Component Catalog

Component Catalog

This document maps every public component from layrz_theme to its planned layrz_ui equivalent, assigning milestones and identifying blockers.

About This Document

layrz_ui is a clean-break rewrite, not a drop-in replacement for layrz_theme. The architecture is different (separate files instead of part/part of), naming is different (Layrz* instead of Themed*), and some components are deferred or redesigned.

This catalog answers:

• What exists in layrz_theme? (70+ components)
• When will layrz_ui have an equivalent? (Milestone 1–7)
• What's the relationship? (ports, redesigns, or defers)
• What blockers prevent shipping? (upstream dependencies, Material coupling)

Note on Naming Conventions

Every form field in layrz_ui is named Layrz*Input, regardless of how it collects its value. The *Picker suffix from layrz_theme is retired entirely. All layrz_ui identifiers use the settled Layrz* prefix convention. For full details on the input family architecture and shared contract, see Input Contract.

Reading This Table

layrz_theme Name	layrz_ui Name	Milestone	Built On	Notes

• layrz_theme Name: The component as it exists today in layrz_theme
• layrz_ui Name: The planned name in layrz_ui (always Layrz*, no aliases)
• Milestone: M1 (foundation), M2–M6 (phased components), M7 (blocked)
• Built On: Which SDK primitive it leverages (or "hand-rolled" if none)
• Notes: Structural changes, design choices, or blockers

---

Domain: Buttons

layrz_theme	layrz_ui	M	Built On	Notes
ThemedButton	LayrzButton	M2	RawTooltip + FocusableActionDetector + GestureDetector + AnimatedContainer	Six styles (elevated, elevated fab, outlined, outlined fab, outlinedTonal, outlinedTonal fab); six semantic factories (save, cancel, info, show, edit, delete) with style: parameter replacing isElevated; optional LayrzButtonController for busy state; LayrzButtonType semantic colors; D15 interaction states with fill ladder; D27 style trim from 12 to 6
ThemedActionButton	LayrzActionButton	M2	LayrzButton	Icon-only action button; may be a factory on LayrzButton
ThemedActionsButtons	LayrzActionsButtons	M2	LayrzButton	Horizontal button group
ThemedAnimatedCheckbox	LayrzAnimatedCheckbox	M2	ToggleableStateMixin	Animated checkbox state; integrate with M3 LayrzCheckboxInput
ThemedButtonStyle	(removed)	—	—	Styling is via LayrzThemeExtension

---

Domain: Inputs (General)

layrz_theme	layrz_ui	M	Built On	Notes
ThemedTextInput	LayrzTextInput	M3	EditableText	Single-line and multiline textarea
ThemedSelectInput	LayrzSelectInput	M3	RawAutocomplete	Searchable dropdown, single selection
ThemedMultiSelectInput	LayrzMultiSelectInput	M3	RawAutocomplete	Searchable dropdown, multi-selection
ThemedNumberInput	LayrzNumberInput	M3	EditableText	Min/max bounds, step buttons, decimal formatting
ThemedPasswordInput	LayrzPasswordInput	M3	EditableText	Strength indicator, show/hide toggle
ThemedCheckboxInput	LayrzCheckboxInput	M3	ToggleableStateMixin	Checkbox, switch, dropdown field styles
ThemedRadioInput	LayrzRadioInput	M3	RawRadio	Radio button group with responsive grid layout
ThemedSearchInput	LayrzSearchInput	M3	EditableText	Inline or expandable search bar
ThemedDualListInput	LayrzDualListInput	M3	EditableText	Two-panel available/selected list
ThemedDurationInput	LayrzDurationInput	M3	LayrzNumberInput	Duration picker (days, hours, minutes, seconds)
ThemedDynamicAvatarInput	LayrzDynamicAvatarInput	M4	LayrzAvatarInput	URL, base64 upload, icon, or emoji
ThemedDynamicCredentialsInput	LayrzDynamicCredentialsInput	M7	—	Deferred: requires layrz_models decoupling
ThemedCodeEditor	LayrzCodeEditor	M7	—	Deferred: code_text_field 1.1.0 is Material-built
InputLikeContainer	LayrzInputContainer	M3	Container	Consistent input styling wrapper
SelectItem	LayrzSelectItem	M3	—	Data class for select options
FieldError	LayrzFieldError	M3	—	Error display for form fields

---

Domain: Pickers (Inputs with Selection Surfaces)

The M4 "Pickers" group name refers to the interaction pattern — inputs that open a selection surface. None of these components are named *Picker; they all use the *Input suffix (see Note on Naming Conventions above). They compose LayrzTextInput internally, rendered read-only, with the selection surface opening on tap.

See Input Contract for the architectural requirement that LayrzTextInput ships first in M3 and is the base for all M4 inputs.

layrz_theme	layrz_ui	M	Built On	Notes
ThemedDatePicker	LayrzDateInput	M4	RawDialogRoute	Single date selection
ThemedDateRangePicker	LayrzDateRangeInput	M4	RawDialogRoute	Start and end date
ThemedTimePicker	LayrzTimeInput	M4	RawDialogRoute	Single time-of-day
ThemedTimeRangePicker	LayrzTimeRangeInput	M4	RawDialogRoute	Start and end time
ThemedDateTimePicker	LayrzDateTimeInput	M4	RawDialogRoute	Date + time in tabbed dialog
ThemedDateTimeRangePicker	LayrzDateTimeRangeInput	M4	RawDialogRoute	Start and end datetime
ThemedDateTimeSteppedPicker	LayrzDateTimeSteppedInput	M4	RawDialogRoute	Calendar first, then time picker
ThemedMonthPicker	LayrzMonthInput	M4	RawDialogRoute	Month + year grid with navigation
ThemedMonthRangePicker	LayrzMonthRangeInput	M4	RawDialogRoute	Multi-month or consecutive range
ThemedColorPicker	LayrzColorInput	M4	CustomPaint	Hand-rolled replacement for flex_color_picker (Material-built)
ThemedEmojiPicker	LayrzEmojiInput	M4	RawDialogRoute	Emoji selection from Unicode groups
ThemedAvatarPicker	LayrzAvatarInput	M4	—	System image picker, returns base64
ThemedFilePicker	LayrzFileInput	M4	—	System file browser, returns base64 + bytes
ThemedIconPicker	LayrzIconInput	M4	RawDialogRoute	Layrz icon selection (Solar icon set)

---

Domain: Menus and Navigation

layrz_theme	layrz_ui	M	Built On	Notes
(no predecessor)	LayrzDropdownMenu	M2	RawMenuAnchor	Popup menu with sealed item hierarchy (Entry, Label); builder-based trigger; keyboard accessible; fade + translate enter, no exit animation
(no predecessor)	LayrzDropdownItem (sealed)	M2	—	Base sealed class for menu items
(no predecessor)	LayrzDropdownEntry	M2	—	Interactive menu entry with label, optional icon, optional color dot, optional shortcut (display-only)
(no predecessor)	LayrzDropdownLabel	M2	—	Non-interactive section label with surface3 background
(no predecessor)	LayrzDropdownMenuAlignment	M2	—	Enum: start, center, end
ThemedNavigatorPage	LayrzNavigatorPage	M5	PageRoute	Custom page transition wrapping
ThemedNavigatorAction	LayrzNavigatorAction	M5	—	Action callback in navigator
ThemedNavigatorWidget	LayrzNavigatorWidget	M5	—	Custom navigator item rendering
ThemedNavigatorSeparator	LayrzNavigatorSeparator	M5	—	Visual separator between nav items
ThemedNavigatorLabel	LayrzNavigatorLabel	M5	—	Text label in navigator
ThemedNavigatorItem	LayrzNavigatorItem	M5	—	Base type for nav items (page, action, widget, separator, label)
ThemedNotificationItem	LayrzNotificationItem	M5	—	Toast/notification appearance
ThemedNavigatorSeparatorType	LayrzNavigatorSeparatorType	M5	—	Enum: horizontal, vertical, etc.
(App bar)	LayrzAppBar	M5	Container	Top navigation bar
(Side nav)	LayrzSideNavigation	M5	Column	Side navigation panel
(Bottom nav)	LayrzBottomNavigation	M5	Row	Bottom navigation bar
(Mini nav)	LayrzMiniNavigation	M5	—	Compact floating nav
(Dual nav)	LayrzDualNavigation	M5	—	Two-level navigation (side + top)

---

---

Domain: Data (Chips, Tables)

layrz_theme	layrz_ui	M	Built On	Notes
ThemedChip	LayrzChip	M2	Container	Compact visual label widget (no selection state)
ThemedChipGroup	LayrzChipGroup	M2	SingleChildScrollView + Row	Multiple chips in a row with overflow handling
ThemedChipStyle	LayrzChipStyle	M2	—	Enum: filled, outlined, filledTonal; D28 trim to three values (visual-only chips)
ThemedChipGroupBehavior	LayrzChipGroupBehavior	M2	—	Enum: none (scrolls), compact (clamps with +N overflow)
ThemedTable (legacy)	(removed)	—	—	Superseded by table2; do not port
ThemedColumn	(removed)	—	—	Superseded by table2; do not port
ThemedTableAction	(removed)	—	—	Superseded by table2; do not port
ThemedTableAvatar	(removed)	—	—	Superseded by table2; do not port
ThemedTable2	LayrzTable	M6	—	Data table with sort, search, multiselect, row actions
ThemedColumn2	LayrzColumn	M6	—	Column definition for table
ThemedTable2Controller	LayrzTableController	M6	—	State management for table
ThemedTable2Event	LayrzTableEvent	M6	—	Event base class (sort, search, refresh, etc.)
ThemedTable2OnTapBehavior	LayrzTableOnTapBehavior	M6	—	Enum: none, row select, custom action

---

Domain: Feedback (Alerts, Tooltips, Snackbars)

layrz_theme	layrz_ui	M	Built On	Notes
ThemedAlert	LayrzAlert	M2	Container	Inline status callout (info/success/warning/danger/context); split-panel layout always
ThemedAlertIcon	LayrzAlertIcon	M2	—	Icon display for alert
ThemedAlertStyle	LayrzAlertStyle	M2	—	Enum: layrz, filledIcon (all split-panel); D27 style trim from 5 to 2
ThemedAlertType	LayrzAlertType	M2	—	Enum: info, success, warning, danger, context, custom
ThemedTooltip	LayrzTooltip	M2	RawTooltip	Hover hint text
ThemedTooltipPosition	LayrzPreferredSide	M2	—	Enum: top, bottom, left, right — shared across tooltips and anchored panels
ThemedSnackbar	LayrzSnackbar	M5	OverlayEntry	Transient feedback message
ThemedSnackbarMessenger	LayrzSnackbarMessenger	M5	—	Root widget for snackbar system
ThemedSnackbarType	LayrzSnackbarType	M5	—	Enum: info, success, warning, danger

---

Domain: Selection

layrz_theme	layrz_ui	M	Built On	Notes
(no predecessor)	LayrzSelectableAction	M2	—	Data class representing a text selection toolbar action (copy, cut, paste, select all, or custom). Built-in actions dedupe by kind; custom actions dedupe by identity. Set is intersected with field state to suppress actions not applicable (e.g., copy from obscured field). See Input Contract.
(no predecessor)	LayrzTextSelectionControls	M2	TextSelectionControls + TextSelectionHandleControls	Singleton providing selection handles and toolbar integration for EditableText. Handles are teardrop-shaped, colored primary, rotated to point at selection. Toolbar shows copy, cut, paste, select all, and custom actions.
(no predecessor)	LayrzSelectionToolbar	M2	CustomSingleChildLayout	Dark overlay toolbar (fg1 background, sf1 content) showing action buttons above/below selection. Horizontal scroll when content exceeds width.
(no predecessor)	LayrzSelectionMagnifier	M2	RawMagnifier	Touch-only magnifier (1.25× scale default) that tracks finger during long-press+drag text selection. Shows magnified text under finger.
(no predecessor)	LayrzSelectionHandlePainter	M2	CustomPainter	Renders teardrop-shaped selection handle glyph. Unrotated corner points NW; rotated clockwise for left (NE), right (NW), collapsed (N) handle types.

---

Domain: Display and Text

layrz_theme	layrz_ui	M	Built On	Notes
(no predecessor)	LayrzText	—	SelectableRegion	Removed in 0.0.12. Text selection is now owned by LayrzLayout (SelectableRegion) and LayrzTextInput (EditableText).
ThemedAvatar	LayrzAvatar	M2	—	User avatar (image or initials)
ThemedImage	LayrzImage	M2	Image	Optimized image with fallback
(no predecessor)	LayrzCard	M2	hand-rolled	Elevated surface container with optional interactive behavior; five discrete elevation levels; no outer margin
ThemedCalendar	LayrzCalendar	M6	CustomPaint	Month view with event rendering
ThemedCalendarMode	LayrzCalendarMode	M6	—	Enum: month, week, day
ThemedCalendarEntry	LayrzCalendarEntry	M6	—	Single event in calendar
ThemedCalendarRangeEntry	LayrzCalendarRangeEntry	M6	—	Range event in calendar
ThemedCodeSnippet	LayrzCodeSnippet	M7	—	Deferred: flutter_highlight is Material-built
WorkInProgressView	LayrzWorkInProgressView	M5	—	Placeholder for unfinished features

---

Domain: Application Shells and Navigation

layrz_theme	layrz_ui	M	Built On	Notes
ThemedLayout	LayrzLayout	M5	Container + LayoutBuilder	Single design: sidebar (desktop, 178px) + drawer (mobile, 260px). Navigator items: Page (icon+label+active) and Label (section band) only. No separators, actions, or widgets. User menu via RawMenuAnchor dropdown; notifications in footer. See D37.
(All layout presentations)	(single design only)	M5	—	Dropped by D37: mini-bar, dual-bar, bottom-bar, and separate app bars. Single design handles all breakpoints.
ThemedNavigatorPage	LayrzNavigatorPage	M5	—	Sealed class: page item with label, icon, isSelected flag, optional onTap callback
ThemedNavigatorLabel	LayrzNavigatorLabel	M5	—	Sealed class: section band with label, optional colour
ThemedNavigatorAction	(dropped)	—	—	Dropped by D37. Use LayrzButton in detail area or footer.
ThemedNavigatorWidget	(dropped)	—	—	Dropped by D37. Detail area is consumer-owned.
ThemedNavigatorSeparator	(dropped)	—	—	Dropped by D37. Use LayrzNavigatorLabel for grouping.

---

Domain: Layout Helpers and Scaffolds

layrz_theme	layrz_ui	M	Built On	Notes
ResponsiveRow	LayrzRow	M2	hand-rolled	12-column responsive grid container
ResponsiveCol	LayrzCol	M2	hand-rolled	Column definition within responsive row
—	LayrzConstrainedView	M2	hand-rolled	Width-constrained, horizontally-centred column (new; no predecessor)
Sizes	LayrzSizes	M2	—	Breakpoint names (xs, sm, md, lg, xl)
SizesExt	—	—	—	Removed; breakpoints via constants
Scrollbar	LayrzScrollbar	M5	RawScrollbar	Material-free scrollbar with visible thumb, hidden track on hover. Installed by LayrzApp.scrollBehavior by default. Vertical only; horizontal and touch exempt.
ThemedScaffoldView, ThemedScaffoldCell	LayrzScaffoldShell	M5	Column	Adaptive list-detail shell (merges view and cell into single component with internal pane/sheet swap, container-driven)
ThemedGridDelegateWithFixedHeight	LayrzGridDelegateWithFixedHeight	M6	SliverGridDelegate	Custom grid layout delegate

---

Domain: Theme Utilities

layrz_theme	layrz_ui	M	Built On	Notes
ThemedFontHandler	LayrzFontHandler	M1	google_fonts	Font loading via TextStyle API
ThemedInputBorder	—	—	—	Removed; layrz_ui uses no borders on inputs (InputBorder.none)
ThemedPlatform	LayrzPlatform	M1	—	Runtime platform detection

---

Domain: Tabs

layrz_theme	layrz_ui	M	Built On	Notes
ThemedTab	LayrzTab	M5	—	Single tab definition
ThemedTabView	LayrzTabView	M5	—	Tab container with bar and pages
ThemedTabStyle	LayrzTabStyle	M5	—	Tab styling options

---

Domain: Dialogs and Views

layrz_theme	layrz_ui	M	Built On	Notes
ThemedAboutDialog	LayrzAboutDialog	M5	RawDialogRoute	Standard about dialog
(Generic dialog)	LayrzDialog	M5	showGeneralDialog	Dialog wrapper on RawDialogRoute
(Alert dialog)	LayrzAlertDialog	M5	showGeneralDialog	Confirmation dialog with actions

---

Domain: Map (Blocked)

layrz_theme	layrz_ui	M	Built On	Notes
ThemedMapButton	LayrzMapButton	M7	—	Deferred: no flutter_map replacement exists
ThemedMapDragButton	LayrzMapDragButton	M7	—	Deferred: blocked by flutter_map
(Map layers)	LayrzMapLayer*	M7	—	Deferred
(Map controls)	LayrzMapControl*	M7	—	Deferred
(Map dialogs)	LayrzMapDialog*	M7	—	Deferred

---

Domain: Extensions and Mixins

layrz_theme	layrz_ui	M	Built On	Notes
LayrzOrm	LayrzOrm	M7	—	Deferred: requires layrz_models decoupling
ThemedPageBuilder	LayrzPageBuilder	M5	PageRoute	Generic page route builder
ThemedPageTransition	LayrzPageTransition	M5	PageTransitionsBuilder	Custom page transition mechanics
DateTimeExtension	—	M3	—	Utility methods on DateTime (for pickers)
I18nExtension	—	—	—	i18n helpers; depends on app-level localization
NumToSizedBox	—	—	—	Removed; use SizedBox.square(dimension: num) instead
StylingExtension	LayrzStylingExtension	M6	—	Utility methods on widgets
ThemedColorExtensions	LayrzColorExtensions	M1	—	Hex conversion, contrast, opacity
ColorblindFilter	LayrzColorbindFilter	M7	—	Deferred: awaiting upstream canvas/shader support
VxStateUtilsMixin	—	—	—	Removed; use standard State patterns

---

Summary by Milestone

Milestone 1: Foundation (0 components)

• Token system
• Theme architecture (InheritedTheme migration)
• CI pipeline
• Documentation

Milestone 2: Core Primitives (12 components)

• LayrzButton
• LayrzCard
• LayrzTooltip
• LayrzAlert
• LayrzChip, LayrzChipGroup
• LayrzRow, LayrzCol, LayrzConstrainedView (responsive grid and constrained view)
• LayrzText (selectable text)
• LayrzDropdownMenu (menu with sealed items)
• LayrzAvatar, LayrzImage

Milestone 3: Input Fields (12 components)

Base component ships first: LayrzTextInput is the architectural base for all inputs. Every other input composes it internally rather than reimplementing field chrome. See Input Contract for the shared contract and architectural requirements.

• LayrzTextInput (base for all inputs; must ship first)
• LayrzNumberInput
• LayrzPasswordInput
• LayrzCheckboxInput
• LayrzRadioInput
• LayrzSwitch
• LayrzSelectInput
• LayrzMultiSelectInput
• LayrzSearchInput
• LayrzDualListInput
• LayrzDurationInput
• Support types (LayrzSelectItem, LayrzFieldError, LayrzInputContainer)

Milestone 4: Pickers (Inputs with Selection Surfaces; 15 components)

All M4 components are named Layrz*Input and compose LayrzTextInput internally. The group name "Pickers" refers to the interaction pattern (inputs that open a selection surface), not the naming convention.

• LayrzDateInput
• LayrzDateRangeInput
• LayrzTimeInput
• LayrzTimeRangeInput
• LayrzDateTimeInput
• LayrzDateTimeRangeInput
• LayrzDateTimeSteppedInput
• LayrzMonthInput
• LayrzMonthRangeInput
• LayrzColorInput (hand-rolled)
• LayrzEmojiInput
• LayrzAvatarInput
• LayrzFileInput
• LayrzIconInput
• LayrzDynamicAvatarInput

Milestone 5: Layout, Navigation, Feedback (13 components)

• LayrzLayout (sidebar desktop + drawer mobile, flat nav items)
• LayrzNavigatorPage (page item with icon, label, active flag)
• LayrzNavigatorLabel (section band for grouping)
• LayrzScaffoldShell (adaptive list-detail shell)
• LayrzScrollbar (Material-free scrollbar on RawScrollbar, installed by LayrzApp)
• LayrzTabView, LayrzTab (horizontal tabs, M3 styling)
• LayrzSnackbar, LayrzSnackbarMessenger (transient feedback)
• LayrzDialog, LayrzAlertDialog (modal dialogs on RawDialogRoute)
• LayrzAboutDialog (about dialog)
• LayrzPageBuilder (page route builder)
• LayrzPageTransition (page transition mechanics)
• LayrzNotificationItem (notification display in nav footer)

Milestone 6: Data Display (6 components)

• LayrzTable
• LayrzColumn
• LayrzTableController
• LayrzTableEvent and subclasses
• LayrzCalendar
• LayrzGridDelegateWithFixedHeight
• LayrzStylingExtension

Milestone 7: Blocked / Deferred

• Map ecosystem — blocked on flutter_map replacement (9 components)
• Code editor — blocked on code_text_field replacement
• Code snippet — blocked on flutter_highlight replacement
• Model-bound inputs — blocked on layrz_models decoupling (2 components: DynamicCredentialsInput, Orm)
• Colorblind filter — awaiting upstream canvas/shader support

---

Components Not Being Ported

The following exist in layrz_theme but are not being ported to layrz_ui:

Component	Reason
ThemedTable (legacy)	Superseded by ThemedTable2; table2 is more capable
ThemedInputBorder	layrz_ui inputs use no borders (Material best practice of no-border text fields)
NumToSizedBox	Removed; use SizedBox.square(dimension: num)
VxStateUtilsMixin	Removed; standard State patterns are clearer
I18nExtension	App-level concern, not design system concern

---

Blocked on External Dependencies

These components cannot ship until external dependencies are resolved:

flutter_map Replacement (M7, 9 components)

• Blocking: Map ecosystem
• Impact: ThemedMapButton, ThemedMapDragButton, all map layers/controls/dialogs
• Status: No Material-free flutter_map replacement exists. Options:
  • Write a custom Material-free map library (out of scope for M1–M6)
  • Defer map entirely (current plan)

code_text_field Replacement (M7)

• Blocking: ThemedCodeEditor
• Impact: Code editing widget
• Status: code_text_field 1.1.0 imports Material. Options:
  • Find or write a Material-free alternative
  • Defer code editing (current plan)

flutter_highlight Replacement (M7)

• Blocking: ThemedCodeSnippet
• Impact: Code snippet display widget
• Status: flutter_highlight 0.7.0 imports Material. Options:
  • Use a simpler syntax highlighter (e.g., highlight.dart, which is Material-free)
  • Defer code snippets (current plan)

layrz_models Decoupling (M7, 2 components)

• Blocking: ThemedDynamicCredentialsInput, ThemedOrm
• Impact: Model-bound input widgets, ORM helper
• Status: layrz_models 3.24.7 imports Material in 19 files. Options:
  • Decouple layrz_models from Material (upstream issue)
  • Defer model-bound components until decoupling is complete (current plan)

Canvas/Shader Support (M7)

• Blocking: ColorblindFilter
• Impact: Colorblind accessibility filter
• Status: Awaiting upstream Flutter support for canvas-based filters

---

Structural Changes from layrz_theme

File Organization

• layrz_theme: Uses part/part of with 24 domain files
• layrz_ui: Uses separate files under <module>/src/ with export-only barrels

Impact: Significantly improved modularity and testability. One concern per file prevents 2,000-line monoliths.

Naming

• layrz_theme: Themed* prefix (e.g., ThemedButton)
• layrz_ui: Layrz* prefix (e.g., LayrzButton)

Impact: Clean break. No migration aliases; consuming apps must rename imports.

Styling Approach

• layrz_theme: Hardcoded Material Design language (Material Design colors, Material-style buttons, etc.)
• layrz_ui: Token-based semantic design, entirely customizable, zero Material dependency

Impact: True design system independence. Theming is first-class, not bolted on.

Component API

• layrz_theme: Heavily Material-influenced (Material's TextTheme, Material's button styles, etc.)
• layrz_ui: Design-agnostic, driven by tokens and state management (WidgetState)

Impact: Cleaner, more consistent API across all components.

---

Verification Criteria

For each milestone, the following criteria must be satisfied before shipping:

• All components listed for the milestone are complete
• Each component has full test coverage (light and dark theme, all interactive states)
• Every component parameter is documented per CLAUDE.md rule #1
• No Material or Cupertino imports anywhere in implementation
• Token usage is consistent (no hardcoded colors, spacing, etc.)
• Component integrates with theme system (LayrzTheme, tokens, state resolution)
• Preview annotations are present for visual components

---

Last updated: 2026-08-17