@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/components/badge/badge.d.ts

@@ -1,3 +1,4 @@
+export type BadgeTone = 'blue' | 'teal' | 'green' | 'amber' | 'orange' | 'red' | 'pink' | 'violet' | 'slate';
 export type BadgeOptions = {
     /**
      * Visible badge text.
@@ -11,6 +12,13 @@ export type BadgeOptions = {
      * Semantic intent.
      */
     kind?: 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+    /**
+     * Categorical colour — a project, a label, a module — from
+     * the tone palette rather than the status set, so a tag never reads as a warning. When set it
+     * decides the colour and `kind` is ignored for it; `variant` still applies. Unknown names are
+     * ignored.
+     */
+    tone?: BadgeTone | null;
     /**
      * Fill treatment.
      */
@@ -29,7 +37,13 @@ export type BadgeOptions = {
     title?: string;
 };
 /**
- * Creates a status pill: a small, non-interactive label carrying a semantic colour.
+ * Categorical tones, in the order they are documented.
+ * @type {ReadonlyArray<BadgeTone>}
+ */
+export declare const BADGE_TONES: ReadonlyArray<BadgeTone>;
+/**
+ * Creates a status pill: a small, non-interactive label carrying a semantic colour — or, with
+ * `tone`, a categorical one.
  *
  * The badge is plain text content, so it needs no ARIA of its own. A badge without a label but
  * with a `title` is named for assistive technology through `role="img"`.
@@ -44,3 +58,9 @@ export declare function badge(opts?: BadgeOptions): HTMLSpanElement;
  * @returns {HTMLSpanElement}
  */
 export declare function badgeGroup(badges: HTMLSpanElement[]): HTMLSpanElement;
+/**
+ * Resolves a categorical tone name, or null for anything outside the palette.
+ * @param {unknown} value Requested tone.
+ * @returns {BadgeTone|null}
+ */
+export declare function normalizeBadgeTone(value: unknown): BadgeTone | null;

package/dist/types/components/button/button.d.ts

@@ -23,6 +23,11 @@ export type ButtonOptions = {
      * Whether the button is disabled.
      */
     disabled?: boolean;
+    /**
+     * Whether the button is working on its action — see
+     * `setButtonBusy()`.
+     */
+    busy?: boolean;
     /**
      * Native title text.
      */
@@ -48,3 +53,13 @@ export declare function button(opts?: ButtonOptions): HTMLButtonElement;
  * @returns {HTMLDivElement}
  */
 export declare function buttonGroup(buttons: HTMLButtonElement[]): HTMLDivElement;
+/**
+ * Marks a button as working on its action, or done. A busy button shows a spinner before its
+ * label, announces `aria-busy`, and ignores activation — but stays focusable, unlike a disabled
+ * one, so focus does not fall to the page while the work runs and the reader hears it finish.
+ * Works on any `.zx-btn`, including one the application built itself.
+ * @param {HTMLButtonElement} element
+ * @param {boolean} busy
+ * @returns {HTMLButtonElement} The same button.
+ */
+export declare function setButtonBusy(element: HTMLButtonElement, busy: boolean): HTMLButtonElement;

package/dist/types/components/calendar/calendar.d.ts

@@ -132,7 +132,9 @@ export type CalendarOptions = {
      */
     dateUnit?: 'milliseconds' | 'seconds';
     /**
-     * Localized component messages.
+     * Per-instance messages, keyed `calendar.*` (`calendar.today`,
+     * `calendar.next`, …). The bare keys of earlier versions (`today`, `next`) are still read, after the
+     * namespaced key, until the next major version.
      */
     msg?: Record<string, string>;
     /**
@@ -248,6 +250,68 @@ export type CalendarEventChangeDetail = {
 export type CalendarSetOptions = {
     silent?: boolean;
 };
+/** @typedef {import('./calendar-model.js').CalendarEvent} CalendarEvent */
+/** @typedef {import('./calendar-model.js').CalendarView} CalendarView */
+/** @typedef {import('./calendar-model.js').CalendarReader} CalendarReader */
+/**
+ * @typedef {Object} CalendarOptions
+ * @property {Record<string, any>[]} [events=[]] Event records.
+ * @property {Date|string|number|null} [date=null] Initial local anchor date; null uses today.
+ * @property {CalendarView} [view='month'] Initial view.
+ * @property {CalendarView[]} [views=['agenda','day','week','month','year']] Allowed views.
+ * @property {string|string[]} [locale] Intl locale override.
+ * @property {number} [weekStart=1] First weekday, 0 (Sunday) through 6 (Saturday).
+ * @property {boolean} [weekNumbers=true] Show ISO week numbers in month view.
+ * @property {boolean} [workweek=false] Show Monday–Friday in the week time grid.
+ * @property {number} [agendaDays=14] Number of days in agenda view.
+ * @property {number} [slotDuration=30] Time-grid snap interval in minutes.
+ * @property {number} [slotMinTime=0] First visible minute of the day.
+ * @property {number} [slotMaxTime=1440] Exclusive last visible minute of the day.
+ * @property {number} [scrollTime=480] Minute initially scrolled into view.
+ * @property {number} [eventLimit=3] Maximum visible month lanes before a More button.
+ * @property {boolean} [selectable=false] Enable pointer time-range selection.
+ * @property {boolean} [editable=false] Enable event moving and resizing.
+ * @property {boolean|null} [eventStartEditable=null] Global move override; null inherits editable.
+ * @property {boolean|null} [eventDurationEditable=null] Global resize override; null inherits editable.
+ * @property {boolean} [optimistic=true] Apply event proposals locally before persistence confirms.
+ * @property {boolean} [nowIndicator=true] Show the current-time line in day/week views.
+ * @property {Date|(() => Date)|null} [now=null] Current-time override for deterministic rendering.
+ * @property {boolean} [disabled=false] Disable toolbar, date, selection, and editing controls.
+ * @property {CalendarReader} [eventId='id'] Event ID reader.
+ * @property {CalendarReader} [eventTitle='title'] Event title reader.
+ * @property {CalendarReader} [eventStart='start'] Event start reader.
+ * @property {CalendarReader} [eventEnd='end'] Event end reader.
+ * @property {CalendarReader} [eventAllDay='allDay'] Event all-day reader.
+ * @property {CalendarReader} [eventColor='color'] Event colour reader.
+ * @property {CalendarReader} [eventLocation='location'] Event location reader.
+ * @property {CalendarReader} [eventEditable='editable'] Per-event move reader.
+ * @property {CalendarReader} [eventDurationEditable='durationEditable'] Per-event resize reader.
+ * @property {'milliseconds'|'seconds'} [dateUnit='milliseconds'] Unit for numeric event dates.
+ * @property {Record<string, string>} [msg] Per-instance messages, keyed `calendar.*` (`calendar.today`,
+ *   `calendar.next`, …). The bare keys of earlier versions (`today`, `next`) are still read, after the
+ *   namespaced key, until the next major version.
+ * @property {(event: CalendarEvent) => Node|string|null} [renderEvent] Optional safe event-content renderer.
+ * @property {(event: CustomEvent<{events: CalendarEvent[]}>) => void} [oneventschange] Programmatic event-data listener.
+ * @property {(event: CustomEvent<{view: CalendarView, oldView: CalendarView}>) => void} [onviewchange] View listener.
+ * @property {(event: CustomEvent<{view: CalendarView, start: Date, end: Date}>) => void} [ondateschange] Visible-range listener.
+ * @property {(event: CustomEvent<{event: CalendarEvent, jsEvent: Event}>) => void} [oneventclick] Event activation listener.
+ * @property {(event: CustomEvent<{event: CalendarEvent, jsEvent: Event}>) => void} [oneventdblclick] Event double-activation listener.
+ * @property {(event: CustomEvent<{date: Date, allDay: boolean, view: CalendarView, jsEvent: Event}>) => void} [ondateclick] Date/time activation listener.
+ * @property {(event: CustomEvent<{start: Date, end: Date, allDay: boolean, view: CalendarView, jsEvent: Event}>) => void} [onselect] Range-selection listener.
+ * @property {(event: CustomEvent<CalendarEventChangeDetail>) => void} [oneventchange] Move/resize proposal listener.
+ * @property {(event: CustomEvent<{date: Date, view: CalendarView, jsEvent: Event}>) => void} [onnew] New-event command listener.
+ * @property {(event: CustomEvent<{date: Date, count: number, jsEvent: Event}>) => void} [onmoreclick] Month-overflow listener.
+ */
+/**
+ * @typedef {Object} CalendarEventChangeDetail
+ * @property {CalendarEvent} event Proposed event.
+ * @property {CalendarEvent} oldEvent Previous event.
+ * @property {'move'|'resize'} action Edit action.
+ * @property {{milliseconds: number, days: number, minutes: number, endMilliseconds: number}} delta Edit delta.
+ * @property {Event} jsEvent Originating pointer or keyboard event.
+ * @property {() => boolean} revert Idempotent optimistic revert callback.
+ */
+/** @typedef {{silent?: boolean}} CalendarSetOptions */
 /**
  * Accessible, dependency-free agenda/day/week/month/year scheduling surface.
  * @fires Calendar#viewchange
@@ -513,10 +577,8 @@ export declare class Calendar extends Component<CalendarOptions> {
      */
     _dayCountLabel(day: Date, count: number): string;
     /**
-     * Resolves a message through the host translator, falling back to the built-in English text.
-     *
-     * Distinct from `msg()`: the built-in `msg` option answers the calendar's own vocabulary, so a
-     * dotted key falls past it to the host translator, which is what these strings never had.
+     * Resolves a message through `msg()`, falling back to the built-in English text. Redundant now
+     * that `msg()` ends in the default catalogue; kept until the private copies are removed.
      * @param {string} key Message key.
      * @param {string} fallback Built-in text, with `%1`-style placeholders.
      * @param {...unknown} args Interpolation values.

package/dist/types/components/card-view/card-view.d.ts

@@ -109,9 +109,10 @@ export type CardViewOptions = {
      */
     headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
     /**
-     * Accessible collection label.
+     * Accessible collection label; null resolves message
+     * `cardView.label`, "Card view".
      */
-    label?: string;
+    label?: string | null;
     onrecordaction?: (event: CustomEvent<Record<string, unknown>>) => void;
 };
 export type CardViewState = {
@@ -203,7 +204,8 @@ export type CardRecordGroup = {
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Card surface treatment.
  * @property {number} [loadingCount=6] Skeleton cards shown while loading.
  * @property {1|2|3|4|5|6} [headingLevel=3] Per-card title heading level.
- * @property {string} [label='Card view'] Accessible collection label.
+ * @property {string|null} [label=null] Accessible collection label; null resolves message
+ *   `cardView.label`, "Card view".
  * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onrecordaction]
  */
 /**
@@ -304,8 +306,9 @@ export declare class CardView extends RecordView {
  * @param {CardViewOptions['groupBy']} groupBy Group field or resolver.
  * @param {unknown[]} [groupOrder=[]] Preferred group ids.
  * @param {ViewField[]} [fields=[]] Complete fields for accessor-aware grouping.
+ * @param {string} [ungroupedLabel='Ungrouped'] Label of the group collecting records without a value.
  * @returns {CardRecordGroup[]} Deterministic groups.
  */
-export declare function groupCardRecords(records: ViewRecord[], groupBy: CardViewOptions['groupBy'], groupOrder?: unknown[], fields?: ViewField[]): CardRecordGroup[];
+export declare function groupCardRecords(records: ViewRecord[], groupBy: CardViewOptions['groupBy'], groupOrder?: unknown[], fields?: ViewField[], ungroupedLabel?: string): CardRecordGroup[];
 /** @param {unknown} value @returns {string} */
 export declare function normalizeCardWidth(value: unknown): string;

package/dist/types/components/card-view/record-card.d.ts

@@ -139,6 +139,13 @@ export type RecordCardOptions = {
      * Listener-free, owner-created controls such as a move handle.
      */
     controls?: Node[];
+    /**
+     * Resolves the card's built-in strings
+     * (`recordCard.select`, `recordCard.actions`, `recordCard.untitled`, `recordCard.selected`,
+     * `recordCard.notSelected`). An owning component passes its own `msg()`; omitted, the host
+     * translator and then the default English catalogue answer.
+     */
+    message?: (key: string, ...args: unknown[]) => string;
 };
 export type ResolvedRecordPreview = {
     /**
@@ -218,6 +225,10 @@ export type ResolvedRecordPreview = {
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Surface treatment.
  * @property {1|2|3|4|5|6} [headingLevel=3] Card title heading level.
  * @property {Node[]} [controls=[]] Listener-free, owner-created controls such as a move handle.
+ * @property {(key: string, ...args: unknown[]) => string} [message] Resolves the card's built-in strings
+ *   (`recordCard.select`, `recordCard.actions`, `recordCard.untitled`, `recordCard.selected`,
+ *   `recordCard.notSelected`). An owning component passes its own `msg()`; omitted, the host
+ *   translator and then the default English catalogue answer.
  */
 /**
  * @typedef {Object} ResolvedRecordPreview

package/dist/types/components/chart/chart.d.ts

@@ -22,6 +22,12 @@ export type ChartSpec = {
      * Engine-specific options.
      */
     options: Record<string, unknown>;
+    /**
+     * Whether the chart must not animate: the operating system asks
+     * for reduced motion, or the host sits inside a `data-zx-motion="reduced"` region. An adapter turns
+     * its engine's own animation off when this is true; `ChartJsAdapter` sets `animation: false`.
+     */
+    reducedMotion: boolean;
     /**
      * Point-selection callback.
      */
@@ -155,6 +161,9 @@ export type ChartOptions = {
  * @property {string} type Chart type.
  * @property {ChartData} data Chart data.
  * @property {Record<string, unknown>} options Engine-specific options.
+ * @property {boolean} reducedMotion Whether the chart must not animate: the operating system asks
+ *   for reduced motion, or the host sits inside a `data-zx-motion="reduced"` region. An adapter turns
+ *   its engine's own animation off when this is true; `ChartJsAdapter` sets `animation: false`.
  * @property {(detail: ChartSelectDetail) => void} onSelect Point-selection callback.
  */
 /**
@@ -223,6 +232,7 @@ export declare class Chart extends Component<ChartOptions> {
     _handle: ChartHandle;
     _destroyed: boolean;
     _observer: ResizeObserver;
+    _stopWatchingMotion: () => void;
     static cssName: string;
     /** @type {Readonly<ChartOptions>} */
     static defaults: Readonly<ChartOptions>;

package/dist/types/components/checklist/checklist.d.ts

@@ -29,6 +29,12 @@ export type ChecklistOptions = {
      * Fallback initial checked state.
      */
     defaultChecked?: boolean;
+    /**
+     * Whether the heading is left out. The group keeps the
+     * heading text as its accessible name (`aria-label`); a Field labelling the checklist names it
+     * instead, which is why the `checklist` field type sets this.
+     */
+    hideLabel?: boolean;
     /**
      * Async item loader.
      */
@@ -62,6 +68,9 @@ export type ChecklistLoadedDetail = {
  * @property {boolean} [search=true] Whether the search field is shown.
  * @property {number} [height=280] Maximum list height in pixels.
  * @property {boolean} [defaultChecked=false] Fallback initial checked state.
+ * @property {boolean} [hideLabel=false] Whether the heading is left out. The group keeps the
+ *   heading text as its accessible name (`aria-label`); a Field labelling the checklist names it
+ *   instead, which is why the `checklist` field type sets this.
  * @property {(() => Promise<ChecklistItem[]>|ChecklistItem[])|null} [load=null] Async item loader.
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
  * @property {(event: CustomEvent<ChecklistChangeDetail>) => void} [onchange] Change listener.

package/dist/types/components/code-editor/code-editor.d.ts

@@ -61,27 +61,14 @@ export type CodeEditorOptions = {
         value: string;
     }>) => void;
 };
-/**
- * @typedef {Object} CodeEditorOptions
- * @property {unknown} [value=''] Initial text.
- * @property {string} [name=''] Form field name.
- * @property {string} [language='text'] Language identifier shown to the user and exposed as data.
- * @property {string} [label='Code editor'] Accessible editor label.
- * @property {string} [placeholder=''] Placeholder text.
- * @property {number} [rows=12] Visible textarea rows.
- * @property {string} [indent='\t'] Text inserted by Tab and removed by Shift+Tab.
- * @property {'off'|'soft'|'hard'} [wrap='off'] Textarea wrapping behavior.
- * @property {boolean} [spellcheck=false] Whether browser spellcheck is enabled.
- * @property {boolean} [readOnly=false] Whether content can be selected but not changed.
- * @property {boolean} [disabled=false] Whether the editor is disabled.
- * @property {boolean} [status=true] Whether the line/column status is visible.
- * @property {(event: CustomEvent<{value:string}>) => void} [oninput] Input listener.
- * @property {(event: CustomEvent<{value:string}>) => void} [onchange] Change listener.
- */
 /**
  * Dependency-free source editor for structured text, Markdown, JSON and code. It deliberately uses
  * a native textarea: values remain text-safe, browser undo and IME behavior stay intact, and Tab /
  * Shift+Tab provide predictable indentation without a third-party editor runtime.
+ *
+ * Capturing Tab is what a code surface has to do, and it would be a keyboard trap if nothing undid
+ * it: Escape releases the capture until the next keystroke in the editor, so Escape then Tab (or
+ * Shift+Tab) moves focus out of the editor as it would leave any other field.
  * @fires CodeEditor#input
  * @fires CodeEditor#change
  * @extends {Component<CodeEditorOptions>}
@@ -95,6 +82,8 @@ export declare class CodeEditor extends Component<CodeEditorOptions> {
     _position: HTMLElement;
     _header: HTMLElement;
     _input: HTMLTextAreaElement;
+    /** Set by Escape: the next Tab moves focus instead of indenting. */
+    _tabReleased: boolean;
     static cssName: string;
     /** @type {CodeEditorOptions} */
     static defaults: CodeEditorOptions;

package/dist/types/components/context-menu/context-menu.d.ts

@@ -1,6 +1,6 @@
 import { Component } from '../../core/component.js';
 export type MenuItem = import('../../internal/menu-items.js').MenuItem;
-export type ContextMenuEntry = import('../../internal/menu-items.js').MenuEntry;
+export type ContextMenuEntry = import('../../internal/menu-items.js').MenuItem | import('../../internal/menu-items.js').MenuHeading | import('../../internal/menu-items.js').MenuSeparator | '-';
 export type ContextMenuOptions = {
     /**
      * Menu
@@ -35,7 +35,11 @@ export type ContextMenuOptions = {
     onclose?: (event: CustomEvent<Record<string, never>>) => void;
 };
 /** @typedef {import('../../internal/menu-items.js').MenuItem} MenuItem */
-/** @typedef {import('../../internal/menu-items.js').MenuEntry} ContextMenuEntry */
+/**
+ * A context menu's entries: the shared menu model without `choice` rows, which a menu that closes
+ * on every activation cannot hold.
+ * @typedef {import('../../internal/menu-items.js').MenuItem|import('../../internal/menu-items.js').MenuHeading|import('../../internal/menu-items.js').MenuSeparator|'-'} ContextMenuEntry
+ */
 /**
  * @typedef {Object} ContextMenuOptions
  * @property {ContextMenuEntry[]|((context: Element|null) => ContextMenuEntry[])} [items=[]] Menu

package/dist/types/components/data-filter/data-filter.d.ts

@@ -37,7 +37,7 @@ export type SelectFilterDefinition = {
      */
     options?: Array<unknown | DataFilterOption>;
     /**
-     * Empty option label.
+     * Empty option label; omitted resolves message `dataFilter.all`, "All".
      */
     emptyLabel?: string;
 };
@@ -94,7 +94,7 @@ export type DataFilterOptions = {
      */
     autoApply?: boolean;
     /**
-     * Clear button label; null resolves `dataFilter.clear`.
+     * Clear button label; null resolves message `dataFilter.clear`, "Clear".
      */
     clearLabel?: string | null;
     onfilter?: (event: CustomEvent<DataFilterEventDetail>) => void;
@@ -118,7 +118,7 @@ export type DataFilterEventDetail = {
  * @property {Array<string|((row: DataFilterRow) => unknown)>} [fields] Row fields combined with OR.
  * @property {(row: DataFilterRow) => unknown} [get] Custom value accessor.
  * @property {Array<unknown|DataFilterOption>} [options] Explicit options; omitted derives distinct values.
- * @property {string} [emptyLabel] Empty option label.
+ * @property {string} [emptyLabel] Empty option label; omitted resolves message `dataFilter.all`, "All".
  */
 /**
  * @typedef {Object} TextFilterDefinition
@@ -142,7 +142,7 @@ export type DataFilterEventDetail = {
  * @property {FilterDefinition[]} [filters=[]] Declarative filters.
  * @property {DataFilterRow[]} [data=[]] Rows to filter.
  * @property {boolean} [autoApply=true] Apply and emit whenever a control changes.
- * @property {string|null} [clearLabel=null] Clear button label; null resolves `dataFilter.clear`.
+ * @property {string|null} [clearLabel=null] Clear button label; null resolves message `dataFilter.clear`, "Clear".
  * @property {(event: CustomEvent<DataFilterEventDetail>) => void} [onfilter]
  */
 /** @typedef {{rows: DataFilterRow[], state: Record<string, unknown>}} DataFilterEventDetail */

package/dist/types/components/datebox/date-range-box.d.ts

@@ -29,7 +29,8 @@ export type DateRangeBoxOptions = {
      */
     placeholder?: string | null;
     /**
-     * Show a clear button while a range is present.
+     * Show a clear button while a range is present and the box is
+     * enabled; without it the input keeps no room for one.
      */
     clearable?: boolean;
     /**
@@ -119,6 +120,7 @@ export declare function formatRangeText(range: DateRange | null, format: string,
 export declare class DateRangeBox extends Component<DateRangeBoxOptions> {
     _originalState: string;
     _originalAriaDisabled: string;
+    _originalClearable: string;
     _format: string;
     _separator: string;
     _disabled: boolean;
@@ -209,6 +211,8 @@ export declare class DateRangeBox extends Component<DateRangeBoxOptions> {
     _placeholder(): string;
     /** @returns {void} */
     _syncDisplay(): void;
+    /** A disabled box offers no clear button: there is nothing it could do. @returns {void} */
+    _syncClear(): void;
     /** @returns {void} */
     _syncDisabled(): void;
     /** @returns {void} */

package/dist/types/components/datebox/datebox.d.ts

@@ -26,7 +26,8 @@ export type DateboxOptions = {
      */
     placeholder?: string | null;
     /**
-     * Show a clear button when a value is present.
+     * Show a clear button while a value is present and the box is
+     * enabled; without it the input keeps no room for one.
      */
     clearable?: boolean;
     /**
@@ -66,7 +67,8 @@ export type DateboxUnit = 'date' | 'seconds';
  * @property {Date|null} [min=null] Earliest selectable date.
  * @property {Date|null} [max=null] Latest selectable date.
  * @property {string|null} [placeholder=null] Input placeholder; null derives one from the format.
- * @property {boolean} [clearable=true] Show a clear button when a value is present.
+ * @property {boolean} [clearable=true] Show a clear button while a value is present and the box is
+ *   enabled; without it the input keeps no room for one.
  * @property {boolean} [disabled=false] Disable all controls.
  * @property {(event: CustomEvent<{date: Date|null}>) => void} [onchange] Change listener.
  * @property {(event: CustomEvent<{text: string}>) => void} [oninvalid] Invalid-input listener.
@@ -86,6 +88,7 @@ export type DateboxUnit = 'date' | 'seconds';
 export declare class Datebox extends Component<DateboxOptions> {
     _originalState: string;
     _originalAriaDisabled: string;
+    _originalClearable: string;
     _format: string;
     _disabled: boolean;
     _open: boolean;
@@ -142,6 +145,8 @@ export declare class Datebox extends Component<DateboxOptions> {
     _normalizeValue(value: Date | number | string | null | unknown): Date | null;
     /** @returns {void} */
     _syncDisplay(): void;
+    /** A disabled box offers no clear button: there is nothing it could do. @returns {void} */
+    _syncClear(): void;
     /** @returns {void} */
     _syncDisabled(): void;
     /** @returns {void} */

package/dist/types/components/dialog/dialog.d.ts

@@ -50,7 +50,7 @@ export type DialogOptions = {
         toElement: () => Node | null;
     } | null;
     /**
-     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
      */
     scope?: Element | string | null;
     /**
@@ -137,6 +137,14 @@ export type ConfirmOptions = {
      * Whether the confirmation action is dangerous.
      */
     danger?: boolean;
+    /**
+     * Text the reader must type before the confirm button
+     * enables — the name of what is about to be deleted, say. The dialog adds an input labelled
+     * "Type <confirmText> to confirm" (message `dialog.typeToConfirm`, `%1` standing for the text),
+     * focuses it, and enables the confirm button, and Enter, only while its value matches exactly,
+     * ignoring surrounding spaces.
+     */
+    confirmText?: string | null;
 };
 export type PromptOptions = {
     /**
@@ -155,6 +163,14 @@ export type PromptOptions = {
      * Input placeholder.
      */
     placeholder?: string;
+    /**
+     * Confirmation label.
+     */
+    okLabel?: string;
+    /**
+     * Cancellation label.
+     */
+    cancelLabel?: string;
 };
 /** @typedef {'default'|'primary'|'danger'|'ghost'} DialogButtonKind */
 /**
@@ -173,7 +189,7 @@ export type PromptOptions = {
  * @property {DialogButton[]} [buttons=[]] Footer buttons.
  * @property {boolean} [closable=true] Whether Escape and the header button may close the dialog.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Body content.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -204,6 +220,11 @@ export type PromptOptions = {
  * @property {string} [okLabel='OK'] Confirmation label.
  * @property {string} [cancelLabel='Cancel'] Cancellation label.
  * @property {boolean} [danger=false] Whether the confirmation action is dangerous.
+ * @property {string|null} [confirmText=null] Text the reader must type before the confirm button
+ *   enables — the name of what is about to be deleted, say. The dialog adds an input labelled
+ *   "Type <confirmText> to confirm" (message `dialog.typeToConfirm`, `%1` standing for the text),
+ *   focuses it, and enables the confirm button, and Enter, only while its value matches exactly,
+ *   ignoring surrounding spaces.
  */
 /**
  * @typedef {Object} PromptOptions
@@ -211,6 +232,8 @@ export type PromptOptions = {
  * @property {Node|string|number|null} [message=''] Prompt message.
  * @property {string} [value=''] Initial input value.
  * @property {string} [placeholder=''] Input placeholder.
+ * @property {string} [okLabel='OK'] Confirmation label.
+ * @property {string} [cancelLabel='Cancel'] Cancellation label.
  */
 /**
  * Structured modal with a title, body, footer actions, and switchable views.
@@ -285,17 +308,18 @@ export declare class Dialog extends Modal {
      */
     static alert({ title, message, okLabel }?: AlertOptions): Promise<void>;
     /**
-     * Opens a confirmation dialog.
+     * Opens a confirmation dialog. With `confirmText` it becomes a type-to-confirm dialog: the
+     * confirm button stays disabled until the reader has typed that text.
      * @param {ConfirmOptions} [options={}] Confirmation options.
-     * @returns {Promise<boolean>}
+     * @returns {Promise<boolean>} True when confirmed; false on Cancel, Escape, or the close button.
      */
-    static confirm({ title, message, okLabel, cancelLabel, danger }?: ConfirmOptions): Promise<boolean>;
+    static confirm({ title, message, okLabel, cancelLabel, danger, confirmText }?: ConfirmOptions): Promise<boolean>;
     /**
      * Opens a single-line text prompt.
      * @param {PromptOptions} [options={}] Prompt options.
      * @returns {Promise<string|null>}
      */
-    static prompt({ title, message, value, placeholder }?: PromptOptions): Promise<string | null>;
+    static prompt({ title, message, value, placeholder, okLabel, cancelLabel }?: PromptOptions): Promise<string | null>;
     /**
      * Applies the dialog width. Subclasses that size themselves on a different axis override this.
      *
@@ -313,6 +337,22 @@ export declare class Dialog extends Modal {
      */
     _message(key: string, fallback: string): string;
 }
+/**
+ * Reports whether what the reader typed confirms a type-to-confirm dialog: the same text, exactly
+ * — case and inner spacing included — once surrounding spaces are ignored on both sides.
+ * @param {unknown} typed Input value.
+ * @param {unknown} expected Text the dialog asks for.
+ * @returns {boolean}
+ */
+export declare function typedConfirmation(typed: unknown, expected: unknown): boolean;
+/**
+ * Splits the type-to-confirm message around `%1`, where the text to type goes. A translation that
+ * leaves `%1` out gets the text after it, following a space; a second `%1` is filled in as text.
+ * @param {string} template Message such as "Type %1 to confirm".
+ * @param {string} expected Text to type.
+ * @returns {[string, string]} The text before and after the text to type.
+ */
+export declare function typeToConfirmParts(template: string, expected: string): [string, string];
 /**
  * Copies footer-button descriptors without mutating the caller's array or objects, and settles
  * the two booleans the footer renders from.

package/dist/types/components/dropdown/dropdown.d.ts

@@ -1,6 +1,4 @@
 import { Component } from '../../core/component.js';
-declare const HANDLE_POINTER_DISMISS: unique symbol;
-declare const HANDLE_ESCAPE_DISMISS: unique symbol;
 export type DropdownOptions = {
     /**
      * Panel content.
@@ -29,7 +27,7 @@ export type DropdownOptions = {
      */
     closeOnSelect?: boolean;
     /**
-     * Element whose nearest Zx theme scope owns the panel; defaults to the anchor.
+     * Element whose nearest Zx theme scope owns the panel; defaults to the anchor. Resolved on every open, so an anchor connected after construction still gets its scope.
      */
     scope?: Element | string | null;
     /**
@@ -49,12 +47,22 @@ export type DropdownOptions = {
  * @property {boolean} [matchWidth=false] Whether the panel matches the anchor width.
  * @property {'click'|'manual'} [openOn='click'] Trigger behavior.
  * @property {boolean} [closeOnSelect=false] Whether a click within the panel closes it.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the panel; defaults to the anchor.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the panel; defaults to the anchor. Resolved on every open, so an anchor connected after construction still gets its scope.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
  */
 /**
  * Generic anchored floating panel using the browser popover top layer.
+ *
+ * Open, the panel is one entry on the overlay stack (`core/overlay-stack.js`): Escape closes it
+ * only while it is the topmost layer that takes Escape, a press outside it and every overlay opened
+ * from it closes it, and it closes with the overlay its anchor sits in. Inside an open dialog the
+ * panel is hosted by that dialog, so `showModal()` does not make it inert.
+ *
+ * The panel follows its trigger in the Tab order: Tab on the anchor of an open panel moves into
+ * the panel's first focusable control (or onto the panel itself when it carries a `tabindex`),
+ * Tab past the panel's last control continues after the anchor, and Shift+Tab from the first goes
+ * back to the anchor. Closing while focus is inside returns it to the anchor.
  * @fires Dropdown#open
  * @fires Dropdown#close
  * @extends {Component<DropdownOptions>}
@@ -115,9 +123,16 @@ export declare class Dropdown extends Component<DropdownOptions> {
      * @returns {void}
      */
     destroy(): void;
-    /** @param {PointerEvent} event @returns {void} */
-    [HANDLE_POINTER_DISMISS](event: PointerEvent): void;
-    /** @param {KeyboardEvent} event @returns {void} */
-    [HANDLE_ESCAPE_DISMISS](event: KeyboardEvent): void;
+    /**
+     * Internal seam for components built on a Dropdown (MenuButton, ContextMenu, the app rail):
+     * replaces what Escape does when the overlay stack routes it to this panel, and takes the panel
+     * out of the anchor's Tab order — a menu is reached with the arrow keys, not Tab.
+     * @param {{onEscape?: ((event: KeyboardEvent) => void)|null, tabReach?: boolean}} settings
+     * @returns {this}
+     * @internal
+     */
+    _configure(settings: {
+        onEscape?: ((event: KeyboardEvent) => void) | null;
+        tabReach?: boolean;
+    }): this;
 }
-export {};

package/dist/types/components/entity-ref/entity-ref.d.ts

@@ -115,7 +115,7 @@ export type EntityRefOptions = {
      */
     actions?: EntityRefActionEntry[];
     /**
-     * Density-independent identity size.
+     * Size of the icon and the identity text.
      */
     size?: 'sm' | 'md' | 'lg';
     /**
@@ -230,7 +230,7 @@ export type EntityRefState = {
  * @property {EntityRefMetadata[]} [metadata=[]] Labelled dense metadata.
  * @property {EntityRefLinkValue} [link=null] Optional native primary link.
  * @property {EntityRefActionEntry[]} [actions=[]] Secondary controls; element actions keep their own behavior.
- * @property {'sm'|'md'|'lg'} [size='md'] Density-independent identity size.
+ * @property {'sm'|'md'|'lg'} [size='md'] Size of the icon and the identity text.
  * @property {boolean} [wrap=false] Whether long identity text may wrap instead of truncating.
  * @property {string} [actionsLabel='Entity actions'] Accessible name for secondary actions.
  * @property {(event: CustomEvent<{id: unknown, entity: Readonly<EntityRefState>, href: string, event: MouseEvent}>) => void} [onactivate]