@zeyos/zx 4.3.4 → 5.0.0

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

@@ -1,11 +1,12 @@
 import { Component } from '../../core/component.js';
+export type AvatarTone = 'blue' | 'teal' | 'green' | 'amber' | 'orange' | 'red' | 'pink' | 'violet' | 'slate';
 export type AvatarOptions = {
     /**
      * Image URL.
      */
     src?: string | null;
     /**
-     * Name used to derive fallback initials.
+     * Name used to derive the fallback initials and tone.
      */
     name?: string;
     /**
@@ -17,13 +18,20 @@ export type AvatarOptions = {
      */
     label?: string | null;
     /**
-     * Preset (`sm`, `md`, `lg`) or pixel size.
+     * Preset — `sm` 24px, `md` 32px, `lg` 40px at the default
+     * spacing unit — or a pixel size. Below 24px the fallback shows a single initial.
      */
     size?: string | number;
     /**
      * Avatar shape.
      */
     shape?: 'circle' | 'rounded' | 'square';
+    /**
+     * Fallback colour from the tone palette. `null` derives a
+     * stable tone from the name (or the initials when there is no name), so the same person gets the
+     * same colour on every screen; see {@link avatarTone}.
+     */
+    tone?: AvatarTone | null;
     /**
      * Optional presence state.
      */
@@ -33,19 +41,35 @@ export type AvatarOptions = {
      */
     statusLabel?: string | null;
 };
+/**
+ * A categorical tone from the design system's tone palette (`--zx-color-tone-*`).
+ * @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} AvatarTone
+ */
 /**
  * @typedef {Object} AvatarOptions
  * @property {string|null} [src=null] Image URL.
- * @property {string} [name=''] Name used to derive fallback initials.
+ * @property {string} [name=''] Name used to derive the fallback initials and tone.
  * @property {string|null} [initials=null] Explicit fallback initials.
  * @property {string|null} [label=null] Accessible label; null makes the avatar decorative.
- * @property {string|number} [size='md'] Preset (`sm`, `md`, `lg`) or pixel size.
+ * @property {string|number} [size='md'] Preset — `sm` 24px, `md` 32px, `lg` 40px at the default
+ * spacing unit — or a pixel size. Below 24px the fallback shows a single initial.
  * @property {'circle'|'rounded'|'square'} [shape='circle'] Avatar shape.
+ * @property {AvatarTone|null} [tone=null] Fallback colour from the tone palette. `null` derives a
+ * stable tone from the name (or the initials when there is no name), so the same person gets the
+ * same colour on every screen; see {@link avatarTone}.
  * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state.
  * @property {string|null} [statusLabel=null] Text alternative for the presence state.
  */
 /**
- * Stable-size user image with deterministic initials fallback and optional presence state.
+ * The tone palette, in hash order. Every entry is a valid `tone`; the hash picks among the
+ * chromatic ones and keeps `slate`, the neutral, for a fallback with no name behind it. Order is
+ * part of the contract: changing it moves every derived avatar to a different colour.
+ * @type {ReadonlyArray<AvatarTone>}
+ */
+export declare const AVATAR_TONES: ReadonlyArray<AvatarTone>;
+/**
+ * Stable-size user image with a deterministic fallback — initials on a tone picked from the name —
+ * and an optional presence state.
  * @extends {Component<AvatarOptions>}
  */
 export declare class Avatar extends Component<AvatarOptions> {
@@ -61,6 +85,7 @@ export declare class Avatar extends Component<AvatarOptions> {
         label: string;
         size: string | number;
         shape: "circle" | "rounded" | "square";
+        tone: AvatarTone;
         status: "away" | "busy" | "offline" | "online";
         statusLabel: string;
     };
@@ -93,8 +118,22 @@ export declare class Avatar extends Component<AvatarOptions> {
     _syncStatus(): void;
 }
 /**
- * Derives at most two uppercase initials from the first and last words of a name.
+ * Derives uppercase initials from the first and last words of a name.
  * @param {unknown} name Name-like value.
+ * @param {1|2} [limit=2] How many initials to return: two by default, one for an avatar too small
+ * to hold two legibly.
  * @returns {string}
  */
-export declare function avatarInitials(name: unknown): string;
+export declare function avatarInitials(name: unknown, limit?: 1 | 2): string;
+/**
+ * Picks a stable fallback tone for a name.
+ *
+ * The name is trimmed, NFC-normalised and lower-cased, then hashed with 32-bit FNV-1a over its
+ * UTF-16 code units, and the hash picks one of the eight chromatic tones of {@link AVATAR_TONES}.
+ * The result depends on nothing but the name — not the locale, the page, or the order avatars
+ * render in — so a person keeps their colour everywhere. An empty name is `slate`, the neutral
+ * tone, which no name hashes to.
+ * @param {unknown} name Name-like value.
+ * @returns {AvatarTone}
+ */
+export declare function avatarTone(name: unknown): AvatarTone;

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

@@ -1,3 +1,7 @@
+export type ButtonShortcut = {
+    label: string;
+    keys: string;
+};
 export type ButtonOptions = {
     /**
      * Visible button label.
@@ -19,10 +23,19 @@ 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.
      */
     title?: string;
+    /**
+     * Keyboard hint; does not register a keyboard handler.
+     */
+    shortcut?: ButtonShortcut;
     /**
      * Click callback.
      */
@@ -40,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

@@ -504,6 +504,25 @@ export declare class Calendar extends Component<CalendarOptions> {
     _refreshNowIndicator(): void;
     /** @param {string} message @returns {void} */
     _announce(message: string): void;
+    /**
+     * Names a month or year cell by its date and how many events it holds. Singular and plural are
+     * separate keys because a language that inflects the noun cannot reach it from one template.
+     * @param {Date} day Day the cell stands for.
+     * @param {number} count Events on that day.
+     * @returns {string}
+     */
+    _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.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
 }
 /** @event Calendar#viewchange @type {CustomEvent<{view: CalendarView, oldView: CalendarView}>} */
 /** @event Calendar#dateschange @type {CustomEvent<{view: CalendarView, start: Date, end: Date}>} */

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

@@ -125,4 +125,11 @@ export declare class Card extends Component<CardOptions> {
     _renderHeading(): void;
     /** @returns {void} */
     _syncHeader(): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
 }

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

@@ -31,6 +31,10 @@ export type CardViewOptions = {
      * Record selection behavior.
      */
     selectable?: false | 'single' | 'multi';
+    /**
+     * Select through a checkbox or the non-interactive card surface.
+     */
+    selectionTrigger?: 'checkbox' | 'card';
     /**
      * Initially selected record ids.
      */
@@ -44,9 +48,10 @@ export type CardViewOptions = {
      */
     hiddenFields?: string[];
     /**
-     * Whether to expose shared field controls.
+     * Whether to expose shared field controls. `true` renders the chooser in the card toolbar and
+     * `false` omits it; an object customises its `label` and mounts it into `target`.
      */
-    fieldControls?: boolean;
+    fieldControls?: boolean | import('../view/record-view.js').ViewFieldControlsConfig;
     /**
      * Empty-result content.
      */
@@ -172,10 +177,13 @@ export type CardRecordGroup = {
  * @property {import('../view/record-view.js').ViewSort|null} [sort=null] Initial shared sort.
  * @property {'local'|'server'} [sortMode='local'] Local sorting or event-only server sorting.
  * @property {false|'single'|'multi'} [selectable=false] Record selection behavior.
+ * @property {'checkbox'|'card'} [selectionTrigger='checkbox'] Select through a checkbox or the non-interactive card surface.
  * @property {unknown[]} [selection=[]] Initially selected record ids.
  * @property {string[]} [fieldOrder=[]] Preferred shared field order.
  * @property {string[]} [hiddenFields=[]] Initially hidden metadata fields.
- * @property {boolean} [fieldControls=true] Whether to expose shared field controls.
+ * @property {boolean|import('../view/record-view.js').ViewFieldControlsConfig} [fieldControls=true]
+ * Whether to expose shared field controls. `true` renders the chooser in the card toolbar and
+ * `false` omits it; an object customises its `label` and mounts it into `target`.
  * @property {string|Node|(()=>string|Node)|null} [emptyText=null] Empty-result content.
  * @property {RecordCardValueSource} [titleField=null] Title field id or explicit resolver.
  * @property {RecordCardValueSource} [subtitleField=null] Subtitle field id or explicit resolver.

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

@@ -119,6 +119,10 @@ export type RecordCardOptions = {
      * Selection presentation.
      */
     selectable?: false | 'single' | 'multi';
+    /**
+     * Selection affordance for owning views.
+     */
+    selectionTrigger?: 'checkbox' | 'card';
     /**
      * Current selection state.
      */
@@ -209,6 +213,7 @@ export type ResolvedRecordPreview = {
  * @property {RecordCardLink|((record:ViewRecord,index:number)=>RecordCardLink)} [link]
  * @property {RecordCardAction[]|((record:ViewRecord,index:number)=>RecordCardAction[])} [actions=[]]
  * @property {false|'single'|'multi'} [selectable=false] Selection presentation.
+ * @property {'checkbox'|'card'} [selectionTrigger='checkbox'] Selection affordance for owning views.
  * @property {boolean} [selected=false] Current selection state.
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Surface treatment.
  * @property {1|2|3|4|5|6} [headingLevel=3] Card title heading level.
@@ -229,7 +234,8 @@ export type ResolvedRecordPreview = {
  *
  * The returned `<li>` belongs in a semantic `<ul>`/`<ol>`. When selectable its global
  * `aria-description` announces selection without applying the unsupported `aria-selected` state
- * to a listitem; multi-selection also adds a native checkbox. It deliberately remains a listitem
+ * to a listitem; multi-selection adds a native checkbox unless the owner opts into card-surface
+ * selection. It deliberately remains a listitem
  * rather than becoming an ARIA option because cards may contain native links and buttons, which
  * the listbox pattern does not permit inside an option. Preview images are paired with a stable
  * fallback. The owning component listens for image `error` and marks the fallback.

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

@@ -0,0 +1,149 @@
+import { Component } from '../../core/component.js';
+export type CodeEditorOptions = {
+    /**
+     * Initial text.
+     */
+    value?: unknown;
+    /**
+     * Form field name.
+     */
+    name?: string;
+    /**
+     * Language identifier shown to the user and exposed as data.
+     */
+    language?: string;
+    /**
+     * Accessible editor label.
+     */
+    label?: string;
+    /**
+     * Placeholder text.
+     */
+    placeholder?: string;
+    /**
+     * Visible textarea rows.
+     */
+    rows?: number;
+    /**
+     * Text inserted by Tab and removed by Shift+Tab.
+     */
+    indent?: string;
+    /**
+     * Textarea wrapping behavior.
+     */
+    wrap?: 'off' | 'soft' | 'hard';
+    /**
+     * Whether browser spellcheck is enabled.
+     */
+    spellcheck?: boolean;
+    /**
+     * Whether content can be selected but not changed.
+     */
+    readOnly?: boolean;
+    /**
+     * Whether the editor is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the line/column status is visible.
+     */
+    status?: boolean;
+    /**
+     * Input listener.
+     */
+    oninput?: (event: CustomEvent<{
+        value: string;
+    }>) => void;
+    /**
+     * Change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        value: string;
+    }>) => void;
+};
+/**
+ * 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>}
+ */
+export declare class CodeEditor extends Component<CodeEditorOptions> {
+    _createdRoot: boolean;
+    _initialChildren: ChildNode[];
+    _initialAttributes: Map<string, string>;
+    _language: string;
+    _languageLabel: HTMLElement;
+    _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;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** @returns {string} */
+    getValue(): string;
+    /**
+     * Replaces the editor text.
+     * @param {unknown} value New value.
+     * @param {{silent?:boolean}} [options={}] Suppress the `change` event.
+     * @returns {this}
+     */
+    setValue(value: unknown, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** @param {unknown} language New language identifier. @returns {this} */
+    setLanguage(language: unknown): this;
+    /** @returns {this} */
+    focus(): this;
+    /** @returns {this} */
+    enable(): this;
+    /** @returns {this} */
+    disable(): this;
+    /** @param {boolean} value Read-only state. @returns {this} */
+    setReadOnly(value: boolean): this;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _handleKeydown(event: KeyboardEvent): void;
+    /** @returns {void} */
+    _updatePosition(): void;
+    /** @returns {void} */
+    destroy(): void;
+}
+/**
+ * Applies Tab or Shift+Tab to a textarea selection.
+ * @param {string} value Complete source value.
+ * @param {number} start Selection start.
+ * @param {number} end Selection end.
+ * @param {string} indent Indentation text.
+ * @param {boolean} outdent Whether to remove indentation.
+ * @returns {{value:string,start:number,end:number}}
+ */
+export declare function indentSelection(value: string, start: number, end: number, indent?: string, outdent?: boolean): {
+    value: string;
+    start: number;
+    end: number;
+};
+/** @param {string} value @param {number} start @param {number} end @returns {{line:number,column:number,lines:number}} */
+export declare function editorPosition(value: string, start: number, end?: number): {
+    line: number;
+    column: number;
+    lines: number;
+};
+/**
+ * Code editor input event.
+ * @event CodeEditor#input
+ * @type {CustomEvent<{value:string}>}
+ */
+/**
+ * Code editor committed change event.
+ * @event CodeEditor#change
+ * @type {CustomEvent<{value:string}>}
+ */

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

@@ -0,0 +1,5 @@
+/**
+ * Registers the CodeEditor-backed `code` field type.
+ * @returns {void}
+ */
+export declare function registerCodeEditorFieldAdapter(): void;

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

@@ -1,6 +1,6 @@
 import { Component } from '../../core/component.js';
-export type MenuItem = import('../menu-button/menu-button.js').MenuItem;
-export type ContextMenuEntry = MenuItem | '-';
+export type MenuItem = import('../../internal/menu-items.js').MenuItem;
+export type ContextMenuEntry = import('../../internal/menu-items.js').MenuEntry;
 export type ContextMenuOptions = {
     /**
      * Menu
@@ -34,6 +34,22 @@ 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 */
+/**
+ * @typedef {Object} ContextMenuOptions
+ * @property {ContextMenuEntry[]|((context: Element|null) => ContextMenuEntry[])} [items=[]] Menu
+ *   items and `'-'` separators, or a function returning them for the element the menu is opening
+ *   on — which is how a row menu disables the actions that row does not allow. Returning an empty
+ *   array cancels the opening.
+ * @property {string|null} [selector=null] Restricts the menu to descendants matching this
+ *   selector, and reports the matched element as the context of the selection. A table passes
+ *   `'tbody tr'` here to get a per-row menu from one listener.
+ * @property {(event: CustomEvent<{value: unknown, item: MenuItem, context: Element|null}>) => void} [onselect]
+ *   Selection listener.
+ * @property {(event: CustomEvent<{context: Element|null}>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
+ */
 /**
  * Right-click menu for a region, implementing the APG menu pattern.
  *

package/dist/types/components/date-picker/date-picker.d.ts

@@ -134,4 +134,12 @@ export declare class DatePicker extends Component<DatePickerOptions> {
     _inRange(date: Date): boolean;
     /** @param {Date} date @returns {HTMLButtonElement|null} */
     _buttonForDate(date: Date): HTMLButtonElement | null;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
 }

package/dist/types/components/date-picker/time-picker.d.ts

@@ -124,4 +124,11 @@ export declare class TimePicker extends Component<TimePickerOptions> {
     _buildMark(mark: ClockMark, selected: number): HTMLElement;
     /** @param {HTMLElement} element @param {ClockMark} mark @param {number} selected @returns {void} */
     _syncMark(element: HTMLElement, mark: ClockMark, selected: number): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
 }

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} */