zaniah 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bad32e7fbe4f1abe64589fbc41d73f242c4ed3aeee9f760c67a4d205d0c8d8d7
-  data.tar.gz: b57324bacd30eeea83d04407f689e9ca47d79178d1f0228acf5396fa2ea27881
+  metadata.gz: 8bda306c4301dbab842c0014a31bd563366fd846755c1adab9b864704dcd04a2
+  data.tar.gz: 94a9f0005a5e03e97f64f362e9ace3c1ec1757a2f73b9bf893f4e4eee6c56926
 SHA512:
-  metadata.gz: 5bbf0bebdad77e095cb6faba2a614cf5129558dd10629c94f2e6ad9966f9cb50dfe32a37b551569cdcfb1ba74085d4c64a3667740ff1699fa7b8ce03c553ad4c
-  data.tar.gz: 9d2491ddb19ce68065497f484b9bba0aa4e026fa998a31e3bca3d7bd41f0ed6edd805f0096aefd28ce2b1acf9309f0b96785cbbce88d67ebea10526094060a2f
+  metadata.gz: 0ed9ec96438a5e8de2c420b13d709be7865ad5a1df0d5e0d41cb23a110a2fe00dfc9143624a4fa4ead856e02f9b63c9e986df2f89ecee7e1f113e6265bfa6485
+  data.tar.gz: 118e347c3b1fe1ddc83e5f5a3390fd4dfb026ca95b79d32239c328960b1dc3a91525e7e70f1b60ef24570026f4f997dd0bb82f955a12c3f67653bd8db90d4032

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.12.0 — 2026-10-02
+
+- Add streaming virtual tables with lazy cells, stable selection, row styling, configurable columns, and tail following.
+- Add virtual hexadecimal and ASCII byte views with linked selection, highlights, keyboard navigation, and copying.
+- Preserve scrolling and height measurements when virtual list counts change, with optional bottom following.
+- Avoid stale rows and duplicated drawing when scrolling keyed virtual lists.
+- Reduce layout work for fixed-size containers and reuse unchanged visible byte rows for faster redraws.
+- Speed up vector recording by reusing resolved paint colors.
+- Add text-field validation states and token completion with keyboard selection and Unicode-safe replacement.
+- Add programmatic tree selection and item context menus.
+- Add suggested filenames, starting directories, and extension filters for native file dialogs.
+- Fix inspection snapshots for nested UI components, including select controls in dialogs.
+- Preserve accessible content and actions inside wrapped split panes.
+
+## 0.11.0 — 2026-09-25
+
+- Add segmented controls, alerts, hover cards, calendar and date-range inputs.
+- Add zoomable views, dockable workspaces, and editable property grids.
+- Add typed drag-and-drop across desktop backends with explicit move completion.
+
 ## 0.10.0 — 2026-09-24
 
 - Add Unicode bidirectional text layout, caret affinity, and Arabic joining.

data/README.md

@@ -114,7 +114,7 @@ For an interactive window, choose `backend: :mac`, `:linux`, `:windows`, or
 | `:tui` | ANSI terminal | Text-grid rendering and terminal input |
 
 Native backends use the operating system libraries through Ruby's Fiddle. See
-[Native backends](docs/native.md) for platform requirements and checks.
+[Native backends](https://noxdea.github.io/zaniah/docs/guides/native.html) for platform requirements.
 
 Native macOS, Windows, and X11 windows can be moved to a display returned by
 `Zaniah::Platform.displays` with `window.move_to_display(display)`. Headless and
@@ -124,37 +124,18 @@ compositor to fullscreen on that output, but the compositor may choose otherwise
 
 ## Documentation
 
-- [Native backends](docs/native.md) — windows, displays, file watching, and terminals
-- [Text system](docs/text.md) — font discovery, shaping, rasterization, and caching
-- [Images](docs/images.md) — PNG, GIF, baseline JPEG, and orientation support
-- [SVG and lists](docs/vector_and_list.md) — static vector icons and virtual lists
-- [Drag-and-drop reordering](docs/drag_drop.md) — stable IDs, virtual targets, and keyboard access
-- [Layout and scrolling](docs/layout.md) — Grid, resizable pane grids, scrolling, 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
-- [Declarative elements](docs/describe.md) — validated vocabularies, event routing, diffs, and surfaces
-- [Architecture decisions](docs/adr) — design records and rationale
+- [Getting started](https://noxdea.github.io/zaniah/docs/) — installation and your first render
+- [Guides](https://noxdea.github.io/zaniah/docs/guides/) — platforms, layout, text, themes, accessibility, and advanced APIs
+- [Components](https://noxdea.github.io/zaniah/docs/components/) — rendered examples, code, and API summaries
+- [Component API reference](https://noxdea.github.io/zaniah/docs/guides/component-reference.html) — all constructors and variants in one table
+- [Contributing guidelines](.github/CONTRIBUTING.md) — development and platform checks
+- [Architecture decisions](docs/adr) — implementation rationale
 - [RBS declarations](sig) — public API signatures
 
-## Development
-
-```sh
-bundle install
-bundle exec rake test
-bundle exec rake bench
-gem build --strict zaniah.gemspec
-```
-
-Set `BUDGET=1` to enable benchmark assertions.
-
 ## Contributing
 
-Bug reports and pull requests are welcome at
-[github.com/noxdea/zaniah](https://github.com/noxdea/zaniah).
+Bug reports and pull requests are welcome. See the
+[contributing guidelines](.github/CONTRIBUTING.md) for checks and documentation updates.
 
 ## License
 

data/assets/fonts/NotoSans-LICENSE.txt

@@ -0,0 +1,94 @@
+Copyright 2018 The Noto Project Authors (github.com/googlei18n/noto-fonts)
+
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

data/docs/_templates/page.erb

@@ -0,0 +1,123 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="<%= h(page.fetch("lead")) %>">
+  <meta name="theme-color" content="#0b1220">
+  <link rel="canonical" href="https://noxdea.github.io/zaniah/docs/<%= path == "index.html" ? "" : path %>">
+  <link rel="stylesheet" href="<%= link_from(path, "site.css") %>">
+  <title><%= h(page.fetch("title")) %> · Zaniah Docs</title>
+</head>
+<body>
+  <a class="skip-link" href="#content">Skip to content</a>
+  <header class="site-header">
+    <div class="header-inner">
+      <a class="brand" href="<%= link_from(path, "index.html") %>" aria-label="Zaniah documentation home"><span class="brand-symbol" aria-hidden="true">Z</span><span>Zaniah <small>Docs</small></span></a>
+      <nav class="header-links" aria-label="Global navigation">
+        <a href="<%= link_from(path, "index.html") %>">Docs</a>
+        <a href="<%= link_from(path, "guides/index.html") %>">Guides</a>
+        <a href="<%= link_from(path, "components/index.html") %>">Components</a>
+        <a href="https://github.com/noxdea/zaniah">GitHub</a>
+      </nav>
+    </div>
+  </header>
+
+  <div class="docs-shell">
+    <aside class="sidebar" aria-label="Documentation navigation">
+      <% groups.each do |group, items| %>
+        <div class="nav-group"><h2><%= h(group) %></h2>
+          <% items.each do |item| %>
+            <a href="<%= link_from(path, item.fetch("path")) %>"<%= ' aria-current="page"' if item["path"] == path %>><%= h(item.fetch("title")) %></a>
+          <% end %>
+        </div>
+      <% end %>
+    </aside>
+
+    <main id="content" class="content">
+      <details class="mobile-nav"><summary>Browse documentation</summary><nav aria-label="Mobile documentation navigation">
+        <% groups.each do |group, items| %>
+          <strong><%= h(group) %></strong>
+          <% items.each do |item| %>
+            <a href="<%= link_from(path, item.fetch("path")) %>"<%= ' aria-current="page"' if item["path"] == path %>><%= h(item.fetch("title")) %></a>
+          <% end %>
+        <% end %>
+      </nav></details>
+      <div class="page-heading">
+        <p class="breadcrumb"><a href="<%= link_from(path, "index.html") %>">Docs</a><span aria-hidden="true">/</span><%= h(page.fetch("group")) %></p>
+        <h1><%= h(page.fetch("title")) %></h1>
+        <p class="lead"><%= inline(page.fetch("lead")) %></p>
+      </div>
+      <% if page["kind"] == "component" %>
+        <section class="doc-section" id="import"><h2>Import</h2>
+          <p>Load the optional component layer before using the examples below.</p>
+          <div class="code-example"><div class="code-label">Ruby</div><pre><code>require "zaniah/ui"</code></pre></div>
+        </section>
+      <% end %>
+
+      <% if page["kind"] == "index" %>
+        <% index_groups.each do |group| %>
+          <% items = groups.fetch(group) %>
+          <% items = items.reject { |item| item["kind"] == "index" } %>
+          <section class="doc-section" id="<%= h(group.downcase.gsub(/[^a-z0-9]+/, "-")) %>">
+            <h2><%= h(group) %></h2>
+            <div class="directory">
+              <% items.each do |item| %>
+                <a href="<%= link_from(path, item.fetch("path")) %>"><strong><%= h(item.fetch("title")) %></strong><span><%= h(item.fetch("lead")) %></span></a>
+              <% end %>
+            </div>
+          </section>
+        <% end %>
+      <% elsif page["kind"] == "markdown" %>
+        <article class="markdown"><%= guide_html %></article>
+      <% else %>
+        <% page.fetch("sections", []).each do |section| %>
+          <section class="doc-section" id="<%= section_id(section) %>">
+            <h2><%= h(section.fetch("heading")) %></h2>
+            <% Array(section["text"]).each do |paragraph| %><p><%= inline(paragraph) %></p><% end %>
+            <% if section["image"] %>
+              <% image_width, image_height = image_dimensions(section.fetch("image")) %>
+              <figure class="example"><div class="example-label">Rendered example</div><img src="<%= link_from(path, section.fetch("image")) %>" alt="<%= h(section.fetch("alt")) %>" width="<%= image_width %>" height="<%= image_height %>" loading="lazy"><figcaption>Rendered by Zaniah's headless backend.</figcaption></figure>
+            <% end %>
+            <% if section["code"] %>
+              <div class="code-example"><div class="code-label"><%= h(section.fetch("code_label", "Ruby")) %></div><pre><code><%= h(section.fetch("code")) %></code></pre></div>
+            <% end %>
+            <% if section["note"] %><p class="note"><%= inline(section.fetch("note")) %></p><% end %>
+          </section>
+        <% end %>
+        <% if page["kind"] == "component" %>
+          <section class="doc-section" id="api"><h2>API summary</h2><p>Constructor options and behaviors are drawn from the <a href="<%= link_from(path, "guides/component-reference.html") %>">component reference</a>.</p>
+            <div class="table-scroll"><table><thead><tr><th>Component</th><th>Constructor and methods</th><th>Variants or behavior</th></tr></thead><tbody>
+              <% rows.each do |row| %><tr><td><code><%= h(row[:names].join(", ")) %></code></td><td><%= inline(row[:constructor]) %></td><td><%= inline(row[:variants]) %></td></tr><% end %>
+            </tbody></table></div>
+          </section>
+          <section class="doc-section" id="accessibility"><h2>Accessibility</h2>
+            <% if page["a11y"] %><p><%= inline(page["a11y"]) %></p><% end %>
+            <div class="table-scroll"><table><thead><tr><th>Component</th><th>Semantic role</th></tr></thead><tbody>
+              <% rows.each do |row| %><tr><td><code><%= h(row[:names].join(", ")) %></code></td><td><%= h(row[:role]) %></td></tr><% end %>
+            </tbody></table></div>
+          </section>
+        <% end %>
+      <% end %>
+
+      <nav class="pagination" aria-label="Adjacent pages">
+        <% if previous_page %><a href="<%= link_from(path, previous_page.fetch("path")) %>"><small>Previous</small><strong><%= h(previous_page.fetch("title")) %></strong></a><% end %>
+        <% if next_page %><a href="<%= link_from(path, next_page.fetch("path")) %>"><small>Next</small><strong><%= h(next_page.fetch("title")) %></strong></a><% end %>
+      </nav>
+    </main>
+
+    <aside class="toc" aria-label="On this page"><p>On this page</p>
+      <% if page["kind"] == "index" %>
+        <% index_groups.each do |group| %><a href="#<%= h(group.downcase.gsub(/[^a-z0-9]+/, "-")) %>"><%= h(group) %></a><% end %>
+      <% elsif page["kind"] == "markdown" %>
+        <% guide_toc.each do |anchor, heading| %><a href="#<%= h(anchor) %>"><%= heading %></a><% end %>
+      <% else %>
+        <% if page["kind"] == "component" %><a href="#import">Import</a><% end %>
+        <% page.fetch("sections", []).each do |section| %><a href="#<%= section_id(section) %>"><%= h(section.fetch("heading")) %></a><% end %>
+        <% if page["kind"] == "component" %><a href="#api">API summary</a><a href="#accessibility">Accessibility</a><% end %>
+      <% end %>
+    </aside>
+  </div>
+  <footer class="site-footer"><span>Zaniah is open source under the MIT License.</span><a href="https://github.com/noxdea/zaniah">Source on GitHub</a></footer>
+</body>
+</html>

data/docs/adr/021-dock-layout-tree.md

@@ -0,0 +1,33 @@
+# ADR 021: Represent dock layouts as a validated tree
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+An application needs to save tabbed, split workspaces and restore them across
+sessions. Dragging a tab changes both its group and potentially the split tree.
+A fixed five-region dock cannot represent nested splits or stable panel identity.
+
+## Decision
+
+`UI::DockLayout` stores tab groups and binary splits with stable string IDs.
+`to_h` and `from_h` provide a plain-data round trip; parsing rejects duplicate
+IDs, empty groups, invalid active tabs, invalid orientations, and out-of-range
+ratios. `UI::DockWorkspace` derives visible panes from this model and reuses
+`UI::SplitPane` for dividers. Layout changes produce a new validated model.
+The application owns persistence and handles `on_detach` notifications; the
+component does not create windows.
+
+## Alternatives considered
+
+- A flat list of panels plus coordinates would make nested resizing and
+  restoration ambiguous.
+- Extending `DockPanel` would change its simple five-region contract.
+- Making detach automatically create windows would assume application policy.
+
+## Consequences
+
+Persisted layouts can be validated independently of rendering. Empty groups
+are pruned after a move. Applications can choose their own storage format and
+window ownership; they must keep panel IDs stable across releases.

data/docs/components.md

@@ -21,10 +21,21 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 }
 ```
 
+`VirtualTable`, `HexView`, and `TreeView` accept `viewport_height=` when a window
+or split pane resizes. This updates their internal list viewport while retaining
+scroll state and selection. `VirtualTable#follow_tail=` toggles bottom following;
+call `scroll_to(source.count - 1, align: :end)` to resume immediately from elsewhere.
+
+`TreeView#on_context_menu { |item, cx| menu }` selects the item under a right
+click before opening the returned menu at the pointer. The callback receives the
+same item value as `on_select`.
+
 ## Component reference
 
 | Layer | Component | Main constructor/options | Variants | Accessibility role |
 | --- | --- | --- | --- | --- |
+| L4 | `VirtualTable` | `(source, columns:, height:, row_height:, selection:, follow_tail:)`; lazy `count`/`cell` source | stable row IDs, sortable/resizable headers, column visibility/order, row colors | table |
+| L4 | `HexView` | `(bytes, bytes_per_row:, group:, offset_digits:, height:)`; `highlights=`, `select`, `scroll_to_offset` | viewport rows; synchronized hex/ASCII selection and copying | group |
 | 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 |
@@ -32,6 +43,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L0 | `Card` | `(*children)`, `child` | theme surface | group |
 | L0 | `Badge` | `(text, variant:)` | neutral/accent/success/warning/danger | text |
 | L0 | `Kbd` | `(keys, platform:)`; `.for(action, keymap:)` | OS shortcut notation, including multi-stroke bindings | text |
+| L0 | `Alert` | `(title, message:, variant:, action:, dismissible:, live:)`; `dismiss` | info/success/warning/danger; persistent until dismissed | alert when live, otherwise status |
 | 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 |
@@ -42,6 +54,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | 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 | `SegmentedControl` | `(options, value:)`; `on_change` | mutually exclusive segments; arrows/Home/End | radiogroup/radio |
 | 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 |
@@ -50,10 +63,11 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | 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 | `HoverCard` | `(content, anchor:, open_delay:, close_delay:)` | hover or focus opens after a delay; non-modal | dialog |
 | L2 | `ContextMenu`, `Menu` | `(items, anchor:, open:)` | pointer + arrows/Home/End/Enter/Esc | menu/menuitem |
 | L2 | `MenuBar` | `(menus)` or `.from(app.menu_bar)` | declarative menu model or legacy pairs | 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 | `TextField` | `(value, placeholder:, label:, prefix:, suffix:, error:, max_length:, clearable:)`; `status(kind, message:)`, `completion(provider)` | IME, selection, counter, validation, token completion | 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 |
@@ -63,6 +77,8 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L2 | `Combobox` | `(items, value:, label:, placeholder:, disabled:, matcher:)`; `on_change` | editable, filtered choices with highlighted matches | 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 | `Calendar` | `(value:, min:, max:, range:, week_start:, month_names:)`; `on_change` | arrow keys move days/weeks, Page keys move months, Enter selects | grid/gridcell |
+| L2 | `DateRangePicker` | `(value:, min:, max:, week_start:, month_names:)`; `on_change` | Calendar-backed start/end selection | 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 |
@@ -82,11 +98,14 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L3 | `SplitPane` | `(first, second, orientation:, ratio:, min:, max:)`; `on_change` | horizontal/vertical, draggable separator | group/separator |
 | L3 | `PaneGrid` | `(panes, columns:, rows:, divider_size:, minimum:, keyboard_step:)`; `replace`, `on_resize` | arbitrary resizable grid, stable pane IDs | group/separator |
 | L3 | `Resizable` | `(content, width:, height:, min_width:, min_height:, max_width:, max_height:)`; `on_resize` | drag or keyboard resize | group/separator |
+| L3 | `ZoomPanView` | `(content, zoom:, min_zoom:, max_zoom:)`; `fit`, `zoom_to`, `view_to_content` | drag to pan, pinch or Ctrl+wheel to zoom, `+`/`-`/`0` when focused | group |
 | L3 | `DockPanel` | `(center:, top:, right:, bottom:, left:)` | five-region layout | group |
+| L3 | `DockWorkspace` | `(layout, render:)`; `on_layout_change`, `on_detach`; `DockLayout.to_h`/`.from_h` | drag tabs to move/split, arrows select, Alt+arrows move, Ctrl+Shift+arrows split, Ctrl+Shift+D requests detach | tablist/tab/tabpanel/separator |
 | 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`, `on_copy`, `on_paste` | virtual rows, sorting, resizing, editing, typed clipboard hooks | table/row/cell |
 | L4 | `Grid` | `(rows:, columns:, row_height:, column_width:, frozen_rows:, frozen_columns:)`; `scroll_to`, range `selection`, `on_select`, `on_edit`, `on_fill`, `on_resize`, `on_copy`, `on_paste` | two-axis virtualization, frozen panes, visible-cell resize/fill and typed clipboard hooks | table |
-| L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, `replace`, `replace_children`, `invalidate`, lazy `children` proc | arrows/Home/End | tree/treeitem |
+| L4 | `TreeView` | `(items, height:, selected:)`; `select_id`, `on_context_menu`, `expand`, `collapse`, `replace`, `replace_children`, `invalidate`, lazy `children` proc | arrows/Home/End | tree/treeitem |
+| L4 | `PropertyGrid` | `(schema, values, height:, row_height:)`; `on_change`, `set` | typed existing controls, `Validation`, virtual rows | table/row/cell |
 | L5 | `Sparkline` | `(values, width:, height:, color:, label:)` | line + tooltip | image |
 | L5 | `LineChart`, `BarChart`, `StackedBarChart`, `AreaChart` | `(series, width:, height:, colors:, label:)`; `AreaChart(stacked:)` | shared axes, ticks, grid lines, color-keyed legend, tooltip | image |
 | L5 | `PieChart`, `DonutChart` | `(data, width:, height:, colors:, label:)` | slices, shared color-keyed legend, tooltip | image |
@@ -101,6 +120,28 @@ All input components are keyboard operable. Disabled controls remain visible but
 removed from focus traversal. Overlay components close on Esc; modal overlays restore
 the previous focus. See [TUI](tui.md) for terminal representations.
 
+`Calendar` and `DateRangePicker` use Ruby's `Date` and ISO 8601 strings. Pass
+`week_start: 0..6` (Sunday is 0) and twelve `month_names:` to localize the grid
+without an i18n dependency. A range picker returns a two-element array of dates;
+its second value is `nil` while the user is choosing the end. `HoverCard` accepts
+an element/component as its anchor to open on pointer hover or keyboard focus, or
+a `Point`/`Bounds` for positioned use. Its delays follow the window's injected clock.
+
+`ZoomPanView` uses content-local coordinates for `zoom_to` and `view_to_content`.
+Call `fit` after the first layout; it scales the content into the current viewport.
+Native macOS pinch emits `Input::Magnify`, while Ctrl+wheel provides a desktop fallback.
+
+`DockLayout` is a validated tree of tab groups and horizontal/vertical splits with
+stable string IDs. Use `DockLayout.tabs` and `.split` to build it, and persist
+`layout.to_h` in the application; `DockLayout.from_h` restores it. `DockWorkspace`
+passes the active panel ID to `render:` and emits a new layout on tab changes.
+`on_detach` is a notification only; the application decides whether to open a
+window and remove the panel. A pointer drop in the outer 20% of a group splits it.
+`PropertyGrid` schema entries use `key`, optional `label`, `type` (`text`,
+`textarea`, `number`, `boolean`, `select`, `color`, `date`, `time`), `options` for
+select, and an optional `Validation`. Invalid edits remain in the control while
+the last valid value is retained. Both components expose terminal fallbacks.
+
 `Combobox` and `CommandPalette` default to case-insensitive substring matching in
 input order. Pass `matcher:` to either component, or set a default with
 `Zaniah.configure { |config| config.matcher = matcher }`. A matcher implements
@@ -169,6 +210,3 @@ resize. Grid and Table clipboard hooks receive half-open `Grid::Area` ranges;
 Table areas follow the current display order without changing its stable-ID
 selection. See [Layout](layout.md#two-axis-virtual-grid). Tree views use Up/Down to select, Right to expand or enter the first child,
 and Left to collapse or return to the parent.
-
-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.

data/docs/inspection.md

@@ -16,4 +16,6 @@ Zaniah::Inspection.perform(window, node, :press)
 
 The snapshot containers and copied collections are frozen. `entry.element` is deliberately a live element reference: use it only in the same frame, because the next render may replace it. Accessibility nodes are copied for inspection; pass one to `Inspection.perform` to invoke an action on its current source node. Actions require a node from the current frame. To wait for a settled UI, call `Zaniah::Inspection.idle?(app)` after draining queued work and rendering dirty windows.
 
-The public API is declared in [`sig/inspection.rbs`](../sig/inspection.rbs), and its independently runnable contract test is [`test/inspection_contract_test.rb`](../test/inspection_contract_test.rb). Breaking changes receive at least one minor version of deprecation during 0.x, as recorded in [ADR 013](adr/013-public-inspection-api.md).
+The public API is declared in [`sig/inspection.rbs`](../sig/inspection.rbs).
+Breaking changes receive at least one minor version of deprecation during 0.x,
+as recorded in [ADR 013](adr/013-public-inspection-api.md).

data/docs/layout.md

@@ -96,14 +96,6 @@ remains a set of stable row IDs; hook arguments are `Grid::Area` ranges in the
 current sorted display order, covering all columns. Disjoint selected rows
 produce separate areas. The application retains ownership of table data.
 
-`bench/grid.rb` measures a headless 800×600 viewport over a 1,000,000×16,000
-grid at 23 sequential scroll positions, including cell construction, layout,
-prepaint, and paint. `BUDGET=1 ruby bench/grid.rb` asserts a 16.67 ms median
-frame limit. A local run on 2026-09-23 measured 12.964 ms and constructed an
-average of 250 cells per frame. This microbenchmark does not include an
-application's backing store, expensive cell renderers, or a native compositor;
-rerun it on target hardware for deployment decisions.
-
 `ScrollView` accepts one child and clips it to the viewport. Its `axis` is
 `:vertical`, `:horizontal`, or `:both`; use `scroll_to` for programmatic
 scrolling and `scroll_state` for offsets and edge checks.