zaniah 0.6.4 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 985d3d62a8ffa112effba1aed1976c2b7403a7e6ef2a49dca9b817c80d49b3da
-  data.tar.gz: 8e641aad423d506fcbf18fe5c6c22afa8beff2ae5b321ae73559cbec8ed26181
+  metadata.gz: 0e4185eb60f475f07fb3deee4bf07f0e7e16240771ee9199f9783d3fe13130cb
+  data.tar.gz: 05cafb090e57d8552cda0826d8db0ff1fa980107eab05ab9841824d6a18187c6
 SHA512:
-  metadata.gz: e71ed6d538a8ba9f48d3521def68d05957c637d631116dbf5676a47672d750b1128d361b7b8af48cd5231c01742db7ca88b6846961fc30c58339d4bf696e05a0
-  data.tar.gz: d6d48b77d5a4793d0e4aa2c4a5e23ccd34f4d5d690c858ecba51ad3585571275a12fa3b5ec882c1a03abdc2db174f757e6002d642d9b13b42aafe46b53f1ca23
+  metadata.gz: e5da9a69b48d186dcb04cf71cf48922d9e72fd019ff54919451f028cc211262fd8c49ecf85eb6dbbfd8b48213ad324ab98aefc9079473ace7d8a289401079ae4
+  data.tar.gz: f2b7ada32c16d932143db6cf68a9c2073e085ef0cda762aa7ed2f07ae7fdee5b9d5b1f5c3a5289b5fc54930fab9dbef1c0720e8035656c8ac700a2904012f431

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.8.0 — 2026-09-24
+
+- Add native macOS and Windows menus, declarative context menus, and platform-aware shortcut labels.
+- Add MIME-keyed clipboard content on desktop backends, including HTML, PNG, file URLs, and X11 incremental transfers.
+- Add Grid and Table copy/paste hooks with TSV and HTML data.
+- Add window state persistence, frameless windows, and draggable title regions across native backends.
+
+## 0.7.0 — 2026-09-24
+
+- Add a stable frame inspection API with accessibility queries and DevTools integration.
+- Unify focused and application commands with validation, availability, and checked state.
+- Add headless and TUI clipboard support, including OSC 52 output.
+- Add desktop editing shortcuts and copy, cut, paste, undo, and redo for plain and rich text while leaving conflicting TUI shortcuts unbound.
+- Add configurable matching and accessible, highlighted results to the command palette and combobox.
+
 ## 0.6.4 — 2026-09-24
 
 - Share Cartesian chart scales, axes, grid lines, ticks, and color-keyed legends across chart types.

data/docs/adr/013-public-inspection-api.md

@@ -0,0 +1,16 @@
+# ADR 013: Expose a stable inspection boundary
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+External test drivers and DevTools currently read render state through internal instance variables or maintain duplicate tree walkers. Internal layout and platform state can change without notice, which makes downstream tooling fragile. One option is to expose each underlying object directly; another is to publish a read-only view of the latest frame.
+
+## Decision
+
+Publish `Zaniah::Inspection.snapshot(window)` as the external read boundary, backed by small, explicit read accessors on the existing objects. DevTools uses the same boundary. Snapshot values are frozen; the `Entry#element` reference remains live only until the next frame. During the 0.x series, a breaking change to this public API requires at least one minor release of deprecation before removal.
+
+## Consequences
+
+Inspection is constructed only when requested, avoiding per-frame traversal cost. The small accessors and compatibility period constrain internal refactors, but test drivers no longer depend on private instance variables. Native accessibility actions still require a current node and window.

data/docs/adr/014-unified-command-dispatch.md

@@ -0,0 +1,40 @@
+# ADR 014: Route UI commands through focused handlers before app actions
+
+- Status: Proposed
+- Date: 2026-09-24
+
+## Context
+
+Keyboard actions currently reach only focused handlers. Menus, palettes, context
+menus, and accessibility actions need the same behavior, including a way to ask
+whether an item is enabled without executing it. Routing each source separately
+would make focus precedence and disabled states diverge.
+
+Native menu accelerators introduce a separate risk: macOS can process a
+`keyEquivalent` in addition to the framework keymap. Keeping both active could
+execute one command twice.
+
+## Decision
+
+Use `Dispatcher#perform` for all command sources. Focused handlers take precedence
+from leaf to root, followed by `App#actions`. A focused handle can provide a
+side-effect-free `validate` callback: `false` blocks the command, `true` enables
+it, and `nil` defers to the next handle. `available?` asks validators and the app
+registry without invoking action handlers. Legacy focused handlers without a
+validator remain executable but cannot advertise availability by themselves.
+
+An unvalidated legacy focus handler still executes before a disabled app
+command, even though `available?` can only report the app command as disabled.
+Such focused actions need `validate` to advertise their own availability.
+
+Keyboard focus movement remains a dispatcher concern. Native menu shortcuts
+must be routed through the Zaniah keymap exactly once; platform adapters must
+verify that native `keyEquivalent` processing does not also invoke the command.
+
+## Consequences
+
+Menus and palettes can share dispatch and validation with keyboard input, and
+app-wide commands remain available when no focus handler consumes them. Focused
+actions intended for menus must provide `validate`; an opaque handler alone
+cannot safely report support without being run. Native shortcut behavior needs
+platform verification before this ADR can be accepted.

data/docs/adr/015-mime-clipboard-types.md

@@ -0,0 +1,25 @@
+# ADR 015: Use MIME names for clipboard representations
+
+- Status: Proposed
+- Date: 2026-09-24
+
+## Context
+
+Applications need to place text, HTML, images, and private formats on the
+clipboard at the same time. Each operating system names these formats
+differently. Exposing those native names would make application copy/paste
+logic platform-specific; using a closed enum would exclude private formats.
+
+## Decision
+
+Use MIME strings as the public representation keys. Platform adapters map
+common MIME names to native formats and preserve other names where the system
+allows it. Items contain eagerly supplied, immutable data. The toolkit owns
+transport and format negotiation, not conversion of application data.
+
+## Consequences
+
+Applications can offer multiple formats through one API without depending on
+an OS adapter. Adapters must maintain the native mappings and account for
+platform-specific limits. Lazy data providers may be added later if eager
+copies become a measured problem.

data/docs/components.md

@@ -31,6 +31,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | 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 | `Kbd` | `(keys, platform:)`; `.for(action, keymap:)` | OS shortcut notation, including multi-stroke bindings | 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 |
@@ -50,7 +51,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | 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 | `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 | `TextArea` | TextField plus `rows:` | multiline/wrapped | textbox/multiline |
@@ -59,7 +60,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | 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 | `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 | `TimePicker` | `(value, step:, label:, disabled:)`; `on_change` | 24-hour time, minute/hour keyboard steps | combobox |
@@ -77,14 +78,14 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | 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 | `CommandPalette` | `(commands, open:, placeholder:, matcher:)`; `.from(app.actions)` | searchable modal, Up/Down/Enter | dialog/list |
 | 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 | `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 | `Grid` | `(rows:, columns:, row_height:, column_width:, frozen_rows:, frozen_columns:)`; `scroll_to`, range `selection`, `on_select`, `on_edit`, `on_fill`, `on_resize` | two-axis virtualization, frozen panes, visible-cell resize/fill callbacks | table |
+| 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 |
 | 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 |
@@ -100,6 +101,15 @@ 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.
 
+`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
+`match(query, labels)` and returns `UI::Matcher::Match` values with an original
+label `index`, descending `score`, and half-open UTF-8 byte `ranges` for highlighting.
+It may also implement `refine(previous_matches, query)` for incremental queries.
+`CommandPalette.from(app.actions)` uses registered action titles, disables
+unavailable actions, and displays shortcuts with `UI::Kbd`. See [Menus](menus.md).
+
 `UI::RichText` accepts UTF-8 byte ranges at grapheme boundaries. Inline styles are
 `bold`, `italic`, `size`, `color`, `font`, and `link`; paragraphs support start,
 center, end, and non-final-line justification, plus bullet/ordered lists and levels.
@@ -134,7 +144,9 @@ viewport.
 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, Right to expand or enter the first child,
+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,

data/docs/inspection.md

@@ -0,0 +1,19 @@
+# Frame inspection
+
+`Zaniah::Inspection` gives test drivers and DevTools a public, read-only view of the latest rendered frame. It works with headless and native windows.
+
+```ruby
+window.render(root)
+snapshot = Zaniah::Inspection.snapshot(window)
+save = snapshot.find(test_id: "save")
+buttons = snapshot.where(type: Zaniah::UI::Button)
+frontmost = snapshot.at(Zaniah::Point.new(120, 40))
+node, path = snapshot.accessibility.query(role: :button, label: /save/i).first
+Zaniah::Inspection.perform(window, node, :press)
+```
+
+`snapshot.root` and its children expose type, key, test ID, window-space bounds, resolved style, tooltip, context menu, handlers, and focus state. `snapshot.overlays` exposes tooltip, popup, and menu state; `snapshot.text_runs` contains rendered text; `snapshot.frame` contains a monotonically increasing frame number and timing statistics. `snapshot.find` returns the first match, `where` returns all matches, and `at` uses the frontmost registered hit region. A newly opened window has no root until its first render.
+
+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).

data/docs/layout.md

@@ -75,6 +75,27 @@ apply a validated batch with a single frame request; `row_hidden?` and
 destination areas; the application owns cell values and fill semantics. Shift
 extends a range; Cmd/Ctrl-click toggles an additional cell range.
 
+Copy and paste are opt-in: the grid never owns cell values. `on_copy` receives
+the selected `Grid::Area` values and returns MIME-keyed content, which Zaniah
+writes to the clipboard. `on_paste` receives the same half-open areas and all
+available clipboard formats; the application decides how to apply them.
+Without the corresponding hook, the action is unhandled. With a hook but no
+selection, the action is disabled.
+
+```ruby
+grid.on_copy do |areas, _cx|
+  {"text/plain" => cells_as_tsv(areas), "text/html" => cells_as_html(areas)}
+end
+grid.on_paste do |areas, content, _cx|
+  paste_cells(areas, content.fetch("text/plain")) if content.types.include?("text/plain")
+end
+```
+
+`UI::Table` and `UI::DataGrid` use the same hooks. Their existing `selection`
+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

data/docs/menus.md

@@ -0,0 +1,64 @@
+# Menus and shortcuts
+
+`Zaniah::Menu` describes commands; the application owns what each command does.
+Register actions once and attach a menu model to the app:
+
+```ruby
+app.actions.register(:save, title: "Save") { |cx| save_document(cx) }
+app.menu_bar = Zaniah::Menu.build do
+  app_menu
+  submenu "File" do
+    item :save
+    separator
+    submenu "Recent", items: -> { recent_items }
+  end
+  submenu "Edit" do
+    standard_edit_items
+  end
+  window_menu
+end
+```
+
+`recent_items` must return a `Zaniah::Menu` or an array of `Menu::Item` values.
+The callback runs when that submenu opens, not when the menu bar is drawn.
+`app_menu` and `window_menu` are macOS-only placeholders. They are omitted on
+other platforms. A missing item title comes from `app.actions`; a missing
+shortcut comes from the most recent keymap binding valid in an empty context.
+Context-only bindings are not shown. Multi-stroke shortcuts appear in window
+menus and `UI::Kbd`, but native menus show only single strokes.
+
+For Linux, headless, and TUI, place `Zaniah::UI::MenuBar.from(app.menu_bar)` in
+the application layout. Zaniah never inserts it automatically. Menu commands
+use `dispatcher.perform(action, source: :menu)` and are enabled or checked by
+`available?` and `checked?` when a menu opens. The in-window menu exposes a
+Back row for nested submenus and restores the previously focused control so
+standard editing commands target that control. `Inspection.snapshot(window).overlays.menu`
+returns the app's current model. Existing `UI::MenuBar.new([[label, items]])`
+and `UI::Menu.new([[label, callback]])` forms remain valid.
+
+`UI::Kbd.new("cmd-shift-p", platform: :mac)` displays `⌘⇧P`; on Windows or
+Linux it displays `Super+Shift+P`. `UI::Kbd.for(:save, keymap: keymap)` uses
+the same binding as the menu. Its TUI text always uses readable names such as
+`Ctrl+Shift+P`.
+
+Windows attaches a native menu to each window. It refreshes enabled and checked
+states when a menu opens and evaluates dynamic submenus at that time. Single-key
+shortcuts appear after a tab in item labels; key input still runs only through
+the Zaniah keymap, not a Win32 accelerator table. The menu model remains
+available for inspection and in-window display on all backends; headless has
+no system menu.
+
+On macOS, `App#menu_bar` becomes the system main menu. The app menu uses native
+About, Hide, Show All, and Quit items; `window_menu` uses the native Window menu.
+Dynamic submenu callbacks run when that submenu opens. Enabled and checked
+states are refreshed from the active window's dispatcher. Native shortcuts
+display single-stroke keymap bindings and route key events through the keymap
+before AppKit can run a matching menu item. A missing menu model keeps the
+original Quit-only menu. Run `ruby examples/native_menu.rb` in a macOS graphical
+session to inspect the native behavior.
+
+`element.context_menu(Zaniah::Menu.build { item :save })` accepts the same
+command model as the menu bar, including separators, nested submenus, dynamic
+items, and current enabled/checked state. macOS and Windows use native context
+menus for this model; headless, TUI, and `UI::ContextMenu` use the in-window
+menu. The older `[["Save", -> { save }]]` form remains supported.

data/docs/native.md

@@ -42,6 +42,54 @@ file drops, fullscreen, cursors, URL opening, file dialogs, appearance changes,
 and PNG capture. Platform availability differs; see [the RBS declarations](../sig/native.rbs)
 and [platform declarations](../sig/platform.rbs) for the exact API.
 
+## Clipboard representations
+
+`Clipboard::Item` holds eager MIME-keyed data. `text/*` values are UTF-8 text;
+other values are bytes. The window's `clipboard` and `clipboard=` methods remain
+shortcuts for `text/plain`.
+
+```ruby
+item = Zaniah::Clipboard::Item.new(
+  "text/plain" => "a\tb",
+  "text/html" => "<b>a</b>",
+  "image/png" => png_bytes
+)
+window.write_clipboard([item])
+window.clipboard_types                   # available MIME names, without reading data
+content = window.read_clipboard(types: ["text/html", "text/plain"])
+content.types                            # formats found, in requested order
+content.fetch("text/html")
+```
+
+Headless keeps representations in per-window memory. TUI also keeps every
+representation in memory and sends only `text/plain` writes to the terminal
+with OSC 52; it cannot read the terminal's clipboard. Native macOS, Windows,
+X11, and Wayland exchange `text/plain`, `text/html`, and `image/png` with other
+applications. macOS also preserves arbitrary MIME types under reversible
+`com.noxdea.zaniah.mime.<hex>` pasteboard identifiers; Windows, X11, and
+Wayland use their native format mechanisms. Native clipboard exchange still
+depends on a running desktop session and should be checked on each target OS.
+
+## Window state and decorations
+
+`window.frame` uses logical screen coordinates; `window.state.to_h` can be saved
+by the application and passed back to `window.restore_state`. Missing displays
+and offscreen frames are corrected toward the primary display. `maximize`,
+`minimize`, `restore`, `fullscreen?`, `always_on_top=`, and `on_state_change`
+operate on the native window where supported. `decorations: :native` is the
+default; `:hidden_titlebar` and `:none` enable a custom titlebar built from
+`window_drag_region` and `window_control` elements. `min_size:`, `resizable:`,
+and macOS-only `traffic_lights:` are creation options.
+
+X11 window managers must support EWMH for state and drag requests. On X11,
+`:hidden_titlebar` has the same no-decoration effect as `:none` through Motif
+hints. Wayland does not expose a window position: its frame origin is `nil`
+and setting a position raises. Wayland also cannot request always-on-top or
+programmatically restore a minimized window; those operations raise rather
+than claim success. Client-side decorations on Wayland depend on the compositor
+and its decoration protocol. Verify native placement and drag behavior on each
+target desktop before relying on it.
+
 ## Displays, file watching, and terminals
 
 `Zaniah::Platform.displays` returns the available displays for a backend.
@@ -73,6 +121,7 @@ ruby examples/native_smoke.rb --gl --check /tmp/zaniah-gl.png
 ruby examples/linux_smoke.rb
 ruby examples/linux_smoke.rb --wayland
 ruby examples/native_watch.rb
+ruby examples/native_menu.rb              # macOS only
 ```
 
 Linux XIM composition is exercised in CI with Xvfb and IBus/KKC. Native input,

data/docs/text.md

@@ -164,6 +164,25 @@ Supported inline styles are `bold`, `italic`, `size`, `color`, `font`, and
 receives `(text, rich_text)`; selection changes are reported by `on_select`.
 IME composition uses the existing `TextBuffer` composition path.
 
+## Editing shortcuts
+
+Editable text fields and rich text share the same actions from keyboard, menu,
+and command dispatch. The default desktop keys are:
+
+| Action | macOS | Windows | Linux |
+| --- | --- | --- | --- |
+| Undo / redo | Cmd+Z / Cmd+Shift+Z | Ctrl+Z / Ctrl+Y or Ctrl+Shift+Z | Ctrl+Z / Ctrl+Shift+Z |
+| Cut / copy / paste / select all | Cmd+X/C/V/A | Ctrl+X/C/V/A | Ctrl+X/C/V/A |
+| Previous / next word | Option+Left/Right | Ctrl+Left/Right | Ctrl+Left/Right |
+| Document start / end | Cmd+Up/Down | Ctrl+Home/End | Ctrl+Home/End |
+
+Shift with a word arrow extends the selection. Up/Down moves between logical
+lines in multiline fields; Home/End moves to the current line's edges. Copy
+requires a selection, and password fields never copy or cut. Paste and undo
+are disabled during IME composition. The TUI does not assign these desktop
+editing shortcuts by default because terminal control keys can conflict;
+applications may provide a custom keymap.
+
 ## Inline and block overlays
 
 Attach non-editable UI elements to text without inserting bytes into the source:

data/docs/tui.md

@@ -7,6 +7,7 @@ tests and non-window integrations.
 | Component family | Terminal representation |
 | --- | --- |
 | Label, Badge, Avatar | text, `[badge]`, `(initials)` |
+| Kbd | textual shortcut, such as `Ctrl+Shift+P`; multiple strokes are space-separated |
 | Icon | Unicode check/close/search/menu/info/warning symbol; unlabeled unknown icons are omitted |
 | Divider, Card | `─`/`│` and box-drawing characters |
 | Skeleton, Spinner, ProgressBar, Meter | shade cells, `◌`, or a ten-cell progress track; animation jumps to its terminal state |
@@ -16,11 +17,11 @@ tests and non-window integrations.
 | Text inputs | `[value]`; password values are masked and validation errors have `!` |
 | Select, Combobox, MultiSelect | labeled brackets, filtered menu marker, or comma-separated selected values |
 | DatePicker, TimePicker, ColorPicker | labeled ISO date, 24-hour time, or hex color in brackets |
-| Tooltip, Popover, Menu, Dropdown | status text or a box/menu with `>` selection marker |
+| Tooltip, Popover, Menu, MenuBar, Dropdown | status text or a box/menu with `>` selection marker; nested menus expose a Back row |
 | Tabs, Accordion, Collapsible | selected tab in brackets and `[+]`/`[-]` disclosure markers |
 | ScrollView, Scrollbar | clipped child content and `│`/`─` track |
 | Breadcrumb, Pagination, bars | slash-separated path, page status, space-separated content |
-| Modal, Dialog, Drawer, CommandPalette | box-drawing overlay; focus stays inside until dismissed |
+| Modal, Dialog, Drawer, CommandPalette | box-drawing overlay; palette filters results and supports Up/Down/Enter; focus stays inside until dismissed |
 | SplitPane, PaneGrid, Resizable, DockPanel | `│`/`─` separators, resize corner, or ordered dock regions |
 | ListView | visible rows with `>` on the selected item |
 | Toast | live status text |

data/examples/gallery.rb

@@ -22,6 +22,7 @@ module Gallery
       .child(Zaniah::Div.new.flex_row.items_center.gap(12).children([
         Zaniah::UI::Label.new("Label"), Zaniah::UI::Icon.new(:info, label: "Information"),
         Zaniah::UI::Badge.new("New", variant: :accent), Zaniah::UI::Avatar.new("Ruby UI"),
+        Zaniah::UI::Kbd.new("ctrl-shift-p", platform: :windows),
         Zaniah::UI::Spacer.new(4), Zaniah::UI::Skeleton.new]))
       .child(Zaniah::UI::Divider.new)
       .child(Zaniah::UI::EmptyState.new("No results", message: "Try another query").h(64))

data/examples/native_menu.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Run on macOS with a graphical session. Check File, Edit, Window, Cmd+S,
+# disabled and checked items, and the Recent submenu after opening it twice.
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "zaniah/ui"
+
+raise "native_menu.rb requires macOS" unless RUBY_PLATFORM.include?("darwin")
+
+app = Zaniah::App.new
+count = 0
+enabled = true
+checked = false
+window = nil
+app.actions.register(:save, title: "Save", enabled: ->(_cx) { enabled }) do |_cx|
+  count += 1
+  puts "Save invoked #{count} time(s)"
+  window.request_frame
+end
+app.actions.register(:toggle, title: "Checked item", checked: ->(_cx) { checked }) do |_cx|
+  checked = !checked
+  window.request_frame
+end
+app.actions.register(:enable_save, title: "Enable Save") do |_cx|
+  enabled = !enabled
+  puts "Save enabled: #{enabled}"
+end
+app.menu_bar = Zaniah::Menu.build do
+  app_menu
+  submenu "File" do
+    item :save
+    item :enable_save
+    separator
+    submenu "Recent", items: -> { Zaniah::Menu.build { item :save, title: "Example.txt" }.items }
+  end
+  submenu "Edit" do
+    standard_edit_items
+    separator
+    item :toggle
+  end
+  window_menu
+end
+window = app.open_window(backend: :mac, width: 500, height: 180, title: "Zaniah native menu") do
+  Zaniah::Div.new.p(24).child(Zaniah::UI::Label.new("Open File/Edit/Window; press Cmd+S. Saves: #{count}"))
+end
+window.dispatcher.keymap.bind("cmd-s", :save)
+if ARGV.include?("--check")
+  window.tick
+  cocoa = Zaniah::Platform::Mac::O
+  menu = cocoa.send(Zaniah::Platform::Mac::App.instance.handle, "mainMenu")
+  count = cocoa.send(menu, "numberOfItems", result: :long)
+  raise "native main menu was not installed (#{count} items)" unless count == 4
+  app.menu_bar = nil
+  window.tick
+  fallback = cocoa.send(Zaniah::Platform::Mac::App.instance.handle, "mainMenu")
+  raise "Quit-only menu was not restored" unless cocoa.send(fallback, "numberOfItems", result: :long) == 1
+  puts "Native menu installed"
+  window.close
+else
+  app.run
+end

data/lib/zaniah/accessibility/tree.rb

@@ -36,6 +36,15 @@ module Zaniah
 
       def find(&predicate) = each.find { |node, _path| predicate.call(node) }&.first
 
+      def query(role: nil, label: nil, states: {})
+        raise ArgumentError, "label must be a String or Regexp" unless label.nil? || label.is_a?(String) || label.is_a?(Regexp)
+        each.select do |node, _path|
+          (role.nil? || node.role == role) &&
+            (label.nil? || (node.label && (label.is_a?(Regexp) ? label.match?(node.label) : node.label == label))) &&
+            states.all? { |key, value| node.states.key?(key) && node.states[key] == value }
+        end
+      end
+
       def perform(node, action)
         owner = @action_owners&.[](node.object_id)
         owner&.accessibility_action(node, action)

data/lib/zaniah/app.rb

@@ -7,13 +7,14 @@ require_relative "task_executor"
 
 module Zaniah
   class App
-    attr_reader :windows, :executor
+    attr_reader :windows, :executor, :actions, :menu_bar
 
     def initialize(clock: MONOTONIC_CLOCK)
       @slots, @generations, @free, @windows, @globals = [], [], [], [], {theme: Theme.dark}
       @listeners, @effects, @updating, @flushing = {}, [], 0, false
       @clock = clock
       @executor = TaskExecutor.new(clock: clock)
+      @actions = Input::ActionRegistry.new
     end
 
     def new_entity
@@ -107,6 +108,7 @@ module Zaniah
       options[:clock] ||= @clock
       window = Platform.open_window(**options)
       window.app = self
+      window.dispatcher.window = window
       @windows << window
       @globals[:theme] = platform_theme(window)
       window.on_appearance do |appearance|
@@ -129,6 +131,13 @@ module Zaniah
       @executor.shutdown
     end
 
+    def menu_bar=(menu)
+      raise ArgumentError, "menu_bar must be a Zaniah::Menu or nil" unless menu.nil? || menu.is_a?(Menu)
+      @menu_bar = menu
+      @windows.each(&:request_frame)
+      menu
+    end
+
     def hot_reload(paths, **options, &block)
       require_relative "devtools"
       reload = DevTools::HotReload.new(self, paths, **options, &block)

data/lib/zaniah/clipboard.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Zaniah
+  module Clipboard
+    class Item
+      attr_reader :types, :formats
+
+      def initialize(formats)
+        raise TypeError, "clipboard formats must be a Hash" unless formats.is_a?(Hash)
+
+        @formats = formats.each_with_object({}) do |(type, value), result|
+          unless type.is_a?(String) && type.match?(/\A[^\s\/]+\/[^\s\/]+\z/)
+            raise ArgumentError, "invalid clipboard MIME type #{type.inspect}"
+          end
+          raise TypeError, "clipboard data must be a String" unless value.is_a?(String)
+
+          data = value.dup
+          if type.start_with?("text/")
+            data = data.encoding == Encoding::BINARY ? data.force_encoding(Encoding::UTF_8) : data.encode(Encoding::UTF_8)
+            raise Encoding::InvalidByteSequenceError, "invalid UTF-8 clipboard text" unless data.valid_encoding?
+          else
+            data.force_encoding(Encoding::BINARY)
+          end
+          result[type.dup.freeze] = data.freeze
+        end.freeze
+        @types = @formats.keys.freeze
+        freeze
+      end
+
+      def fetch(type) = @formats.fetch(type)
+
+      def ==(other) = other.instance_of?(self.class) && @formats == other.formats
+      alias eql? ==
+      def hash = [self.class, @formats].hash
+    end
+
+    class Content < Item
+    end
+  end
+end

data/lib/zaniah/configuration.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zaniah
-  Configuration = Struct.new(:font_raster, :shaper, :font_db, :segmenter, keyword_init: true)
+  Configuration = Struct.new(:font_raster, :shaper, :font_db, :segmenter, :matcher, keyword_init: true)
 end