zaniah 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74d3240032d7ae845a8a1f8f3208cb102ef0b68637cc184ba0f8860ac57b05ee
-  data.tar.gz: 4166002c76247745610218aed5d9090459889b9b383b97b669b199adac46761b
+  metadata.gz: 0e4185eb60f475f07fb3deee4bf07f0e7e16240771ee9199f9783d3fe13130cb
+  data.tar.gz: 05cafb090e57d8552cda0826d8db0ff1fa980107eab05ab9841824d6a18187c6
 SHA512:
-  metadata.gz: d3e80aba0a90f7e946ce916e63e3eed342cac2b1c0eda9cb9dd14112f1c1a9affd4d0ee13bc2cfc81769bcbd12afa4288849825fe1a093396b6ee43893f68a7d
-  data.tar.gz: a1bd580a3da60ac7705f4329d7f7a4b435bdd85638e074710a84b2339a40744e5b1e82d7df243ac9eff439a29ca359e6737e7fa731cb86b6dbedd62b585e5db3
+  metadata.gz: e5da9a69b48d186dcb04cf71cf48922d9e72fd019ff54919451f028cc211262fd8c49ecf85eb6dbbfd8b48213ad324ab98aefc9079473ace7d8a289401079ae4
+  data.tar.gz: f2b7ada32c16d932143db6cf68a9c2073e085ef0cda762aa7ed2f07ae7fdee5b9d5b1f5c3a5289b5fc54930fab9dbef1c0720e8035656c8ac700a2904012f431

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

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 |
@@ -83,8 +84,8 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | 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 |
@@ -106,8 +107,8 @@ input order. Pass `matcher:` to either component, or set a default with
 `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 and disables
-unavailable actions; shortcuts will be added with `UI::Kbd` in the menu phase.
+`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,
@@ -143,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/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/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,7 +17,7 @@ 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 |

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/app.rb

@@ -7,7 +7,7 @@ require_relative "task_executor"
 
 module Zaniah
   class App
-    attr_reader :windows, :executor, :actions
+    attr_reader :windows, :executor, :actions, :menu_bar
 
     def initialize(clock: MONOTONIC_CLOCK)
       @slots, @generations, @free, @windows, @globals = [], [], [], [], {theme: Theme.dark}
@@ -131,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/element.rb

@@ -3,6 +3,7 @@
 module Zaniah
   class Element
     include LengthUnits
+    WINDOW_CONTROLS = %i[close minimize maximize restore fullscreen].freeze
 
     attr_reader :layout_node, :parent, :resolved_style
 
@@ -65,6 +66,14 @@ module Zaniah
     def tooltip_text = @tooltip
     def context_menu(items) = (@context_menu = items; self)
     def context_menu_items = @context_menu
+    def window_drag_region = (@window_drag_region = true; self)
+    def window_drag_region? = !!@window_drag_region
+    def window_control(kind)
+      raise ArgumentError, "unknown window control" unless WINDOW_CONTROLS.include?(kind)
+      @window_control_kind = kind
+      self
+    end
+    def window_control_kind = @window_control_kind
     def flex = style(display: :flex)
     def flex_row = style(flex_direction: :row)
     def flex_col = style(flex_direction: :column)
@@ -150,7 +159,7 @@ module Zaniah
         @focus_handle.focusable = !@static_flags.include?(:disabled)
         cx.dispatcher.register_focus(@focus_handle)
       end
-      unless @handlers.empty? && !@tooltip && !@context_menu && !@style_set.interactive? && !@focus_handle
+      unless @handlers.empty? && !@tooltip && !@context_menu && !@style_set.interactive? && !@focus_handle && !@window_drag_region && !@window_control_kind
         cx.dispatcher.hit(bounds, owner: self) do |event|
           if event.is_a?(Input::MouseDown) && event.button == :right && @context_menu
             cx.window.context_menu(@context_menu, position: event.position)

data/lib/zaniah/input/dispatcher.rb

@@ -13,7 +13,7 @@ module Zaniah
     end
 
     class Dispatcher
-      attr_reader :focused, :focus_origin, :focus_tree
+      attr_reader :focused, :previous_focused, :focus_origin, :focus_tree, :keymap
       attr_accessor :window
 
       def initialize(keymap: Keymap.default_ui)
@@ -30,7 +30,7 @@ module Zaniah
           return
         end
         @focused&.on_focus&.call(false)
-        @focused, @focus_origin = handle, origin
+        @previous_focused, @focused, @focus_origin = @focused, handle, origin
         handle&.on_focus&.call(true)
         reveal(handle)
       end

data/lib/zaniah/input/focus_tree.rb

@@ -49,6 +49,7 @@ module Zaniah
 
       def restore = @traps.pop
       def release_trap(handle) = @traps.delete(handle)
+      def allows?(handle) = @traps.empty? || handle.ancestors.include?(@traps.last)
 
       private
 

data/lib/zaniah/input/keymap.rb

@@ -166,6 +166,14 @@ module Zaniah
       end
 
       def bindings = @bindings.dup.freeze
+
+      def shortcut_for(action)
+        @bindings.reverse_each.find { |binding|
+          same_action = binding.action == action ||
+            ((binding.action.is_a?(Symbol) || binding.action.is_a?(String)) && binding.action.to_s == action.to_s)
+          same_action && binding.predicate.call({})
+        }&.keys&.join(" ")
+      end
     end
   end
 end

data/lib/zaniah/inspection.rb

@@ -112,6 +112,11 @@ module Zaniah
       handle = object.focus_handle if object.respond_to?(:focus_handle)
       items = object.context_menu_items if object.respond_to?(:context_menu_items)
       menu = items&.map { |label, callback| [label.dup.freeze, !callback.nil?].freeze }&.freeze if items.is_a?(Array)
+      if items.is_a?(Menu)
+        menu = items.resolve(registry: window.app&.actions, keymap: window.dispatcher.keymap).map do |item|
+          [item.title.to_s.freeze, item.submenu? || (!!item.action && window.dispatcher.available?(item.action) == :enabled)].freeze
+        end.freeze
+      end
       Entry.new(element: object, type: object.class.name.to_s.delete_prefix("Zaniah::").freeze,
         key: object.respond_to?(:identity_key) ? copy(object.identity_key) : nil,
         test_id: object.respond_to?(:test_id) ? copy(object.test_id) : nil,

data/lib/zaniah/menu.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Zaniah
+  class Menu
+    Item = Data.define(:action, :title, :shortcut, :role, :children, :dynamic) do
+      def separator? = role == :separator
+      def submenu? = role == :submenu
+    end
+
+    class Builder
+      attr_reader :items
+
+      def initialize(owner: nil)
+        @items, @owner = [], owner
+      end
+
+      def item(action, title: nil, shortcut: nil, role: nil)
+        raise ArgumentError, "menu action must be a Symbol or String" unless action.is_a?(Symbol) || action.is_a?(String)
+        raise ArgumentError, "menu title must be a String" unless title.nil? || title.is_a?(String)
+        raise ArgumentError, "menu shortcut must be a String" unless shortcut.nil? || shortcut.is_a?(String)
+        raise ArgumentError, "menu role must be a Symbol" unless role.nil? || role.is_a?(Symbol)
+        @items << Item.new(action: action, title: title, shortcut: shortcut, role: role, children: [].freeze, dynamic: nil)
+        self
+      end
+
+      def submenu(title, items: nil, &block)
+        raise ArgumentError, "provide either items: or a block" if items && block
+        raise ArgumentError, "submenu title must be a String" unless title.is_a?(String)
+        raise ArgumentError, "items: must be callable" if items && !items.respond_to?(:call)
+        children = block ? self.class.new(owner: @owner).tap { |builder| builder.instance_eval(&block) }.items : []
+        @items << Item.new(action: nil, title: title, shortcut: nil, role: :submenu,
+          children: children.freeze, dynamic: items)
+        self
+      end
+
+      def separator
+        @items << Item.new(action: nil, title: nil, shortcut: nil, role: :separator, children: [].freeze, dynamic: nil)
+        self
+      end
+
+      def app_menu = (special_menu(:app_menu); self)
+      def window_menu = (special_menu(:window_menu); self)
+
+      def standard_edit_items
+        item :undo
+        item :redo
+        separator
+        %i[cut copy paste select_all].each { |action| item(action) }
+        self
+      end
+
+      private
+
+      def method_missing(name, *args, **kwargs, &block)
+        return super unless @owner&.respond_to?(name, true)
+        @owner.__send__(name, *args, **kwargs, &block)
+      end
+
+      def respond_to_missing?(name, include_private = false) = @owner&.respond_to?(name, true) || super
+
+      def special_menu(role)
+        @items << Item.new(action: nil, title: nil, shortcut: nil, role: role, children: [].freeze, dynamic: nil)
+      end
+    end
+
+    attr_reader :items
+
+    def self.build(&block)
+      raise ArgumentError, "menu block is required" unless block
+      new(Builder.new(owner: block.binding.receiver).tap { |builder| builder.instance_eval(&block) }.items)
+    end
+
+    def initialize(items)
+      raise ArgumentError, "menu items must be Menu::Item values" unless items.is_a?(Array) && items.all? { |item| item.is_a?(Item) }
+      @items = items.dup.freeze
+    end
+
+    def resolve(registry: nil, keymap: nil, platform: RUBY_PLATFORM)
+      @items.filter_map { |item| resolve_item(item, registry, keymap, platform) }.freeze
+    end
+
+    def children_for(item, registry: nil, keymap: nil, platform: RUBY_PLATFORM)
+      children = item.dynamic ? dynamic_items(item.dynamic.call) : item.children
+      self.class.new(children).resolve(registry: registry, keymap: keymap, platform: platform)
+    end
+
+    private
+
+    def resolve_item(item, registry, keymap, platform)
+      return if %i[app_menu window_menu].include?(item.role) && !platform.to_s.match?(/darwin|mac/)
+      return item if item.separator?
+
+      command = registry&.command(item.action) if item.action
+      item.with(title: item.title || command&.title&.to_s || item.action&.to_s,
+        shortcut: item.shortcut || (item.action && keymap&.shortcut_for(item.action)))
+    end
+
+    def dynamic_items(value)
+      value = value.items if value.is_a?(Menu)
+      raise ArgumentError, "dynamic menu items must be Menu::Item values" unless value.is_a?(Array) && value.all? { |item| item.is_a?(Item) }
+      value
+    end
+  end
+end