zaniah 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc06ae1720a8d05abbc0da78849a355f7c36565c62b3907f941c80dd066594c5
-  data.tar.gz: fd00f6d9bd08c097a5ffa35ce079a83f949c07874d6ff7c76cdc802f7ddd8129
+  metadata.gz: 3a6d77e1edea911ee42064986e375f163213f45bedaeda9c6f3e409b42914cbd
+  data.tar.gz: 21970a583f79a01502abf982811820361a7628dc0ffffca0a2f308fa4852a6b7
 SHA512:
-  metadata.gz: 769bfa73b348d773f2139eb34039a7250f6878986375bdd25c361c3922b16d61ab68a3d14c59f8ef7f3cfd68e04a43d868286b624d1996d2fc2afdb92b23f861
-  data.tar.gz: a9642fa580bd9595e15c48903e698b95dfc5a6f876ca0d71438e488899522e2855351cef18a124e005dae5636e53b500aa46e90e101575c12796fc4e9ae80992
+  metadata.gz: 83d536f11608784994079181c05524fb3935cddf6076728967b78fc54b48ae91889c387efc047159f767dac8743ae5cb89f7c3497f75afa7b733133f6bc7e982
+  data.tar.gz: caa3b692cbe5435abc9571b0ccc3a09dc46db71c022a0ab2f80903dab7336c3818c3ae05ecc3ee6a0aa8ba657fb45bfa61a5218ec236546f229ba9d80614ace2

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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.
+- Add vertical writing, ruby annotations, inline embeds, and richer text decoration.
+- Add a viewport-based code editor with optional buffer and syntax-highlighter adapters.
+- Use DirectWrite shaping on Windows while retaining portable text fallback.
+
 ## 0.9.0 — 2026-09-24
 
 - Add semantic vector recording for UI scenes, including text, images, and raster fallbacks for unsupported drawing.

data/docs/adr/019-bidirectional-caret-affinity.md

@@ -0,0 +1,35 @@
+# ADR 019: Bidirectional caret affinity
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+UTF-8 byte offsets identify logical text positions, but a boundary between
+left-to-right and right-to-left runs can appear at two visual positions. A
+single `offset → x` mapping therefore loses information needed for pointer
+selection and arrow-key movement. Keeping logical movement only would avoid
+this ambiguity but would make arrow keys travel opposite to their visual
+direction inside right-to-left text. Storing display-order text instead would
+break editing, copying, and external byte-offset contracts.
+
+## Decision
+
+Keep text and selection offsets in logical UTF-8 byte order. A rendered line
+may associate an offset with upstream and downstream visual caret positions.
+Pointer hit testing returns both offset and affinity; existing offset-only
+methods remain as compatibility shortcuts. Arrow keys move through visual
+carets by default, while `caret_movement: :logical` preserves storage-order
+movement for applications such as code editors.
+
+Selection is a logical byte range rendered as a set of visual rectangles.
+The Unicode Bidirectional Algorithm resolves the paragraph before line-local
+reordering; neither glyph painting nor hit testing changes stored text order.
+
+## Consequences
+
+The editing path must retain affinity separately from the selection offset,
+and callers that want an exact caret position must use the affinity-aware
+methods. Existing LTR offset and caret APIs keep their values. This decision
+can be revisited if a platform-specific native text editor is adopted as the
+storage and interaction model instead of the toolkit's own text buffer.

data/docs/adr/020-lightweight-code-editor-providers.md

@@ -0,0 +1,36 @@
+# ADR 020: Lightweight code editor provider boundaries
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+The original CodeEditor passed an entire document through one Text element and
+constructed a second Text element containing every line number. Both scale with
+the whole file, and the two elements disagree about row heights when code
+wraps. Applications may already have a rope buffer or incremental syntax
+highlighter; bundling either implementation here would duplicate their work.
+
+## Decision
+
+CodeEditor accepts a line-addressable buffer with `line_count`, `line(index)`,
+`line_start(index)`, `line_of(offset)`, `replace(range, text)`, `undo`, and
+`redo`. The default adapter wraps TextBuffer and indexes UTF-8 byte starts.
+`to_s` is optional for external providers. A highlighter supplies
+`tokens(line_index, text)` as byte ranges and scopes, and receives
+`edited(range, new_text)` after edits. Token scopes resolve through
+`theme.syntax`; the editor owns no parser or language grammar.
+
+The dedicated Surface uses List::HeightIndex to shape and paint only visible
+logical lines. A wrapped logical line owns all its display rows, so its line
+number is painted once at the first display row. The Surface owns one caret,
+one selection, IME candidate placement, standard text actions, and Tab
+indentation. The existing positional constructor remains accepted.
+
+## Consequences
+
+Buffer adapters must keep byte offsets stable and return UTF-8 lines. A
+highlighter can cache tokens incrementally, but may only paint within the
+current viewport. Multi-cursor editing, folding, LSP, and a minimap remain
+application concerns. Unknown row heights use an estimate until those rows
+are visited, so scrollbar position can refine as wrapped lines are measured.

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/adr/022-vertical-writing-and-ruby.md

@@ -0,0 +1,37 @@
+# ADR 022: Vertical writing and ruby clusters
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+Japanese documents need top-to-bottom lines, columns that progress right to
+left, and annotations adjacent to their parent text. Rotating an entire
+horizontal line would give incorrect caret, selection, wrapping, and ruby
+geometry. Inserting ruby readings into the text buffer would also corrupt
+logical UTF-8 offsets and copied text.
+
+## Decision
+
+`Paragraph`, `Text`, and `UI::RichText` accept `writing_mode: :vertical_rl`.
+The inline limit is measured top to bottom, and layout converts inline and
+cross axes to physical coordinates for painting and interaction. The built-in
+shaper uses OpenType `vmtx` advances and GSUB `vert`/`vrt2` when a font supplies
+them. Mixed orientation keeps CJK upright and rotates ordinary Latin glyphs;
+`:upright` suppresses that rotation. A RichText run can request
+`combine_upright: true` for a compact horizontal run inside a vertical line.
+
+Ruby is a style on a parent run, not buffer content. The run is an unbreakable
+editing cluster. Its annotation is centered above the parent in horizontal
+text or to its right in vertical text. Both parent and annotation contribute
+to inline/cross box size, but only the parent contributes to copied text.
+Accessibility and TUI readings include the annotation in parentheses.
+
+## Consequences
+
+Caret, hit testing, selection, and IME rectangles share the axis conversion
+used by painting; stored offsets remain logical UTF-8 byte offsets. Ruby and
+combine-upright cannot be combined on one run. The implementation does not
+claim full CSS Writing Modes or OpenType vertical typography: `VORG`, vertical
+GPOS kerning/mark positioning, and font-specific vertical baseline correction
+remain unsupported. Fonts without vertical tables use horizontal advances.

data/docs/components.md

@@ -32,6 +32,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 +43,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,6 +52,7 @@ 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 |
@@ -63,6 +66,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 +87,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 | `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 |
@@ -94,13 +102,35 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L5 | `Validation` | `required`, `format`, `length`, `number`, `rule` | composable rules | n/a |
 | L5 | `FormField` | `(name, value:, label:, control:, validation:, hint:)` | errors + describedby | group/control/alert |
 | L5 | `Form` | `field`, `on_change`, `on_submit`, `values`, `valid?` | validates before submit | form |
-| L5 | `CodeEditor` | `(value, language:, line_numbers:, read_only:)`; `on_change` | multiline editor with scrolling | textbox |
-| L5 | `RichText` | `(runs, selectable:, editable:)`; `apply`, `insert`, `delete`, `replace`, `paragraph_style` | styled editing, IME, range selection and caret | text/textbox |
+| L5 | `CodeEditor` | `(value, buffer:, highlighter:, wrap:, language:, line_numbers:, read_only:)`; `on_change` | viewport-only multiline editor with syntax scopes and Tab indentation | textbox |
+| L5 | `RichText` | `(runs, selectable:, editable:, writing_mode:, text_orientation:)`; `apply`, `insert`, `delete`, `replace`, `append`, `insert_embed`, `paragraph_style` | styled editing, inline embeds, ruby, vertical text, IME, range selection and caret | text/textbox |
 
 All input components are keyboard operable. Disabled controls remain visible but are
 removed from focus traversal. Overlay components close on Esc; modal overlays restore
 the previous focus. See [TUI](tui.md) for terminal representations.
 
+`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
@@ -111,9 +141,30 @@ It may also implement `refine(previous_matches, query)` for incremental queries.
 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.
-It is read-only by default; set `editable: true` to enable keyboard editing and IME.
+`bold`, `italic`, `size`, `color`, `font`, `link`, `underline` (`:single`, `:double`,
+`:wavy`), `underline_color`, `strikethrough`, `background`, `baseline`
+(`:superscript` or `:subscript`), `letter_spacing`, `ruby: "reading"`, and
+`combine_upright: true`. Ruby parent text is one unbreakable selection cluster;
+copying omits the annotation, while accessibility and TUI expose it in
+parentheses. Ruby and combine-upright cannot be set together on one run.
+`writing_mode: :vertical_rl` uses top-to-bottom lines and right-to-left columns;
+`text_orientation: :mixed` rotates ordinary Latin by default, whereas `:upright`
+keeps it upright. Paragraph styles include
+alignment, lists, levels, `indent`, `quote`, `background`, and before/after spacing.
+`insert_embed(offset, key:, width:, height:) { |cx| element }` stores U+FFFC in the
+text and lays the element out at that inline position. `append(text, style:)` reuses
+cached layouts for unchanged earlier fragments. RichText is read-only by default;
+set `editable: true` to enable keyboard editing and IME.
+
+`UI::CodeEditor` keeps the legacy positional constructor and also accepts a
+line-addressable `buffer:` with `line_count`, `line(index)`, `line_start(index)`,
+`line_of(offset)`, `replace(range, text)`, `undo`, and `redo`. A plain string or
+`TextBuffer` uses the bundled adapter. Optional `highlighter:` provides
+`tokens(line_index, text)` byte ranges with scopes and receives
+`edited(range, new_text)` notifications. Scopes use `theme.syntax` colors. Only
+visible logical lines are shaped; wrapped display rows share one line number.
+The editor supports one caret/selection, standard text actions, IME placement,
+and Tab indentation. See [ADR 020](adr/020-lightweight-code-editor-providers.md).
 
 ## Image decoding
 

data/docs/native.md

@@ -70,6 +70,41 @@ applications. macOS also preserves arbitrary MIME types under reversible
 Wayland use their native format mechanisms. Native clipboard exchange still
 depends on a running desktop session and should be checked on each target OS.
 
+## Typed drag and drop
+
+An element can declare the MIME types it accepts and optionally offer a drag
+source. `on_drag_over` returns `:copy`, `:move`, `:link`, or `:none`; the chosen
+operation must be offered by the source. A drop carries `Clipboard::Content`,
+its logical window position, and the operation. File drops also emit the older
+`Input::FileDrop` event so existing listeners continue to work.
+Offering `:move` requires `on_move:` to remove the source data; it runs once
+after a successful move, or when an X11 target acknowledges the `DELETE` selection.
+
+```ruby
+target.on_drop(types: ["image/png", "text/plain"]) do |drop, _cx|
+  insert(drop.content)
+end
+target.on_drag_over { |drag, _cx| drag.accepts?("image/png") ? :copy : :none }
+source.draggable do |_mouse, _cx|
+  Zaniah::DragData.new(items: [Zaniah::Clipboard::Item.new("text/plain" => "hello")], operations: [:copy])
+end
+```
+
+Headless records the source in `drag_history`; tests may call `drag_over` and
+`complete_drag` to deliver it deterministically. macOS uses AppKit dragging
+sessions; X11 uses XDND (Ctrl requests copy, Shift move, Ctrl+Shift link when
+offered); Wayland uses `wl_data_device`. A target needs `on_drop` and a matching
+MIME type before it can accept a drag. Wayland cannot offer
+link-only drags because its standard data-device action set has only copy and
+move. All desktop protocols depend on another application accepting the MIME
+type and operation. Windows currently preserves file drops through
+`WM_DROPFILES` compatibility and also uses OLE `IDataObject`/`IDropTarget` and
+`IDropSource` for typed data and native drag sources. A preview image is used
+on macOS; Windows, X11, and Wayland currently use the native default cursor
+without a custom preview. TUI has no cross-process drag protocol and only the
+in-process Headless test path.
+X11 XDND proxy windows are not supported.
+
 ## Window state and decorations
 
 `window.frame` uses logical screen coordinates; `window.state.to_h` can be saved

data/docs/text.md

@@ -38,18 +38,43 @@ Provider objects may be supplied instead of symbols:
 | `segmenter` | `grapheme_clusters(text)` | Strings that exactly partition the input |
 | `font_raster` | `rasterize(font, glyph_id, size:, subpixel_x:)` | A glyph bitmap |
 
+Shapers may additionally accept `script:`, `language:`, `direction:`,
+`features:`, and `writing_mode:`. The typesetter inspects accepted keywords, so an existing
+`shape(glyphs, size:, text:)` provider remains valid. If a provider does not
+accept `direction:`, a right-to-left run is shaped in storage order and its
+glyphs are reversed for display. Hebrew works with this fallback; Arabic
+joining in a legacy provider still requires a direction-aware shaper. The built-in shaper
+accepts `direction: :ltr/:rtl` and a four-character OpenType feature map such
+as `{"liga" => false}`.
+
 Providers may implement `close`; the text system closes them when it closes.
 Custom mutable providers used by `fork` must also implement `layout_copy` and
 return an independent provider.
 
 The default Ruby shaper supports horizontal Latin, CJK, and kana text, including
 common OpenType ligatures, contextual substitutions, pair positioning, and
-legacy kerning. It is not a replacement for full complex-script shaping:
-Arabic/Indic reordering, AAT `morx`, vertical text, complete mark positioning,
-and variation-index positioning are unsupported.
-
-Built-in rasterizers are `:native`/`:alhena`, `:freetype`, and `:coretext`
-(`:core_text` is an alias). FreeType and CoreText require their platform library.
+legacy kerning. For Arabic-script OpenType fonts with GSUB, it selects
+`isol`/`fina`/`medi`/`init` from Unicode 18 Joining_Type and then applies
+`rlig`; transparent marks and ZWJ/ZWNJ affect joining. The input `text:` is
+needed to select forms. Fonts using AAT `morx` (including some macOS Arabic
+fonts), advanced Arabic substitutions, complete mark and cursive positioning,
+Indic reordering, complete vertical GPOS positioning, and variation-index
+positioning still need an external shaper. The bundled Abel font has no Arabic
+glyphs. Vertical layout uses `vmtx` advances and GSUB `vert`/`vrt2` where
+available; fonts without vertical metrics retain horizontal advances.
+
+Built-in rasterizers are `:native`/`:alhena`, `:freetype`, `:coretext`
+(`:core_text` is an alias), and Windows-only `:directwrite` (`:direct_write`
+is an alias). FreeType, CoreText, and DirectWrite require their platform library.
+DirectWrite remains opt-in; Windows still defaults to `:native`. It loads fonts
+opened by `FontDB` from their file paths, and other in-memory fonts through the
+Windows 10 in-memory font loader. Its default atlas bitmap is grayscale;
+`Platform::Windows::DirectWrite#rasterize(..., antialias: :cleartype)` returns
+an RGB coverage bitmap for callers that can display subpixel coverage. Compare
+it with Alhena using `ruby examples/native_font.rb path/to/font.ttf --directwrite`
+on Windows. Variable-font instances with selected axes use Alhena's rasterizer
+until an axis-aware DirectWrite face is available. Close an explicitly created
+DirectWrite provider when finished.
 Unimplemented symbolic adapters raise `ArgumentError`; pass a provider object to
 integrate another shaper, segmenter, font database, or rasterizer.
 
@@ -121,6 +146,41 @@ offset = paragraph.hit_test(Zaniah::Point.new(40, 20))
 point = paragraph.offset_to_point(offset)
 ```
 
+Bidirectional text uses Unicode 18.0's UAX #9 rules, with Unicode tables
+generated by `tools/generate_unicode_tables.rb` and no runtime data download.
+`Text.new(value, text_direction: :auto)` detects paragraph direction; use
+`:ltr` or `:rtl` to override it. Layout-only callers may pass `direction:`
+to `layout_paragraph` or `layout_line`. `align: :start/:end` follows paragraph
+direction. Text remains in logical UTF-8 byte order for editing and copying.
+
+At a boundary between directional runs, the same byte offset can have two
+screen positions. `LineLayout#caret_x(offset, affinity: :downstream)` chooses
+one, and `LineLayout#hit_test(x)` returns `[offset, affinity]`. The old
+`x_for_index` and `index_for_x` methods remain available for callers that do
+not retain affinity. `selection_rects(range)` returns the visual rectangles
+occupied by a logical range. `Text.new(..., caret_movement: :logical)` opts
+out of the default visual left/right arrow movement.
+
+Vertical Japanese layout is opt-in. The `width:` argument to a vertical
+paragraph is its inline (top-to-bottom) limit; columns advance right to left.
+On `Text`, use `.h(...)` for that limit:
+
+```ruby
+paragraph = system.layout_paragraph("縦書き", width: 240,
+  writing_mode: :vertical_rl)
+text = Zaniah::Text.new("縦書き", writing_mode: :vertical_rl,
+  text_orientation: :mixed).h(240)
+```
+
+`text_orientation: :mixed` keeps CJK glyphs upright and rotates ordinary Latin
+letters and digits 90 degrees. `:upright` keeps all glyphs upright. Hit testing,
+caret, selection, composition underline, and IME bounds use vertical geometry;
+offsets and clipboard text stay in logical UTF-8 byte order. This is a
+lightweight vertical layout, not a complete CSS Writing Modes implementation:
+it does not implement `VORG`, vertical kerning/mark positioning, script-specific
+vertical baseline adjustment, or arbitrary sideways writing modes. Font support
+determines whether vertical glyph substitutions and metrics are available.
+
 Wrapping supports `:none`, `:word`, and `:anywhere`; Japanese kinsoku modes are
 `:push`, `:hanging`, and `:none`. Font fallback is selected per grapheme from the
 requested font through CJK, emoji, symbol, and general system faces. Colored
@@ -158,8 +218,21 @@ text.insert(text.text.bytesize, " — draft")
 text.paragraph_style(0...text.text.bytesize, align: :start, list: :bullet, level: 0)
 ```
 
-Supported inline styles are `bold`, `italic`, `size`, `color`, `font`, and
-`link`. Paragraph styles support `align: :start/:center/:end/:justify`,
+Supported inline styles include `bold`, `italic`, `size`, `color`, `font`,
+`link`, decoration/background styles, `ruby:`, and `combine_upright:`.
+`ruby: "reading"` annotates one unbreakable parent run; copying selects only
+the parent text, while accessibility and TUI readings include the annotation
+in parentheses. `combine_upright: true` keeps a short run such as `12` upright
+inside vertical text. Ruby and combine-upright cannot be combined on one run.
+
+```ruby
+rich = Zaniah::UI::RichText.new([
+  {text: "漢字", ruby: "かんじ"},
+  {text: "12", combine_upright: true}
+], writing_mode: :vertical_rl).h(240)
+```
+
+Paragraph styles support `align: :start/:center/:end/:justify`,
 `list: :none/:bullet/:ordered`, and nonnegative nesting levels. `on_change`
 receives `(text, rich_text)`; selection changes are reported by `on_select`.
 IME composition uses the existing `TextBuffer` composition path.

data/docs/theme.md

@@ -1,7 +1,7 @@
 # Themes and state styles
 
 `Zaniah::Theme.dark`, `.light`, and `.high_contrast` provide semantic color,
-spacing, radius, shadow, typography, and motion tokens. `App` installs the dark
+spacing, radius, shadow, typography, syntax, and motion tokens. `App` installs the dark
 theme by default and follows native window appearance changes. Read the active
 theme with `FrameContext#theme` or `EntityContext#theme`.
 
@@ -32,6 +32,9 @@ themes' raw color values.
 - `spacing`: a compact 4-pixel scale indexed by token number.
 - `radii` and `shadows`: semantic `none`, `sm`, `md`, `lg`, and `full` values.
 - `typography`: sans/mono families, six sizes, four weights, and three line heights.
+- `syntax`: keyword, string, comment, number, function, type, constant,
+  punctuation, operator, variable, and fallback text colors. `syntax.color(scope)`
+  accepts dotted highlighter scopes such as `"keyword.control"`.
 - `motion`: fast/base/slow durations, easing names, and `reduced?`.
 
 Records support `with`, so a local override does not mutate the shared theme:
@@ -45,6 +48,9 @@ quiet = base.with(
 app.global(:theme, quiet)
 ```
 
+Omitting `syntax:` in `Theme.new` derives readable syntax colors from `colors`.
+Pass a `Theme::Syntax` value to override them explicitly.
+
 Native windows select dark or light initially and refresh the application theme
 when system appearance changes. A system reduced-motion preference sets
 `theme.motion.reduced?` and collapses animation durations to zero.

data/docs/tui.md

@@ -8,28 +8,36 @@ tests and non-window integrations.
 | --- | --- |
 | Label, Badge, Avatar | text, `[badge]`, `(initials)` |
 | Kbd | textual shortcut, such as `Ctrl+Shift+P`; multiple strokes are space-separated |
+| Alert | persistent `! title: message`; dismissed alerts disappear, live alerts announce through accessibility |
 | 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 |
 | Button, IconButton, ToggleButton | `[ label ]`; disabled uses `( label )` |
 | Checkbox, Radio, Switch | `[x]`, `(o)`, `[on ]` |
+| SegmentedControl | `[A\|(B)\|C]`, with the selected segment in parentheses; arrows move selection |
 | Slider, RangeSlider | ten-cell track and numeric value/range |
 | 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 |
+| Calendar, DateRangePicker | month grid with selected day in `[dd]`; picker shows `[start – end]`, with `…` for an unfinished range |
 | Tooltip, Popover, Menu, MenuBar, Dropdown | status text or a box/menu with `>` selection marker; nested menus expose a Back row |
+| HoverCard | content text while open; hidden while closed; focus uses the same open delay as hover |
 | 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; palette filters results and supports Up/Down/Enter; focus stays inside until dismissed |
 | SplitPane, PaneGrid, Resizable, DockPanel | `│`/`─` separators, resize corner, or ordered dock regions |
+| ZoomPanView | zoom percentage and content text; focused `+`/`-`/`0` changes zoom, but pointer panning has no cell equivalent |
+| DockWorkspace | active tab in parentheses inside `[tabs]`, split groups separated by `│` or `───`; arrows select, Alt+arrows move and Ctrl+Shift+arrows split without dragging |
 | ListView | visible rows with `>` on the selected item |
 | Toast | live status text |
 | Table, DataGrid | header and visible rows separated with `|` |
 | TreeView | indentation with `▸`/`▾` expansion markers |
+| PropertyGrid | up to 20 `label: value` rows, with `!` and the validation message on errors; Up/Down/Page keys move the virtual row selection |
 | Sparkline and all chart types | eight-level Unicode sparkline summary |
 | Form, FormField | labeled values, `!` errors, and a submit button |
-| CodeEditor, RichText | numbered plain-text lines or concatenated text runs |
+| CodeEditor | numbered logical lines; wrap, syntax colors, and inline IME underline degrade to plain cells |
+| RichText | concatenated text runs; ruby readings appear in parentheses; inline embeds appear as U+FFFC and decoration/paragraph backgrounds and vertical geometry degrade to plain cells |
 
 Rounded corners, shadows, gradients, and alpha scrims reduce to solid cells. Focus is
 reported by the terminal cursor/reverse-video capability; motion introduced in M7 is

data/examples/gallery.rb

@@ -57,19 +57,43 @@ module Gallery
       .child(Zaniah::Div.new.flex_row.gap(12).children([
         Zaniah::UI::DatePicker.new("2026-09-13"), Zaniah::UI::TimePicker.new("14:30"),
         Zaniah::UI::ColorPicker.new("#2563eb")]))
+    feedback_dates = Zaniah::Div.new.w_full.gap(12)
+      .child(Zaniah::Div.new.flex_row.items_center.gap(16).children([
+        Zaniah::UI::SegmentedControl.new([["Day", :day], ["Week", :week], ["Month", :month]], value: :week),
+        Zaniah::UI::DateRangePicker.new(value: ["2026-09-01", "2026-09-30"])]))
+      .child(Zaniah::UI::Alert.new("Export complete", message: "Your file is ready", variant: :success, dismissible: true))
+      .child(Zaniah::UI::Calendar.new(value: "2026-09-24", week_start: 1))
+    dock_layout = Zaniah::UI::DockLayout.split(id: :work, orientation: :horizontal, ratio: 0.42,
+      first: Zaniah::UI::DockLayout.tabs(id: :left, panels: %i[Files Search]),
+      second: Zaniah::UI::DockLayout.tabs(id: :right, panels: %i[Editor Preview]))
+    property_schema = [
+      {key: :title, label: "Title", type: :text},
+      {key: :count, label: "Count", type: :number},
+      {key: :visible, label: "Visible", type: :boolean}
+    ]
     workspaces = Zaniah::Div.new.w_full.gap(12)
       .child(Zaniah::Div.new.flex_row.gap(12).children([
         Zaniah::UI::SplitPane.new(Zaniah::UI::Label.new("Left pane"), Zaniah::UI::Label.new("Right pane")).w(300).h(100),
         Zaniah::UI::Resizable.new(Zaniah::UI::Label.new("Resize me"), width: 180, height: 100),
         Zaniah::UI::ListView.new(%w[Alpha Beta Gamma Delta], height: 100, selected: 1).w(180)]))
-      .child(Zaniah::UI::DockPanel.new(
-        center: Zaniah::UI::Label.new("Editor"), top: Zaniah::UI::StatusBar.new(Zaniah::UI::Label.new("Top", size: :sm)),
-        left: Zaniah::UI::Sidebar.new(Zaniah::UI::Label.new("Files", size: :sm), width: 90),
-        bottom: Zaniah::UI::StatusBar.new(Zaniah::UI::Label.new("Ready", size: :sm))).w(420).h(120))
+      .child(Zaniah::Div.new.flex_row.gap(12).children([
+        Zaniah::UI::DockPanel.new(
+          center: Zaniah::UI::Label.new("Editor"), top: Zaniah::UI::StatusBar.new(Zaniah::UI::Label.new("Top", size: :sm)),
+          left: Zaniah::UI::Sidebar.new(Zaniah::UI::Label.new("Files", size: :sm), width: 90),
+          bottom: Zaniah::UI::StatusBar.new(Zaniah::UI::Label.new("Ready", size: :sm))).w(420).h(120),
+        Zaniah::UI::ZoomPanView.new(Zaniah::Div.new.w(110).h(70).p(8).bg("#2563eb")
+          .child(Zaniah::UI::Label.new("Zoom / pan", size: :sm)), zoom: 1.3).w(180).h(120)
+      ]))
+      .child(Zaniah::Div.new.flex_row.gap(12).children([
+        Zaniah::UI::DockWorkspace.new(dock_layout,
+          render: ->(id) { Zaniah::Div.new.p(10).child(Zaniah::UI::Label.new("#{id} panel")) }).w(440).h(190),
+        Zaniah::UI::PropertyGrid.new(property_schema,
+          {title: "Workspace", count: 3, visible: true}, height: 190).w(340)
+      ]))
     editors = Zaniah::Div.new.w_full.flex_row.gap(12).children([
       Zaniah::UI::CodeEditor.new("def hello\n  :world\nend\n", language: :ruby).w(390).h(150),
       Zaniah::UI::RichText.new([{text: "Rich ", size: 20}, {text: "text", color: "#2563eb", size: 20}]).w(260)])
-    Zaniah::Div.new.h(2480).p(16).gap(12)
+    Zaniah::Div.new.h(3200).p(16).gap(12)
       .child(section("Foundation", foundation, height: 180))
       .child(section("Actions",
         Zaniah::UI::Button.new("Primary").icon(:check).on_click(&clicks),
@@ -94,7 +118,8 @@ module Gallery
       .child(section("Variants", variants, height: 285))
       .child(section("Data", data, height: 440))
       .child(section("Choice and pickers", choices, height: 210))
-      .child(section("Workspace layout", workspaces, height: 300))
+      .child(section("Feedback and dates", feedback_dates, height: 410))
+      .child(section("Workspace layout", workspaces, height: 530))
       .child(section("Editors", editors, height: 210))
       .child(section("Forms", Zaniah::UI::Form.new.field(name: :email, label: "Release email", value: "ruby@example.com", validation: validation).w(320), height: 150))
   end
@@ -110,6 +135,7 @@ module Gallery
     when /\Atoast-(info|success|warning|danger)\z/ then Zaniah::UI::Toast.new("Saved", variant: Regexp.last_match(1).to_sym)
     when "tooltip" then Zaniah::UI::Tooltip.new("Helpful text", anchor: anchor)
     when "popover" then Zaniah::UI::Popover.new(content, anchor: anchor)
+    when "hover-card" then Zaniah::UI::HoverCard.new(Zaniah::UI::Label.new("Keyboard shortcuts"), anchor: anchor).open
     when "menu" then Zaniah::UI::Menu.new(items, anchor: Zaniah::Point.new(anchor.x, anchor.bottom))
     when "context-menu" then Zaniah::UI::ContextMenu.new(items, anchor: Zaniah::Point.new(anchor.x, anchor.bottom))
     when "modal" then Zaniah::UI::Modal.new(content, title: "Modal")