frus-widgets 0.2.1

//! `frus-widgets` — frus's declarative widget tree.
//!
//! An interface is described with composable widgets ([`Container`], [`Flex`],
//! [`Text`], [`TextField`], [`SingleChildScrollView`]) generic over a message type `Msg`, in the
//! Elm/iced message model. [`build_ui`] translates them into a layout, through
//! `frus-layout`, and then into a [`Ui`]: the [`Scene`] to draw, plus the hit-test maps
//! for clicking, focus and scrolling.
//!
//! The state retained between frames — hover and focus, scroll offsets, caret and
//! selection — lives in a [`Runtime`], keyed by widget identity.

#![deny(missing_docs)]

// The README's example is compiled and run by `cargo test --doc`, so it cannot rot.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
pub struct ReadmeDoctests;

mod actionbutton;
mod alert;
mod animated;
mod appbar;
mod aspectratio;
mod autocomplete;
mod autofill;
mod avatar;
mod badge;
mod banner;
mod barrier;
mod baseline;
mod bottomappbar;
mod bottomsheet;
mod breadcrumb;
mod button;
mod callback;
mod card;
mod carousel;
mod chart;
mod checkbox;
mod chip;
mod clip;
mod collapsible;
mod collapsingheader;
mod colorpicker;
mod component;
mod constraints;
mod container;
mod controltile;
mod custompaint;
mod datatable;
mod datepicker;
mod datetimepicker;
mod datetimerange;
mod dialog;
/// The **disabled state** every control shares: two colours and a four-part contract.
pub mod disabled;
/// Swipe-to-dismiss: the [`dismiss::Dismissible`] widget and its retained state.
pub mod dismiss;
mod divider;
mod dragdrop;
mod drawer;
mod drawerheader;
mod dropdown;
mod dropdownmenu;
mod dsl;
mod editing;
mod expanded;
mod expansionpanel;
mod fab;
mod filters;
mod fittedbox;
mod flex;
mod focus;
/// Form validation, pure and application-side: [`form::Rule`] and [`form::Form`].
pub mod form;
mod switcher;
mod system_ui;
pub use form::ErrorSummary;
mod fractional;
mod grid;
mod gridtile;
mod hero;
// Documented inside (`host.rs`): an outer doc comment here would make its links resolve from
// this scope rather than from the module's.
pub mod host;
mod icon;
mod iconbutton;
mod icons;
mod image;
/// The software keyboard's vocabulary: which keys, and what the action key does.
pub mod ime;
mod ink;
mod inspector;
mod interaction;
mod interactive;
mod kanban;
mod kbd;
mod keyed;
mod layoutbuilder;
pub mod licenses;
mod list;
mod listtile;
/// Which language the interface is in: [`locale::Locale`], [`locale::resolve`] and
/// [`locale::of`].
pub mod locale;
/// The words the framework itself says: [`localizations::Localizations`] and [`localizations::of`].
pub mod localizations;
mod media;
mod mediascope;
mod menu;
mod navbar;
mod navdrawer;
mod navigator;
mod navrail;
mod navscaffold;
mod notifier;
mod overflowbar;
mod overscroll;
mod pageselector;
mod pageview;
mod pagination;
mod paintcache;
mod physics;
mod placeholder;
mod popover;
mod portal;
mod positioned;
mod progressbar;
mod radio;
mod rating;
/// Pull-to-refresh: the [`refresh::RefreshIndicator`] widget and its retained pull.
pub mod refresh;
mod relayout;
mod reorder;
mod reorderable;
mod responsive;
mod richtext;
mod rotatedbox;
mod router;
mod rowcolumn;
mod runtime;
mod safearea;
mod scaffold;
mod scaffoldinfo;
mod scroll;
pub mod scrolloverlay;
pub mod scrollposition;
mod searchbar;
mod searchview;
mod segmented;
/// Stating what a widget **is** from outside it: the [`semantics::Semantics`] wrapper.
pub mod semantics;
mod sheet;
mod shortcuts;
mod skeleton;
mod slider;
mod spacer;
mod spinner;
mod stack;
mod stepper;
mod steps;
mod switch;
mod table;
mod tabs;
mod text;
mod textinput;
mod theme;
mod themebuilder;
mod themed;
mod timeline;
mod timepicker;
mod toast;
mod toasthost;
mod togglebuttons;
mod tooltip;
mod transform;
mod transitions;
pub(crate) mod transparent;
mod tree;
mod twopane;
mod ui;
mod undo;
mod wheel;
mod widget;
mod widgetstate;
mod widgettheme;

pub use actionbutton::{BackButton, CloseButton, DrawerButton, EndDrawerButton};
pub use alert::{Alert, AlertKind};
pub use animated::{
    AnimatedAlign, AnimatedContainer, AnimatedDefaultTextStyle, AnimatedFractionallySizedBox,
    AnimatedOpacity, AnimatedPadding, AnimatedPositioned, AnimatedRotation, AnimatedScale,
    AnimatedSlide, Opacity,
};
pub use appbar::{platform_centers_title, AppBar, APP_BAR_HEIGHT, APP_BAR_MAX_TITLE_SCALE};
pub use aspectratio::AspectRatio;
pub use autocomplete::Autocomplete;
pub use autofill::{AutofillGroup, AutofillHint};
pub use avatar::CircleAvatar;
pub use badge::Badge;
pub use banner::{MaterialBanner, BANNER_ELEVATION, BANNER_MIN_ACTION_BAR_HEIGHT};
pub use barrier::{
    AbsorbPointer, ExcludeSemantics, IgnorePointer, ModalBarrier, Offstage, Visibility,
};
pub use baseline::{Baseline, IgnoreBaseline};
pub use bottomappbar::{bar_spacer, notched_outline, BottomAppBar};
pub use bottomsheet::BottomSheet;
pub use breadcrumb::Breadcrumb;
pub use button::{
    Button, Variant, BUTTON_BORDER_WIDTH, BUTTON_ELEVATION, BUTTON_HEIGHT, BUTTON_MIN_WIDTH,
    BUTTON_PADDING, BUTTON_TEXT_PADDING,
};
pub use callback::{Callback, IntoMsg};
pub use card::{Card, CardVariant, CARD_ELEVATION, CARD_MARGIN};
pub use carousel::CarouselView;
pub use chart::{BarChart, LineChart};
pub use checkbox::Checkbox;
pub use chip::{
    Chip, CHIP_BORDER_WIDTH, CHIP_HEIGHT, CHIP_ICON_SIZE, CHIP_LABEL_PADDING, CHIP_PADDING,
    CHIP_RADIUS,
};
pub use clip::{ClipOval, ClipPath, ClipRRect};
pub use collapsible::{ControlAffinity, ExpansionTile};
pub use collapsingheader::{header_rect, CollapsingHeader, HeaderState, COLLAPSED_HEIGHT};
pub use colorpicker::ColorPicker;
pub use component::{
    back_blocked, component, intervals, rebuild_requested, request_rebuild, take_rebuild_request,
    BuildContext, Component, Interval, IntoCleanup, State, StateContext, StateHandle, StateStore,
    StatefulWidget, StatelessWidget, UseRef, UseState,
};
pub use constraints::{
    AxisConstraint, ConstrainedBox, ConstraintsTransform, ConstraintsTransformBox, Intrinsic,
    IntrinsicAxis, IntrinsicHeight, IntrinsicWidth, Overflow, OverflowBox, SizedBox,
    SizedOverflowBox, UnconstrainedBox,
};
pub use container::Container;
pub use controltile::{CheckboxListTile, RadioListTile, SwitchListTile};
pub use custompaint::CustomPaint;
pub use datatable::{
    compare_cells, page_count, page_range_label, page_rows, row_matches, sort_rows, DataTable,
};
pub use datepicker::DatePicker;
pub use datetimepicker::DateTimePicker;
pub use datetimerange::DateTimeRange;
pub use dialog::{
    ActionsAlignment, AlertDialog, Dialog, SimpleDialog, SimpleDialogOption, DIALOG_ELEVATION,
    DIALOG_INSET_PADDING, DIALOG_MIN_WIDTH, DIALOG_RADIUS,
};
pub use disabled::{
    disabled_container, disabled_content, disabled_mark, over_surface, DISABLED_CONTAINER_OPACITY,
    DISABLED_CONTENT_OPACITY,
};
pub use dismiss::{
    DismissAxis, DismissDirection, DismissPhase, DismissSpec, DismissState, Dismissable,
    Dismissible,
};
pub use divider::{Divider, VerticalDivider, DIVIDER_SPACE, DIVIDER_THICKNESS};
pub use dragdrop::{DragSource, DragTarget, Draggable, DropZone};
pub use drawer::{Drawer, DRAWER_RADIUS, DRAWER_WIDTH};
pub use drawerheader::{DrawerHeader, UserAccountsDrawerHeader, DRAWER_HEADER_HEIGHT};
pub use dropdown::{DropdownButton, DropdownOption};
pub use dropdownmenu::DropdownMenu;
pub use dsl::{button, expanded, flexible, keyed, spacer, text};
pub use editing::TextEditingController;
pub use expanded::{Expanded, FlexFit, Flexible};
pub use expansionpanel::{ExpansionPanel, ExpansionPanelList};
pub use fab::{FabSize, FloatingActionButton};
pub use filters::{BackdropFilter, BackdropGroup, ColorFiltered, ImageFiltered, ShaderMask};
pub use fittedbox::FittedBox;
pub use flex::{Flex, ListBody, Wrap};
pub use focus::{
    ExcludeFocus, ExcludeFocusTraversal, Focus, FocusTraversalGroup, FocusTraversalOrder,
};
pub use fractional::FractionallySizedBox;
pub use grid::GridView;
pub use gridtile::{GridTile, GridTileBar, GRID_TILE_BAR_HEIGHT, GRID_TILE_BAR_TWO_LINE_HEIGHT};
pub use hero::{lerp_rect, Hero, HeroSpot};
pub use icon::Icon;
pub use iconbutton::{
    IconButton, IconButtonVariant, ICON_BUTTON_BORDER_WIDTH, ICON_BUTTON_ICON_SIZE,
    ICON_BUTTON_SIZE,
};
pub use icons::{AnimatedIconData, AnimatedIcons, IconData, IconStyle, Icons};
pub use image::{Image, ImageIcon, ImagePlaceholder, State as ImageState, IMAGE_FADE};
pub use ime::{Capitalization, Ime, KeyboardType, TextInputAction};
pub use ink::{InkStyle, InkWell, Ripples};
pub use inspector::{dump_tree, node_at, paint_overlay as paint_inspector_overlay, InspectorNode};
pub use interaction::{Cursor, InputState, Interaction, Key, KeyResponse, Status, WidgetId};
pub use interactive::{InteractiveView, InteractiveViewer};
pub use kanban::{kanban_slot, Kanban};
pub use kbd::Kbd;
pub use keyed::Keyed;
pub use layoutbuilder::LayoutBuilder;
pub use licenses::{AboutDialog, AboutListTile, LicenseNotice, LicensePage, Package};
pub use list::{ListView, VirtualList};
pub use listtile::{
    ListTile, LIST_TILE_DENSE_HEIGHTS, LIST_TILE_HEIGHTS, LIST_TILE_MIN_LEADING_WIDTH,
    LIST_TILE_MIN_VERTICAL_PADDING, LIST_TILE_PADDING_END, LIST_TILE_PADDING_START,
    LIST_TILE_TITLE_GAP,
};
pub use locale::Locale;
pub use localizations::{English, French, Localizations};
pub use media::{
    Accessibility, AccessibilityOverrides, Brightness, Edges, MediaQuery, SurfaceGuard,
};
pub use mediascope::MediaScope;
pub use menu::{MenuItem, PopupMenuButton};
pub use navbar::NavigationBar;
pub use navdrawer::NavigationDrawer;
pub use navigator::Navigator;
pub use navrail::{BottomBar, DestinationIcon, NavigationDestination, NavigationRail, RailLabels};
pub use navscaffold::NavScaffold;
pub use notifier::{ChangeNotifier, Listenable, Subscription, ValueNotifier};
pub use overflowbar::OverflowBar;
pub use overscroll::{
    cross_axis as glow_cross_axis, edge_for, GlowEdge, OverscrollGlow, ScrollGlows,
};
pub use pageselector::{TabPageSelector, PAGE_DOT_GAP, PAGE_DOT_SIZE};
pub use pageview::{PageSnap, PageView, PagedView};
pub use pagination::Pagination;
pub use paintcache::PaintCache;
pub use physics::{
    page_of, page_target, snap_target, Ballistic, ScrollDecelerationRate, ScrollMetrics,
    ScrollPhysics, Scrollbars, CONSTANT_DECELERATION_FAST, MAX_FLING_VELOCITY, MIN_FLING_VELOCITY,
};
pub use placeholder::{Placeholder, PLACEHOLDER_COLOR, PLACEHOLDER_FALLBACK, PLACEHOLDER_STROKE};
pub use popover::MenuAnchor;
pub use portal::{OverlayPortal, Placement};
pub use positioned::{Positioned, Positioning};
pub use progressbar::LinearProgressIndicator;
pub use radio::{Radio, RadioGroup};
pub use rating::Rating;
pub use refresh::{RefreshIndicator, RefreshPhase, RefreshPull, RefreshSpec, Refreshable};
pub use relayout::LayoutCache;
pub use reorder::{
    nearest_reorder_slot, reflow_reorder_cards, reflow_reorder_columns, reorder_drop_after,
};
pub use reorderable::{settled_index, ReorderGrab, ReorderableList};
pub use responsive::{responsive, Responsive};
pub use richtext::RichText;
pub use rotatedbox::RotatedBox;
pub use router::{GoRoute, GoRouter, GoRouterState};
pub use rowcolumn::{Column, MainAxisSize, Row, VerticalDirection};
pub use runtime::{
    spring_ease, spring_step, Anim, Edit, Runtime, ScrollBallistic, ScrollState, ScrollbarFade,
    SelectionHandle, TransformValues, ValueAnim,
};
pub use safearea::SafeArea;
pub use scaffold::{fab_button, FabLocation, NavPlacement, Scaffold};
pub use scaffoldinfo::{ScaffoldGuard, ScaffoldInfo, ScaffoldScope};
pub use scroll::{Axis, SingleChildScrollView};
pub use scrolloverlay::{OverlayBuilder, ScrollOverlay};
pub use scrollposition::{ScrollPosition, ScrollTarget, ScrollTo};
pub use searchbar::{SearchBar, SEARCH_BAR_HEIGHT, SEARCH_BAR_MAX_WIDTH, SEARCH_BAR_MIN_WIDTH};
pub use searchview::{
    SearchAnchor, SEARCH_VIEW_FULL_SCREEN_HEADER, SEARCH_VIEW_MIN_HEIGHT, SEARCH_VIEW_MIN_WIDTH,
    SEARCH_VIEW_RADIUS,
};
pub use segmented::{
    SegmentedButton, SEGMENTED_BORDER_WIDTH, SEGMENTED_HEIGHT, SEGMENTED_ICON_GAP,
    SEGMENTED_ICON_SIZE, SEGMENTED_PADDING,
};
pub use semantics::{Description, Semantics};
pub use sheet::{
    sheet_takes_release, split_sheet_drag, DraggableScrollableSheet, SheetArea, SheetSpec,
    SheetState, SheetTo, SnapSimulation, SHEET_SNAP_MIN_SPEED,
};
pub use shortcuts::{
    ActionListener, Actions, CallbackShortcuts, FocusableActionDetector, Intent, KeyStroke,
    KeyboardListener, ShortcutKey, Shortcuts,
};
pub use skeleton::Skeleton;
pub use slider::{RangeSlider, Slider};
pub use spacer::Spacer;
pub use spinner::CircularProgressIndicator;
pub use stack::{IndexedStack, Stack, StackFit};
pub use stepper::Stepper;
pub use steps::Steps;
pub use switch::Switch;
pub use switcher::AnimatedSwitcher;
pub use system_ui::{AnnotatedRegion, SystemBars, SystemUiOverlayStyle};
pub use table::Table;
pub use tabs::{
    TabAlignment, TabBar, TabBarVariant, TabItem, TAB_DIVIDER_HEIGHT, TAB_HEIGHT, TAB_ICON_GAP,
    TAB_ICON_HEIGHT, TAB_ICON_SIZE, TAB_INDICATOR_PRIMARY, TAB_INDICATOR_SECONDARY,
    TAB_LABEL_PADDING, TAB_START_OFFSET,
};
pub use text::Text;
pub use textinput::{
    TextField, TextFieldStyle, TextFieldVariant, FIELD_BORDER_WIDTH,
    FIELD_DENSE_OUTLINED_PADDING_BOTTOM, FIELD_DENSE_OUTLINED_PADDING_TOP, FIELD_DENSE_PADDING_Y,
    FIELD_DISABLED_OPACITY, FIELD_FOCUSED_BORDER_WIDTH, FIELD_GAP, FIELD_ICON_SIZE,
    FIELD_LABEL_SCALE, FIELD_NOTCH_GAP, FIELD_OUTLINED_PADDING_BOTTOM, FIELD_OUTLINED_PADDING_TOP,
    FIELD_PADDING_X, FIELD_PADDING_Y, FIELD_RADIUS, FIELD_SUB_SIZE, FIELD_TEXT_SIZE,
};
pub use theme::{
    ColorScheme, TapTarget, TextTheme, Theme, ThemeMode, MIN_TAP_TARGET, SHRUNK_TAP_TARGET,
};
pub use themebuilder::ThemeBuilder;
pub use themed::Themed;
pub use timeline::Timeline;
pub use timepicker::{Endpoint, TimeField, TimePicker, TimeRange};
pub use toast::{SnackBar, SnackBarBehavior, SnackBarKind, SnackBarQueue};
pub use toasthost::{ScaffoldMessenger, SnackBarPosition};
pub use togglebuttons::{
    ToggleAxis, ToggleButtons, TOGGLE_BUTTONS_BORDER_WIDTH, TOGGLE_BUTTON_MIN_SIZE,
};
pub use tooltip::Tooltip;
pub use transform::{FractionalTranslation, Transform};
pub use transitions::{
    eased, DecoratedBoxTransition, DecorationPosition, DefaultTextStyleTransition, FadeTransition,
    ScaleTransition, SlideFrom, SlideTransition,
};
pub use tree::Tree;
pub use twopane::TwoPane;
pub use ui::{
    build_deferred, build_ui, build_ui_inspected, collect_ids, find_by_key, find_path,
    find_sheet_by_key, find_widget, reorder_siblings, reorderable_owners, subtree_ids,
    FocusDirection, Focusable, KeepVisible, Scrollable, Scrollbar, Ui,
};
pub use undo::{EditKind, EditSnapshot, UndoHistory, RUN_PAUSE};
pub use wheel::{ListWheel, RowOnWheel, WheelGeometry};
pub use widget::{CellFn, FillAxes, FilterContext, ReorderAxis, Widget};
pub use widgetstate::{StateFilter, WidgetState, WidgetStateProperty, WidgetStates};
// **Every** one of them, and not only the ones a doc link happened to need. A theme
// struct that is `pub` inside a private module is public and unreachable: callers can
// still set `theme.widgets.button.background`, because the field's type is inferred, but
// they cannot name the type — so `AppBar::icon_theme` took an `IconTheme` no caller
// could build from milestone 396 until now. A property that ships unusable is a property
// that did not ship.
pub use widgettheme::resolve_shape;
pub use widgettheme::{
    AppBarTheme, BadgeTheme, ButtonTheme, CardTheme, CheckboxTheme, ChipTheme, DefaultTextStyle,
    DividerTheme, DrawerTheme, DropdownTheme, ExpansionPanelListTheme, GridTileBarTheme,
    IconButtonTheme, IconTheme, InkTheme, MenuTheme, PageSelectorTheme, RadioTheme, SegmentedTheme,
    SliderTheme, SwitchTheme, TabBarTheme, TextFieldTheme, ToggleButtonsTheme, WidgetThemes,
};

// Convenience re-exports for callers.
/// Installing the reader's font size for a whole frame — see
/// [`frus_core::install_text_scale`]. Re-exported for the shell, which has to hold it
/// across the build, the layout **and** the paint.
pub use frus_core::{install_text_scale, TextScaleGuard};
pub use frus_core::{
    Affine, Alignment, AlignmentDirectional, AlignmentGeometry, Backdrop, BlendMode, Border,
    BorderRadius, BoxDecoration, BoxFit, BoxShadow, ClipShape, Color, ColorFilter, Colors,
    FontWeight, FractionalMask, ImageData, ImageFilter, ImageHandle, Insets, InsetsDirectional,
    LinearGradient, MaterialColor, Orientation, Path, PathVerb, Point, Primitive, Rect, Role,
    Scene, SemanticsProperties, Size, SizeClass, TextAlign, TextDecoration, TextDirection,
    TextOverflow, TextSpan, TextStyle, Toggled, WindowInsets,
};
/// The shared animation layer — physics, curves, driver — see
/// [`frus_core::animation`]. Re-exported here so applications can reach it through
/// `frus_widgets` without depending on `frus-core` directly.
pub use frus_core::{
    AnimationController, ClampedSimulation, Curve, FrictionSimulation, Lerp, Simulation,
    SpringDescription, SpringSimulation, Tolerance, Tween, Velocity, VelocityEstimate,
    VelocityStrategy, VelocityTracker,
};
// `frus_core::Status`, an animation's progress, is renamed so it does not shadow the
// interaction `Status`, which is paint state: hover, press, focus and so on.
pub use frus_core::Status as AnimationStatus;

/// The image stores and the two things a host has to name: a decoder is chosen by the
/// `images` feature, and the **fetcher** is registered by whoever has a network. See
/// [`Image::network`].
pub use frus_core::{images_in_flight, set_image_fetcher, ImageFetcher};
pub use frus_layout::{Align, AlignContent, FlexDirection, Justify, Overflowing, Side};