widgets library

Widget system for composable TUI components.

This library re-exports the widget API from the artisanal_widgets package for backward compatibility.

Classes

AccentPanel
A panel with a colored vertical accent stripe on one side.
AccentPanelThemeData
Theme data for AccentPanel widgets.
Accordion
ActionButton
A compact, styled button designed for use in dialog footers and inline prompt panels.
ActionChip
Flutter-style action chip.
AlertBox
Align
Alignment
AlwaysStoppedAnimation<T>
An Animation that is always stopped at a given value.
Animatable<T>
Transforms a double (typically from an Animation<double>) into a value of type T.
AnimatedBuilder
A general-purpose widget that rebuilds whenever a Listenable notifies.
AnimatedTint
A widget that applies an animated color tint over its child.
AnimatedWidgetBaseState<T extends ImplicitlyAnimatedWidget>
Base state class for ImplicitlyAnimatedWidget.
Animation<T>
An animation with a value of type T.
AnimationController
A TEA-native animation controller.
AnimationTickMsg
Message delivered on each animation frame tick.
AsciiFont
Abstract base class for ASCII art fonts.
AsciiGlyph
Represents a single ASCII art character glyph.
AsciiText
A widget that renders text using large ASCII art font glyphs.
AsyncSnapshot<T>
Badge
BarChart
A vertical bar chart (histogram) widget.
BlockFocus
A widget that blocks keyboard events from reaching its children.
BorderRadius
BoxConstraints
Box constraints for layout.
BoxDecoration
BuildContext
An opaque handle to location in the widget tree.
Builder
A widget that delegates its build to a callback.
BuildOwner
Schedules and rebuilds dirty elements.
Button
Card
Center
ChangeNotifier
A Listenable implementation that stores listeners and can notify them.
ChartBuilder
A convenience widget that rebuilds whenever a ChartModel changes.
ChartModel
An observable data model for driving chart widget rebuilds.
ChartSeries
A named data series for use in charts that support multiple series.
Checkbox
CheckboxListTile
Flutter-style checkbox list tile.
CheckedPopupMenuItem<T>
A selectable menu entry with a check indicator.
Chip
Flutter-style non-interactive chip.
ChoiceChip
Flutter-style single-select chip.
CircularProgressIndicator
Flutter-style circular progress indicator.
ClipRect
A widget that clips its child to its allocated size.
ColoredBox
A widget that fills its area with a single solid color.
Column
CommandPalette
A searchable, grouped list displayed in a modal overlay.
CommandPaletteItem
A single item in a CommandPalette.
CommandPaletteThemeData
Theme data for CommandPalette widgets.
ConstantTween<T>
A tween that always returns the same constant value.
ConstrainedBox
Container
Cubic
A cubic Bezier curve defined by two control points.
Curve
A mapping of the unit interval to the unit interval.
Curves
A collection of common animation curves.
CurveTween
An Animatable that applies a Curve to the input value.
DataTable
A simple data table widget that renders tabular data with column headers, row separators, and optional theming.
DebugOverlay
A debug overlay that displays rendering metrics.
DecoratedBox
A widget that paints a Decoration either behind or in front of its child.
Decoration
DialogAlert
A simple alert dialog with a title, message, and OK button.
DialogConfirm
A simple yes/no confirmation dialog.
DialogPrompt
A dialog with a text input field.
DialogSelect<T>
A generic searchable, grouped selection list dialog.
DialogSelectItem<T>
A single item in a DialogSelect list.
DialogStack
Manages a stack of modal dialogs.
DialogStackState
State for DialogStack, providing the push/pop/replace/clear API.
DialogThemeData
Theme data for dialog widgets (DialogConfirm, DialogAlert, DialogPrompt, DialogSelect).
DiffFile
A file entry in a parsed diff.
DiffStyles
Configuration for diff styling.
Divider
DoubleTapGestureRecognizer
Recognizes double-tap gestures.
DoubleTween
An explicit double tween (mostly for documentation clarity).
DragEndDetails
Details for the end of a drag gesture.
DragGestureRecognizer
Recognizes drag gestures.
DragStartDetails
Details for the start of a drag gesture.
DragUpdateDetails
Details for a drag update event.
Drawer
Flutter-style dropdown button wrapper.
Flutter-style dropdown menu item.
EdgeInsets
ElasticInCurve
An elastic curve that overshoots and then oscillates at the start.
ElasticInOutCurve
An elastic curve that overshoots and oscillates at both ends.
ElasticOutCurve
An elastic curve that overshoots and then oscillates at the end.
Element
A mounted widget instance in the tree.
ElementTree
Owns an element tree and provides rendering.
ElevatedButton
Flutter-style elevated button wrapper.
ErrorThrowingWidget
A widget that deliberately throws during build.
Expanded
ExpansionTile
Flutter-style expansion tile built on top of ListTile.
FadeModalBarrier
A modal barrier that fades in/out with an animated opacity.
FadeTint
A widget that fades a tint in or out over its child.
FileImage
An ImageProvider that loads an image from a file path.
FilledButton
Flutter-style filled button wrapper.
FilterChip
Flutter-style multi-select chip.
Flex
Flexible
FlexParentData
Parent-data used by flex containers for each child render object.
FlippedCurve
A curve that is the reverse of another curve.
Focusable
A widget that responds to keyboard input when focused.
FocusController
Controls which focusable widget is currently focused.
FocusScope
Provides a FocusController to descendants.
Frame
FutureBuilder<T>
GestureArenaManager
Manages gesture arenas for conflict resolution.
GestureDetector
GestureRecognizer
Abstract base class for all gesture recognizers.
GitDiffController
Controller for GitDiffViewer.
GitDiffModel
A git diff viewer bubble.
GitDiffThemeData
Theme data for GitDiffViewer widgets.
GitDiffViewer
A widget for viewing git diffs with syntax highlighting and scrolling.
Gradient
HBox
HeatmapChart
A 2D heatmap widget that maps grid values to colours via a ChartRamp.
HitTestElementEntry
Result of an element-level hit test — pairs an Element with the local coordinates at which its render object was hit.
HitTestEntry
A single entry in a HitTestResult, linking a render object to the local coordinates at which it was hit.
HitTestResult
Accumulated result of a hit test, ordered deepest-first.
HyperlinkText
A text widget that renders as a clickable hyperlink using OSC 8 escape sequences in terminals that support them.
Icon
IconButton
Flutter-style icon button wrapper.
IconData
Icons
IgnorePointer
A widget that is invisible to hit-testing.
Image
A widget that displays an image in the terminal.
ImageData
Data class holding a decoded image.
ImageProvider
Abstract base class for providing images to the Image widget.
ImplicitlyAnimatedWidget
Abstract base class for widgets that implicitly animate when their properties change.
InheritedElement
Element implementation for InheritedWidget nodes.
InheritedWidget
A widget that exposes data to descendants.
InputChip
Flutter-style input chip.
Interval
An interval that starts and/or ends at a fractional point along the curve.
IntTween
A tween that interpolates between two integers.
Key
A Key is an identifier for Widgets.
KeyboardListener
A widget that calls a callback when a key is pressed.
KeyHint
A small widget that displays a keyboard shortcut key and its label.
Label
LayoutBuilder
A widget that provides its parent's constraints to a builder callback.
LeafRenderObjectWidget
A render object widget with no children.
LimitedBox
A box that limits its size only when it's unconstrained.
LinearProgressIndicator
Flutter-style linear progress indicator.
LineChart
A multi-point line chart widget with optional markers, grid, and axis labels.
Listenable
An object that maintains a list of listeners.
ListenableBuilder
A widget that rebuilds when a Listenable changes.
ListTile
ListView
ListViewController
Controller for scroll position in VirtualListView.
LocalKey
A key that is not a GlobalKey.
LoggingNavigatorObserver
A NavigatorObserver that logs navigation events to the console.
LongPressEndDetails
Details for the end of a long-press gesture.
LongPressGestureRecognizer
Recognizes long-press gestures.
LongPressStartDetails
Details for the start of a long-press gesture.
MarkdownText
A widget that renders Markdown content as styled ANSI text.
MediaQuery
MediaQueryData
MemoryImage
An ImageProvider that loads an image from raw bytes.
MetricDisplay
A single-value metric display widget.
ModalRoute<T>
A modal overlay route with an optional barrier.
MouseRegion
MultiChildRenderObjectWidget
A render object widget with multiple children.
A widget that manages a stack of Route objects.
An interface for observing the behavior of a Navigator.
State for Navigator, providing route stack management.
Offset
An offset in terminal cell units (column, row).
Opacity
OpenCodeThemes
All 33 OpenCode themes, ported from the official JSON definitions.
OutlinedButton
Flutter-style outlined button wrapper.
OverflowBox
A widget that imposes different constraints on its child than it gets from its parent, possibly allowing the child to overflow the parent.
Overlay
A widget that manages a stack of OverlayEntry objects.
OverlayEntry
An entry in an Overlay.
OverlayState
State for Overlay, providing methods to insert and remove entries.
Padding
PageRoute<T>
A full-screen page route.
Pagination
PanelBox
PerformanceMetricsSnapshot
Combined snapshot of both runtime and widget-level metrics.
PerformanceOverlay
A simpler variant of DebugOverlay that only shows render timing.
PieChart
A pie or donut chart widget.
PopBehavior
Configuration for how a Navigator handles pop requests via keyboard.
PopupMenuButton<T>
Flutter-style popup menu button.
PopupMenuDivider<T>
A non-selectable divider entry for PopupMenuButton.
PopupMenuEntry<T>
Base class for entries used in PopupMenuButton.
PopupMenuItem<T>
A selectable menu entry for PopupMenuButton.
Positioned
ProgressIndicator
PromptFooterBar
A footer bar for inline prompt panels and dialog bottoms.
ProxyAnimation
An Animation that proxies another animation.
Radio<T>
RadioListTile<T>
Flutter-style radio list tile.
RangeSlider
Flutter-style range slider for selecting a start/end interval.
RangeValues
Immutable pair of values used by RangeSlider.
Rect
A rectangle defined by offset + size, in terminal cell units.
RenderAlign
RenderBox
A render object with box constraints.
RenderColumn
A vertical column layout.
RenderConstrainedBox
RenderContainer
RenderDelegateBox
A render box that delegates paint to a callback.
RenderIgnorePointer
A render object that never reports a hit, causing hit-testing to skip its subtree and continue to siblings in the parent's child list.
RenderListViewport
Render object backing VirtualListView.
RenderListViewScrollViewport
Render object for _ListViewViewport.
RenderMetricsHolder
Mutable holder for RenderMetrics that WidgetApp updates in-place.
RenderMetricsInjection
A portable render-metrics update payload.
RenderMetricsInjector
Global bus for injecting render metrics from anywhere.
RenderMetricsProvider
Provides RenderMetricsHolder to the widget tree via InheritedWidget.
RenderObject
A render object represents a layout/paintable node.
RenderObjectElement
Element for render object widgets.
RenderObjectWidget
Base class for widgets that create render objects.
RenderPadding
RenderRow
A horizontal row layout.
RenderScrollbar
Render object that draws a vertical scrollbar next to or over child content.
RenderSelectableText
A render object that paints text with optional selection highlighting.
RenderSingleChildViewport
Render object for _SingleChildViewport.
RenderSizedBox
RenderStack
RenderText
Renders a text string with constraints.
RenderViewport
Render object backing Viewport.
RenderWrap
ReverseTween<T>
A tween that evaluates another tween in reverse.
RibbonChart
A stacked area (ribbon) chart widget for visualising multiple data series.
RichText
A widget that displays styled text using a TextSpan tree.
Route<T>
Abstract base class for routes managed by a Navigator.
RouteSettings
Immutable route metadata.
Row
SawTooth
A sawtooth curve that repeats count times over the unit interval.
ScrollArea
A convenience widget that wraps SingleChildScrollView with optional sizing and an optional Scrollbar.
Scrollbar
A scrollbar that decorates a scrollable child.
ScrollbarGradient
A vertical gradient for scrollbar tracks or thumbs.
ScrollController
Scroll controller interface for scrollable widgets.
ScrollView
A scrollable container for a single child widget.
Select<T>
SelectableText
A text widget that supports click-drag selection and Ctrl+C copy.
SelectionArea
Provides a shared SelectionController to descendant SelectableText widgets, enabling cross-widget text selection.
SelectionController
Manages text selection state independently of scroll.
SelectOption<T>
ShrinkWrap
SingleChildRenderObjectWidget
A render object widget with a single child.
SingleChildScrollView
A scrollable container for a single child widget.
Size
Size in terminal cell units.
SizedBox
SizedOverflowBox
A widget that is a specific size but passes its original constraints through to its child, which may then overflow.
Slider
Flutter-style slider for selecting a single value.
Spacer
SparklineChart
A compact sparkline widget rendered with Unicode block characters.
SpinnerIndicator
SplitView
Stack
StackParentData
State<T extends StatefulWidget>
Mutable state for a StatefulWidget.
StatefulElement
Element implementation for StatefulWidget nodes.
StatefulWidget
A widget with mutable state managed by a State object.
StatelessElement
Element implementation for StatelessWidget nodes.
StatelessWidget
A widget with a build method and no mutable state.
StaticWidget
A simple widget that wraps a static string or View.
StatusBar
A horizontal bar that displays a row of KeyHint items.
StatusBarThemeData
Theme data for StatusBar widgets.
StepIndicator
A step-by-step progress indicator widget.
StepItem
A single step in a StepIndicator.
StepTween
A tween that floors the interpolated value to an integer.
StreamBuilder<T>
StyledAsciiText
A convenience wrapper that applies a Style to AsciiText.
Switch
SwitchListTile
Flutter-style switch list tile.
TabItem
Tabs
TapDownDetails
Details for a tap-down event.
TapGestureRecognizer
Recognizes single-tap gestures.
TapUpDetails
Details for a tap-up event.
Text
TextButton
Flutter-style text button wrapper.
TextEditingController
Controls the state of a TextField.
TextEditingValue
The current state of a text field.
TextField
A text input widget supporting single-line and multi-line editing.
TextSelection
Range of text that is selected.
TextSpan
Theme
Theme containing semantic colors, text styles, and component themes.
ThemeScope
Provides a theme to descendant widgets via the build context.
Threshold
A curve that jumps from 0.0 to 1.0 when t passes threshold.
Tint
A widget that applies a color tint over its child.
Toast
Tooltip
Transform
A widget that applies spatial transformations to its child.
TreeView
A hierarchical tree view widget.
TreeViewNode
A node in a TreeView widget.
TUIErrorWidget
A widget that displays an error message with red styling.
Tween<T extends dynamic>
A linear interpolation between a begin and end value.
TweenSequence<T>
An Animatable that chains multiple tweens end-to-end with proportional durations.
TweenSequenceItem<T>
A single entry in a TweenSequence.
UniqueKey
A key that is only equal to itself.
ValueKey<T>
A key that uses a value of a particular type to identify itself.
ValueListenable<T>
A Listenable that exposes a current value.
ValueListenableBuilder<T>
A widget that rebuilds when a ValueListenable changes its value.
ValueNotifier<T>
A ChangeNotifier that holds a single value and notifies when it changes.
VBox
VerticalDivider
A vertical line divider.
Viewport
A string-backed scrollable viewport powered by ViewportModel.
ViewportController
Controller for Viewport.
VirtualListView
A render-object driven list view that only paints visible items.
Visibility
Widget
Base class for composable TUI widgets.
WidgetApp
Runs a widget tree using an element hierarchy.
WidgetElement
Default element for widgets without render objects.
WidgetFrameTiming
Per-frame timing data from the widget layer.
WidgetScrollController
A simple ScrollController for use with SingleChildScrollView, ScrollView, and ListView.
Wrap
Zone

Enums

AccentSide
The side on which the accent stripe is drawn.
AlertVariant
AnimationStatus
The status of an animation.
AsyncConnectionState
Axis
BoxFit
How an image should be inscribed into a box.
ButtonSize
ButtonVariant
ChartLegendPosition
Placement for chart legends rendered inside chart bounds.
ChartType
Enumerates the supported chart types.
CrossAxisAlignment
DataTableBorderStyle
Border style for DataTable.
DebugOverlayPosition
Position options for the debug overlay.
DecorationPosition
Where to paint a decoration relative to the child.
DiffViewMode
The display mode for the diff viewer.
FlexFit
GestureDisposition
The final disposition of a recognizer in the arena.
GestureRecognizerState
The lifecycle state of a gesture recognizer.
HitTestBehavior
Controls how a widget behaves during hit testing.
ListTileControlAffinity
Position of the control in list-tile-style rows.
MainAxisAlignment
MainAxisSize
MetricTrend
Trend direction for a MetricDisplay.
Overflow
ProgressLabelPosition
Where to display the percentage label relative to the bar.
ProgressStyle
Predefined fill/track character sets for ProgressIndicator.
RenderCrossAxisAlignment
Alignment policy along the cross axis for flex layouts.
RenderFlexFit
Fit behavior for flex children.
RenderMainAxisAlignment
Horizontal/vertical alignment policy along the main axis for flex layouts.
RenderMainAxisSize
How much space a flex layout should consume on its main axis.
SidebarSide
StackFit
StepStatus
Status of a single step in a StepIndicator.
TextAlign
TextOverflow
TooltipPosition
WrapAlignment
WrapCrossAlignment

Mixins

AnimationMixin<T extends StatefulWidget>
Mixin for State classes that host one or more AnimationControllers.
FocusableWidget
Mixin for widgets that need to track focus state.

Extensions

ThemeContext on BuildContext
Convenience accessors for theme lookup on BuildContext.

Properties

currentTheme → Theme
Returns the current global theme.
no setter
hasDarkBackground → bool
Whether the terminal has a dark background.
no setter

Functions

createElement(Widget widget) → Element
Creates an element for a widget.
elementOf(Widget widget) → Element?
Returns the mounted Element associated with widget, if any.
keyToIdOrFallback(Key? key, Object fallback) → String
Returns a stable string ID for a possibly-null key.
setHasDarkBackground(bool value) → void
Updates the dark background state.
setTheme(Theme theme) → void
Sets the global theme.
shortHash(Object? object) → String
Short 5-hex hash for diagnostics.
updateThemeFromBackground(String? hex) → void
Updates theme based on background hex color (e.g., '#1a1a1a').

Typedefs

AnimationStatusListener = void Function(AnimationStatus status)
Signature for callbacks that receive AnimationStatus changes.
AsyncWidgetBuilder<T> = Widget Function(BuildContext context, AsyncSnapshot<T> snapshot)
CmdCallback = Cmd? Function()
FocusChangedCallback = void Function(bool focused)
FocusKeyCallback = Cmd? Function(KeyMsg msg)
FocusListener = void Function()
GestureDoubleTapCallback = Cmd? Function()
Callback for double-tap events.
GestureDragEndCallback = Cmd? Function(DragEndDetails details)
Callback for the end of a drag gesture.
GestureDragStartCallback = Cmd? Function(DragStartDetails details)
Callback for the start of a drag gesture.
GestureDragUpdateCallback = Cmd? Function(DragUpdateDetails details)
Callback for drag update events.
GestureLongPressCallback = Cmd? Function()
Callback for long-press events.
GestureLongPressEndCallback = Cmd? Function(LongPressEndDetails details)
Callback for the end of a long-press gesture.
GestureLongPressStartCallback = Cmd? Function(LongPressStartDetails details)
Callback for the start of a long-press gesture.
GestureTapCallback = Cmd? Function()
Callback for simple tap events (press + release within slop).
GestureTapCancelCallback = Cmd? Function()
Callback for tap cancellation (pointer moved beyond slop).
GestureTapDownCallback = Cmd? Function(TapDownDetails details)
Callback for tap-down events with position and modifier details.
GestureTapUpCallback = Cmd? Function(TapUpDetails details)
Callback for tap-up events with position details.
GestureWheelCallback = Cmd? Function(MouseMsg msg)
Callback for mouse wheel events (passes through raw MouseMsg).
IndexedSeparatorBuilder = Widget Function(BuildContext context, int index)
IndexedWidgetBuilder = Widget Function(BuildContext context, int index)
A scrollable list of child widgets.
MouseEnterCallback = Cmd? Function(MouseMsg msg)
Callback for mouse enter events.
MouseExitCallback = Cmd? Function(MouseMsg msg)
Callback for mouse exit events.
RouteFactory = Route? Function(RouteSettings settings)
A factory function that creates a route from settings.
RouteWidgetBuilder = Widget Function(BuildContext context)
A builder that creates a widget for a route.
TextChangedCallback = void Function(String value)
Signature for text change notifications from TextField.
TextFieldController = TextEditingController
Alias for TextEditingController for backward compatibility.
TweenConstructor = Tween Function(dynamic value)
Callback type for constructing a new Tween from a target value.
TweenVisitor = Tween? Function(Tween? tween, dynamic targetValue, TweenConstructor constructor)
Callback type for visiting tweens in AnimatedWidgetBaseState.forEachTween.
ValueCmdCallback<T> = Cmd? Function(T value)
VoidCallback = void Function()
WidgetFrameTimingCallback = void Function(WidgetFrameTiming timing)
Callback for per-frame widget-level timing data.

Exceptions / Errors

FlutterError
Simple error class for widget framework errors.