zaniah 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e74156d5d7a3d4ed439e9d46aac5e8fb25b65e974013937dcc1743a5ae1aa665
-  data.tar.gz: ad0468ac4a87fc3181974ad2b905a515b3c414e30df4b190ba07b220c3ecfbc6
+  metadata.gz: f6787d1edc51a6a692859fe62834270cfa2339ade8b00e596e8861632eb59913
+  data.tar.gz: 7407abf9f7a64c80fc307843ffeadd9d130cfb45a12673a85f6cbedf2710a3e4
 SHA512:
-  metadata.gz: f65083c0483107b854879b2303b4bb87d4c05debcaba6167d7335596628d5ccab4d4ccf310d99fd2c10958a3edefa7355d9d9d0229541dc1bc6cba639c8ffc87
-  data.tar.gz: 5881db80886ae7543493bdaebc459301968075b1a41a375e93b0f91a1566829bd5c3169190ff342cfed7e4bd2dc2b573827e7331f2e920a22fd6e2c874d34242
+  metadata.gz: 35cdfc811f06f704d21202e60029c2869eb5b01698c4e52cde3ce2b7c0e45eaa0c6c5a60ec46e9e9f4e15fd2e1b7f88a75b71b9ec829423540259238739cf468
+  data.tar.gz: beaae799ef7227cf30d354819b4d896ee1957666c1617d4a43a15fd8d0112180b0dcf74dadf930c6df8376eaa0045663c83400cca2f6bf019142ab9cb2af0592

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased
+
+## 0.4.0 — 2026-09-15
+
+- Add inline and block text overlays with wrapping-aware layout, hit testing, and row-local relayout.
+
+## 0.3.0 — 2026-09-14
+
+- Improve large flex layouts, GPU scene submission, and software-rendered gradients for smoother frames.
+- Add dark, light, and high-contrast themes with immediate hover, active, focus, and disabled styling.
+- Add Grid, ScrollView/ScrollState, sticky and logical layout, spatial focus navigation, and platform cursors.
+- Add gradients, transforms, paths, layered effects, and matching Software, OpenGL, Metal, and Vulkan scene rendering.
+- Add paragraph layout, Japanese kinsoku, font fallback, selection, Unicode-safe editing, and native IME composition.
+- Add the opt-in `zaniah/ui` component library with keyboard and TUI support.
+- Add clock-driven animation, keyed transitions, inertial scrolling, and reduced-motion support.
+- Add virtual data views, charts, validated forms, native screen-reader support on macOS, Windows, and Linux, DevTools, and a three-theme component gallery.
+
 ## 0.2.0 — 2026-09-11
 
 - Add read-only element, hit-region, popup, and frame inspection APIs.

data/LICENSE.txt

@@ -19,3 +19,21 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+Bundled icons in assets/icons are derived from Lucide (https://lucide.dev):
+
+ISC License
+
+Copyright (c) 2020, Lucide Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -33,11 +33,15 @@ the drawing surface beneath the editor.
 
 ## Features
 
-- Flex, constraint, absolute, wrapping, and baseline-aware layouts
-- Rounded rectangles, images, static SVG, shadows, clipping, and glyph atlases
+- Flex, Grid, sticky, absolute, wrapping, and baseline-aware layouts
+- Gradients, transforms, paths, SVG, shadows, clipping, and GPU glyph atlases
 - Retained element state, subscriptions, and non-blocking background tasks
-- Uniform and variable-height virtual lists
-- OpenType ligatures and horizontal positioning with configurable text providers
+- Scroll views, inertial input, and uniform or variable-height virtual lists
+- OpenType shaping, font fallback, Japanese wrapping, text overlays, selection, editing, and IME
+- Themes, state styles, keyed animation, springs, and reduced-motion support
+- Opt-in controls, overlays, tables, trees, charts, forms, and terminal fallbacks
+- Spatial keyboard focus and a diffed cross-platform accessibility tree
+- F12 inspector, frame statistics, hot reload, and headless golden-image tests
 - Native input, IME, clipboard, file-drop, display, and filesystem events
 - RBS declarations for the public API
 
@@ -110,6 +114,12 @@ Native backends use the operating system libraries through Ruby's Fiddle. See
 - [Native backends](docs/native.md) — windows, displays, file watching, and terminals
 - [Text system](docs/text.md) — font discovery, shaping, rasterization, and caching
 - [SVG and lists](docs/vector_and_list.md) — static vector icons and virtual lists
+- [Layout and scrolling](docs/layout.md) — Grid, ScrollView, sticky positioning, and RTL foundations
+- [Themes](docs/theme.md) — semantic tokens and state styles
+- [Components](docs/components.md) — controls, overlays, data views, charts, and forms
+- [Animation](docs/animation.md) — easing, springs, transitions, and reduced motion
+- [Accessibility](docs/accessibility.md) — semantic trees, diffs, and native bridges
+- [Terminal UI](docs/tui.md) — deterministic component degradation
 - [CPU process workers](docs/process_pool.md) — portable background CPU work
 - [Architecture decisions](docs/adr) — design records and rationale
 - [RBS declarations](sig) — public API signatures

data/assets/icons/check.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>

data/assets/icons/close.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M18 6 6 18M6 6l12 12"/></svg>

data/assets/icons/info.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4M12 8h.01"/></svg>

data/assets/icons/menu.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 6h16M4 12h16M4 18h16"/></svg>

data/assets/icons/search.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>

data/assets/icons/warning.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21.7 18 13.7 4a2 2 0 0 0-3.4 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.7-3Z"/><path d="M12 9v4M12 17h.01"/></svg>

data/docs/accessibility.md

@@ -0,0 +1,61 @@
+# Accessibility
+
+Every window maintains a backend-neutral `Accessibility::Tree` beside its render
+tree. Components expose role, label, value, bounds, states, children, and actions
+through `Accessibility::Node`. The window publishes a notification only when the
+semantic tree changes.
+
+```ruby
+window.accessibility_tree.each do |node, path|
+  puts [path, node.role, node.label].inspect
+end
+```
+
+`window.accessibility_revision` increments after each semantic change, and
+`window.accessibility_tree.changes` contains `added`, `removed`, or `updated`
+records. This makes accessibility assertions deterministic on the headless
+backend without mocking an operating system API.
+
+## Component semantics
+
+Interactive components publish their current state and supported actions. For
+example, checkboxes expose `checked`, mixed checkboxes expose `mixed`, disabled
+controls omit mutating actions, modal dialogs expose `modal`, and live Toast
+messages use the `status` role. `FormField` marks invalid controls and associates
+the error node through its `describedby` state.
+
+Custom components implement the same method:
+
+```ruby
+def accessibility_node(_cx)
+  Zaniah::Accessibility.node(
+    role: :button,
+    label: "Refresh",
+    states: {busy: @loading},
+    actions: @loading ? [] : [:press]
+  )
+end
+```
+
+Decorative content should return `nil`. Container elements without an explicit
+node retain semantic descendants in a generated `group` node.
+
+## Native bridges
+
+- macOS publishes an `NSAccessibilityElement` hierarchy with roles, labels,
+  values, state, bounds, and children, then posts `AXLayoutChanged`.
+- Windows answers `WM_GETOBJECT` with `IRawElementProviderSimple`, fragment,
+  fragment-root, and Invoke providers. UI Automation clients can navigate and
+  query the semantic hierarchy rather than relying on refresh events alone.
+- Linux registers `Accessible`, `Component`, `Action`, and `Application`
+  objects on the AT-SPI D-Bus, embeds the application root in the registry,
+  and emits object-change events. Actions route back through the normal input
+  dispatcher on every platform.
+
+The Linux provider is exercised in CI inside a private D-Bus session. Native
+macOS and Windows objects retain the same `Accessibility::NativeTree` path and
+bounds model used by the headless assertions.
+
+The semantic tree remains the authoritative source on every backend. See
+[ADR-008](adr/008-accessibility-bridge.md) for the boundary between components
+and native adapters.

data/docs/adr/004-style-resolution.md

@@ -0,0 +1,17 @@
+# ADR 004: Resolve interaction styles in elements before paint
+
+- Status: Accepted
+- Date: 2026-09-12
+- Decision deadline: before M1 implementation
+
+## Context
+
+State-specific styles need stable layout inputs and same-frame hover feedback. Resolution could live in elements, the frame context, or a separate style object.
+
+## Decision
+
+Store variants in `StyleSet`, resolve flags from interaction state during prepaint, and let each element use the resolved style during paint. Keep `FrameContext` as a service carrier rather than a style owner.
+
+## Consequences
+
+Existing element builders remain compatible and paint stays deterministic. Elements must register hits when they only have state-specific styles.

data/docs/adr/005-instance-layout.md

@@ -0,0 +1,43 @@
+# ADR 005: Extend the shared GPU instance layout once
+
+- Status: Accepted
+- Date: 2026-09-12
+- Decision deadline: before M3 implementation
+
+## Context
+
+Metal, OpenGL, Vulkan, and Software consume the same 24-float instance payload. Gradients and transforms need more fields; changing the stride independently for each feature repeats risky backend work.
+
+## Decision
+
+Use this 40-float layout. Quad data uses every field; sprites reuse the edge
+fields for source UVs. Triangle vertices reuse rect and radii fields.
+
+| Floats | Quad | Sprite |
+| --- | --- | --- |
+| 0–3 | bounds | bounds |
+| 4–7 | primary color | tint |
+| 8–11 | secondary gradient color | unused |
+| 12–15 | corner radii | unused |
+| 16–19 | border color | unused |
+| 20–23 | edge border widths | source UV |
+| 24–27 | gradient kind, stop positions, angle | unused |
+| 28–31 | gradient center, radius, primitive kind | primitive kind |
+| 32–37 | affine transform (`a,b,c,d,tx,ty`) | affine transform |
+| 38–39 | reserved shadow spread / inset or border flags | unused |
+
+Opacity is multiplied into both fill and border alpha before packing. Linear
+and radial gradients use exactly two stops; a future multi-stop implementation
+may use a 1D texture without another stride change. Shadows are expanded into
+ordinary quad instances, so the reserved shadow fields remain available.
+
+Metal, OpenGL, and Vulkan consume the layout directly, Software consumes the
+equivalent 40-float quad layout, and cached text sprite batches use the same
+stride. Vulkan's bundled SPIR-V shaders render `Scene` quads, sprites, and path
+triangles offscreen; its user-supplied SPIR-V triangle probe remains available.
+
+## Consequences
+
+The coordinated change avoids multiple format migrations. Shader compilation,
+Software golden tests, instance packing tests, and platform-native capture tests
+are release gates on their available hosts.

data/docs/adr/006-component-model.md

@@ -0,0 +1,17 @@
+# ADR 006: Components participate by duck typing
+
+- Status: Accepted
+- Date: 2026-09-12
+- Decision deadline: before M6 implementation
+
+## Context
+
+Components can inherit `Element` or wrap an element tree while implementing the existing render protocol. Inheritance exposes low-level mutable state that components do not need.
+
+## Decision
+
+Components implement `request_layout`, `layout_node`, `prepaint`, and `paint`, delegating those calls to a built root element.
+
+## Consequences
+
+The UI layer stays optional and thin. Protocol changes must be reflected in both elements and components.

data/docs/adr/007-text-buffer.md

@@ -0,0 +1,17 @@
+# ADR 007: Start with a String-backed text buffer
+
+- Status: Accepted
+- Date: 2026-09-12
+- Decision deadline: before M5 implementation
+
+## Context
+
+Text editing needs Unicode-safe changes and undo. A piece table scales better for very large documents, while a Ruby `String` is substantially simpler for the intended settings and editor examples.
+
+## Decision
+
+Use a mutable UTF-8 `String` with byte offsets and grapheme-aware navigation. Revisit a piece table only after representative documents show a measurable problem.
+
+## Consequences
+
+The first implementation is small and easy to verify. Large edits are linear in buffer size.

data/docs/adr/008-accessibility-bridge.md

@@ -0,0 +1,19 @@
+# ADR 008: Separate the accessibility tree from OS bridges
+
+- Status: Accepted
+- Date: 2026-09-12
+- Decision deadline: before M8 implementation
+
+## Context
+
+NSAccessibility, UI Automation, and AT-SPI expose different native contracts, but components need one testable semantic model.
+
+## Decision
+
+Build a backend-neutral accessibility tree first. Add Fiddle-based adapters for macOS, Windows, and Linux that publish tree differences without changing component APIs.
+
+## Consequences
+
+Semantics and diffs are tested headlessly. Native adapters publish layout-change
+query providers and notifications through NSAccessibility, Windows UI Automation,
+and AT-SPI's D-Bus interfaces while retaining the same backend-neutral tree.

data/docs/adr/009-grid-scope.md

@@ -0,0 +1,17 @@
+# ADR 009: Implement a bounded grid layout subset
+
+- Status: Accepted
+- Date: 2026-09-12
+- Decision deadline: before M2 implementation
+
+## Context
+
+Full CSS Grid is too large for the toolkit's first grid implementation. Applications primarily need explicit tracks, spans, gaps, fractional space, and predictable automatic placement.
+
+## Decision
+
+Support explicit rows and columns, row-first auto placement, integer and range placement, `fr`, `minmax`, `auto`, and gaps. Defer named areas and `auto-fit`/`auto-fill`.
+
+## Consequences
+
+Common application layouts are covered with a tractable engine. Deferred CSS features require an explicit later extension.

data/docs/adr/010-text-overlay-layout.md

@@ -0,0 +1,24 @@
+# ADR 010: Model text overlays as layout gaps
+
+- Status: Accepted
+- Date: 2026-09-15
+- Decision deadline: before text overlay implementation
+
+## Context
+
+Inline hints and block annotations must affect wrapping and pointer mapping without
+becoming editable text. Absolutely painting them over an ordinary paragraph would
+leave wrapping, carets, and selection unaware of their size.
+
+## Decision
+
+Represent inline overlays as measured gaps at UTF-8 grapheme boundaries and block
+overlays as measured rows around logical source lines. Cache the wrapped paragraph
+for each explicit source line so changing one inline overlay only reshapes that row.
+Keep overlay elements as ordinary positioned children for painting and input.
+
+## Consequences
+
+Text offsets remain unchanged, overlay children stay clickable, and coordinate
+conversion accounts for every gap. Layout changes after an overlay row still shift
+later vertical positions, but those rows reuse their shaped and wrapped paragraphs.

data/docs/animation.md

@@ -0,0 +1,46 @@
+# Animation
+
+Zaniah uses one clock-driven `Animator` per window. Rendering stays idle when no
+animation is active, and injected clocks keep headless tests deterministic.
+
+```ruby
+window.animator.animate(:progress, from: 0, to: 1,
+  duration: 0.18, easing: :ease_out)
+window.animator.value(:progress)
+```
+
+Available easing values are `linear`, `ease_in`, `ease_out`, and `ease_in_out`.
+`Zaniah::Easing.cubic_bezier(x1, y1, x2, y2)` and
+`window.animator.spring(key, to:, stiffness:, damping:, mass:)` cover custom
+curves and spring motion. Numeric values, `Color`, same-unit `Length`, and
+`Transform` values can be interpolated.
+
+## Style transitions
+
+```ruby
+Div.new.key(:save).bg(theme.colors.surface)
+  .hover(background: theme.colors.surface_hover)
+  .transition(:background, duration: theme.motion.duration_base)
+```
+
+Transitions require `key`; without one the new style is applied immediately.
+Keyed children of a stable `Div` or `List` automatically animate additions,
+removals, and position changes. Removed children remain paintable in the
+window's existing element-state store until their exit animation completes.
+
+`ScrollView`, `List`, and `UniformList` use the same animator for inertial
+scrolling. Pass `inertia: false` to a standalone `ScrollState` to disable it.
+Overlay scrollbars fade after activity; modal overlays and collapsible content
+animate visibility. Editable text carets, skeletons, and spinners also use the
+window clock.
+
+## Reduced motion
+
+The macOS, Windows, and Linux backends read the operating-system reduced-motion
+setting. When `theme.motion.reduced?` is true, the animator completes every
+animation immediately. Tests or applications can opt in explicitly:
+
+```ruby
+theme = Theme.dark
+app.global(:theme, theme.with(motion: theme.motion.with(reduced: true)))
+```

data/docs/components.md

@@ -0,0 +1,109 @@
+# Components
+
+The optional component layer is loaded with `require "zaniah/ui"`. Components use the
+same `request_layout` / `prepaint` / `paint` protocol as elements and may be placed
+directly in an element tree. Builder methods return the component.
+
+```ruby
+require "zaniah/ui"
+
+save = Zaniah::UI::Button.new("Save", variant: :primary, size: :md)
+  .icon(:check)
+  .on_click { |_event, cx| cx.window.request_frame }
+```
+
+Applications may extend variant tables:
+
+```ruby
+Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
+  {background: theme.colors.success, hover: theme.colors.success,
+   foreground: theme.colors.text_inverse, border: theme.colors.success}
+}
+```
+
+## Component reference
+
+| Layer | Component | Main constructor/options | Variants | Accessibility role |
+| --- | --- | --- | --- | --- |
+| L0 | `Label` | `(text, tone:, size:, wrap:)` | tone: default/muted/inverse; size: xs–xl | text |
+| L0 | `Icon` | `(source, size:, color:, label:)` | bundled: check/close/search/menu/info/warning | image when labeled |
+| L0 | `Divider` | `(axis:)` | horizontal/vertical | separator |
+| L0 | `Spacer` | `(size = nil)` | fixed or flexible | none |
+| L0 | `Card` | `(*children)`, `child` | theme surface | group |
+| L0 | `Badge` | `(text, variant:)` | neutral/accent/success/warning/danger | text |
+| L0 | `Avatar` | `(name, image:, size:)` | initials or PNG | image |
+| L0 | `Skeleton` | `(width:, height:)` | pulsing loading placeholder | progressbar/busy |
+| L0 | `EmptyState` | `(title, message:, icon:, action:)` | compositional | group |
+| L1 | `Button` | `(label, size:, variant:)`; `disabled`, `loading`, `icon`, `on_click` | sm/md/lg × primary/secondary/ghost/danger | button |
+| L1 | `IconButton` | `(icon, label:, ...)` | Button variants | button |
+| L1 | `ToggleButton` | `(label, value:)`; `on_change` | Button variants | button/pressed |
+| L1 | `ButtonGroup` | `(*buttons)`, `child` | horizontal | group |
+| L1 | `Checkbox` | `(label, value:, disabled:)`; `on_change` | true/false/mixed | checkbox |
+| L1 | `Radio` | `(label, value:, disabled:)`; `on_change` | selected/unselected | radio |
+| L1 | `RadioGroup` | `(options, value:)`; `on_change` | one selected value | radiogroup |
+| L1 | `Switch` | `(label, value:, disabled:)`; `on_change` | on/off | switch |
+| L1 | `Slider` | `(value:, min:, max:, step:, label:)`; `on_change` | pointer + arrow/Home/End/Page keys | slider |
+| L1 | `RangeSlider` | `(value: [low, high], ...)` | two thumbs | slider |
+| L1 | `ProgressBar` | `(value:, min:, max:, label:)` | determinate/indeterminate | progressbar |
+| L1 | `Spinner` | `(label:, size:)` | animated loading indicator | progressbar/busy |
+| L1 | `Meter` | `(value:, low:, high:, optimum:)` | thresholds | meter |
+| L2 | `Tooltip` | `(text, anchor:, side:, open:)` | top/bottom/left/right | tooltip |
+| L2 | `Popover` | `(content, anchor:, side:, width:, height:, open:, modal:)` | flipped and viewport-clamped | group |
+| L2 | `ContextMenu`, `Menu` | `(items, anchor:, open:)` | pointer + arrows/Home/End/Enter/Esc | menu/menuitem |
+| L2 | `MenuBar` | `(menus)` | compositional | menubar |
+| L2 | `Dropdown` | `(label, items:, value:)`; `on_change` | menu-backed | button |
+| L2 | `TextField` | `(value, placeholder:, label:, prefix:, suffix:, error:, max_length:, clearable:)` | IME, selection, counter | textbox |
+| L2 | `TextArea` | TextField plus `rows:` | multiline/wrapped | textbox/multiline |
+| L2 | `SearchInput` | TextField options | search + clear icons | searchbox |
+| L2 | `PasswordInput` | TextField options | masked display | textbox |
+| L2 | `NumberInput` | TextField plus `min:`, `max:`, `step:`; `increment`, `decrement` | numeric | textbox |
+| L2 | `TagInput` | `(tags, separator:, ...)`; `on_tags_change` | badge list + editor | textbox |
+| L2 | `Select` | `(items, label:, value:, disabled:)`; `on_change` | single choice | combobox |
+| L2 | `Combobox` | `(items, value:, label:, placeholder:, disabled:)`; `on_change` | editable, filtered choices | combobox |
+| L2 | `MultiSelect` | `(items, value:, label:, disabled:)`; `on_change` | multiple selected badges | listbox |
+| L2 | `DatePicker` | `(value, min:, max:, label:, disabled:)`; `on_change` | ISO date, day/week keyboard steps | combobox |
+| L2 | `TimePicker` | `(value, step:, label:, disabled:)`; `on_change` | 24-hour time, minute/hour keyboard steps | combobox |
+| L2 | `ColorPicker` | `(value, label:, swatches:, disabled:)`; `on_change` | hex input and swatches | combobox |
+| L3 | `Tabs` | `(items, selected:)`; `on_change` | arrows/Home/End | tab/tabpanel |
+| L3 | `ScrollView` | `(axis:, scrollbar:)`; `scroll_to` | vertical/horizontal/both; overlay/always/hidden | child tree |
+| L3 | `Scrollbar` | `(scroll_state, axis:, mode:)` | drag, track paging, arrows/Home/End/Page keys | scrollbar |
+| L3 | `Accordion` | `(items, multiple:, open:)` | single/multiple | group |
+| L3 | `Collapsible` | `(label, content, open:)`; `on_change` | open/closed | button/expanded |
+| L3 | `Breadcrumb` | `(items)` | labels or label/callback pairs | navigation/link |
+| L3 | `Pagination` | `(page:, pages:, window:)`; `on_change` | previous/window/next | navigation |
+| L3 | `Toolbar` | `(*children)`, `child` | horizontal | toolbar |
+| L3 | `StatusBar` | `(*children)`, `child` | horizontal | status |
+| L3 | `Sidebar` | `(*children, width:)`, `child` | vertical | navigation |
+| L3 | `Modal`, `Dialog` | `(content, title:, open:, close_on_scrim:, width:)` | focus trap, scrim, Esc | dialog/modal |
+| L3 | `Drawer` | Modal plus `side:` | left/right | dialog/modal |
+| L3 | `Toast` | `(message, variant:, queue:)`; `dismiss` | info/success/warning/danger | live status |
+| L3 | `CommandPalette` | `(commands, open:, placeholder:)` | searchable modal | dialog/list |
+| L3 | `SplitPane` | `(first, second, orientation:, ratio:, min:, max:)`; `on_change` | horizontal/vertical, draggable separator | group/separator |
+| L3 | `Resizable` | `(content, width:, height:, min_width:, min_height:, max_width:, max_height:)`; `on_resize` | drag or keyboard resize | group/separator |
+| L3 | `DockPanel` | `(center:, top:, right:, bottom:, left:)` | five-region layout | group |
+| L3 | `ListView` | `(items, height:, row_height:, selected:)`; `on_select` | virtual rows and keyboard selection | list/listitem |
+| L4 | `Table`, `DataGrid` | `(rows, columns:, height:, selection:, row_key:)`; `on_sort`, `on_select`, `on_edit` | virtual rows, sorting, resizing, editing | table/row/cell |
+| L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, lazy `children` proc | arrows/Home/End | tree/treeitem |
+| L5 | `Sparkline` | `(values, width:, height:, color:, label:)` | line + tooltip | image |
+| L5 | `LineChart`, `BarChart` | `(series, width:, height:, colors:, label:)` | axes, legend, tooltip | image |
+| L5 | `Validation` | `required`, `format`, `length`, `number`, `rule` | composable rules | n/a |
+| L5 | `FormField` | `(name, value:, label:, control:, validation:, hint:)` | errors + describedby | group/control/alert |
+| L5 | `Form` | `field`, `on_change`, `on_submit`, `values`, `valid?` | validates before submit | form |
+| L5 | `CodeEditor` | `(value, language:, line_numbers:, read_only:)`; `on_change` | multiline editor with scrolling | textbox |
+| L5 | `RichText` | `(runs, selectable:)` | styled selectable runs | text |
+
+All input components are keyboard operable. Disabled controls remain visible but are
+removed from focus traversal. Overlay components close on Esc; modal overlays restore
+the previous focus. See [TUI](tui.md) for terminal representations.
+
+Table columns are hashes with `key`, and optional `label`, `width`, `sortable`,
+`resizable`, `editable`, and `render`. Tree items accept hashes containing `id`,
+`label`, and either an array or lazy proc in `children`.
+
+In a table, Up/Down/Home/End/Page keys move and select rows, Shift+Up/Down extends
+a range, and Cmd/Ctrl+A selects every row in multiple-selection mode. Sortable
+headers and resize handles are separate Tab stops; Enter sorts and arrow/Page keys
+resize. Tree views use Up/Down to select and Left/Right to collapse or expand.
+
+Run `bundle exec ruby tools/generate_component_gallery.rb` to rebuild the dark,
+light, and high-contrast component sheets plus overlay variants in all three themes.