@zeyos/zx 5.0.0 → 5.3.0

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

@@ -109,10 +109,64 @@ 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;
+    /**
+     * Keyboard model. `'tabs'` makes every card, title
+     * link, checkbox, and action its own Tab stop. `'roving'` — recommended for lists — follows the
+     * APG Grid pattern with row focus: the collection is one Tab stop, the arrow keys, Home/End, and
+     * PageUp/PageDown move between cards, Enter activates, Space selects, and the controls inside a
+     * card stay pointer targets with `tabindex="-1"`.
+     */
+    keyboard?: 'tabs' | 'roving';
+    /**
+     * Whether group headings carry a toggle that hides
+     * and shows the group's cards.
+     */
+    collapsibleGroups?: boolean;
+    /**
+     * Group ids that start collapsed.
+     */
+    collapsedGroups?: unknown[];
+    /**
+     * Content of a group heading in place of its label. With `collapsibleGroups` it is placed inside
+     * the toggle button, so it must not contain interactive elements.
+     */
+    renderGroupHeading?: ((context: CardGroupHeadingContext) => Node | string | null | undefined) | null;
     onrecordaction?: (event: CustomEvent<Record<string, unknown>>) => void;
+    ongroupcollapse?: (event: CustomEvent<{
+        id: string;
+        collapsed: boolean;
+        collapsedGroups: string[];
+    }>) => void;
+};
+export type CardGroupHeadingContext = {
+    /**
+     * Normalized group id (`''` for records without a value).
+     */
+    id: string;
+    /**
+     * Default label.
+     */
+    label: string;
+    /**
+     * Records in the group.
+     */
+    count: number;
+    /**
+     * The group's records in display order.
+     */
+    records: ViewRecord[];
+    /**
+     * Whether the group is collapsed.
+     */
+    collapsed: boolean;
+    /**
+     * Collapses or expands the group.
+     */
+    toggle: () => void;
 };
 export type CardViewState = {
     /**
@@ -147,6 +201,10 @@ export type CardViewState = {
      * Surface treatment.
      */
     variant: 'outlined' | 'raised' | 'filled';
+    /**
+     * Collapsed group ids.
+     */
+    collapsedGroups: string[];
 };
 export type CardRecordGroup = {
     /**
@@ -203,8 +261,31 @@ 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 {'tabs'|'roving'} [keyboard='tabs'] Keyboard model. `'tabs'` makes every card, title
+ *   link, checkbox, and action its own Tab stop. `'roving'` — recommended for lists — follows the
+ *   APG Grid pattern with row focus: the collection is one Tab stop, the arrow keys, Home/End, and
+ *   PageUp/PageDown move between cards, Enter activates, Space selects, and the controls inside a
+ *   card stay pointer targets with `tabindex="-1"`.
+ * @property {boolean} [collapsibleGroups=false] Whether group headings carry a toggle that hides
+ *   and shows the group's cards.
+ * @property {unknown[]} [collapsedGroups=[]] Group ids that start collapsed.
+ * @property {((context:CardGroupHeadingContext)=>Node|string|null|undefined)|null} [renderGroupHeading=null]
+ *   Content of a group heading in place of its label. With `collapsibleGroups` it is placed inside
+ *   the toggle button, so it must not contain interactive elements.
  * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onrecordaction]
+ * @property {(event:CustomEvent<{id:string,collapsed:boolean,collapsedGroups:string[]}>)=>void} [ongroupcollapse]
+ */
+/**
+ * What `renderGroupHeading` is given for one group.
+ * @typedef {Object} CardGroupHeadingContext
+ * @property {string} id Normalized group id (`''` for records without a value).
+ * @property {string} label Default label.
+ * @property {number} count Records in the group.
+ * @property {ViewRecord[]} records The group's records in display order.
+ * @property {boolean} collapsed Whether the group is collapsed.
+ * @property {() => void} toggle Collapses or expands the group.
  */
 /**
  * @typedef {Object} CardViewState
@@ -216,6 +297,7 @@ export type CardRecordGroup = {
  * @property {string} minCardWidth Responsive minimum card width.
  * @property {number|null} maxColumns Maximum cards per row.
  * @property {'outlined'|'raised'|'filled'} variant Surface treatment.
+ * @property {string[]} collapsedGroups Collapsed group ids.
  */
 /**
  * @typedef {Object} CardRecordGroup
@@ -226,7 +308,20 @@ export type CardRecordGroup = {
 /**
  * Responsive, schema-friendly record cards with shared fields, sorting, selection, state, groups,
  * safe preview media, native title links, and delegated actions.
+ *
+ * With `keyboard: 'roving'` the collection follows the WAI-ARIA APG Grid pattern with row focus,
+ * the model `Table` uses: the content is a `grid`, each card a focusable `row` (`aria-selected`
+ * when selectable, `aria-multiselectable` on the grid for `multi`), and the collection is a single
+ * Tab stop. ArrowUp/ArrowDown move to the card above or below — columns are measured from where the
+ * cards actually are, so a multi-column layout moves by visual row — ArrowLeft/ArrowRight within a
+ * row, Home/End to the first or last card, PageUp/PageDown by a visible page. Enter activates
+ * (`recordclick`), Space toggles selection in `selectable` modes (and activates otherwise),
+ * Shift+movement extends a `multi` selection, and Ctrl/Cmd+A selects every rendered card. A
+ * collapsible group heading is part of the same order: Enter or Space toggles it, ArrowLeft
+ * collapses, ArrowRight expands. The current card is kept by record id across `setData`, sorting,
+ * grouping, and collapsing, and focus is restored without scrolling.
  * @fires CardView#recordaction
+ * @fires CardView#groupcollapse
  * @extends {RecordView}
  */
 export declare class CardView extends RecordView {
@@ -240,6 +335,28 @@ export declare class CardView extends RecordView {
     _cardVariant: "filled" | "outlined" | "raised";
     _cardLoadingCount: number;
     _cardHeadingLevel: 1 | 2 | 3 | 4 | 5 | 6;
+    _cardRoving: boolean;
+    _cardIdPrefix: string;
+    _cardCollapsed: Set<string>;
+    /** @type {{kind:'card'|'group', id:unknown}|null} */
+    _cardCurrent: {
+        kind: 'card' | 'group';
+        id: unknown;
+    } | null;
+    _cardCurrentIndex: number;
+    /** @type {HTMLElement|null} */
+    _cardTabStop: HTMLElement | null;
+    /** @type {number|null} */
+    _cardStickyX: number | null;
+    _cardMoving: boolean;
+    /** @type {Map<string, HTMLElement>} */
+    _cardHeadersById: Map<string, HTMLElement>;
+    /** @type {Map<unknown, string>} */
+    _cardGroupOfId: Map<unknown, string>;
+    /** @type {Map<Element, string>} */
+    _cardSectionIds: Map<Element, string>;
+    /** @type {WeakMap<Element, unknown>} */
+    _cardIdOfNode: WeakMap<Element, unknown>;
     static cssName: string;
     /** @type {Readonly<CardViewOptions & RecordViewOptions>} */
     static defaults: Readonly<CardViewOptions & RecordViewOptions>;
@@ -262,6 +379,19 @@ export declare class CardView extends RecordView {
     setViewState(state: Partial<CardViewState> | null, options?: {
         silent?: boolean;
     }): this;
+    /**
+     * Collapses or expands one group. A collapsed group keeps its heading and hides its cards.
+     * @param {unknown} id Group id, as `groupBy` produces it.
+     * @param {boolean} [collapsed=true] Next state.
+     * @param {{silent?:boolean}} [options={}] Set `silent` to suppress `groupcollapse` and `statechange`.
+     * @returns {this}
+     * @fires CardView#groupcollapse
+     */
+    setGroupCollapsed(id: unknown, collapsed?: boolean, options?: {
+        silent?: boolean;
+    }): this;
+    /** Returns the collapsed group ids. @returns {string[]} */
+    getCollapsedGroups(): string[];
     /** Restores an enhanced target exactly, or removes an owned root. @returns {void} */
     destroy(): void;
     /** @protected @param {string} reason Refresh reason. @returns {void} */
@@ -276,6 +406,67 @@ export declare class CardView extends RecordView {
     private _renderCards;
     /** @private @param {CardRecordGroup} group @param {ViewField[]} fields @param {ViewField[]} visibleFields @param {number} groupIndex @returns {HTMLElement} */
     private _createCardGroup;
+    /**
+     * Builds a group heading: the label (or `renderGroupHeading` content), inside an APG
+     * disclosure button when the group can collapse.
+     * @private
+     * @param {CardRecordGroup} group Group.
+     * @param {string} headingId Heading id.
+     * @param {boolean} collapsible Whether the group can collapse.
+     * @param {boolean} collapsed Whether it is collapsed.
+     * @returns {HTMLElement}
+     */
+    private _createGroupHeader;
+    /**
+     * Turns a rendered card into a grid row for the roving model: row focus, `aria-selected` when
+     * selectable, and the controls inside it out of the Tab order.
+     * @private
+     * @param {HTMLElement} card Card element.
+     * @param {unknown} id Record id.
+     * @returns {void}
+     */
+    private _makeCardRow;
+    /**
+     * Moves the single Tab stop to the current item after a render — the same record or group by
+     * id; else the heading of the collapsed group that now hides the card; else the item now at its
+     * old position — and focuses it again, without scrolling, when the collection had focus.
+     * @private
+     * @param {boolean} hadFocus Whether focus was inside the collection before the render.
+     * @returns {void}
+     */
+    private _syncCardRoving;
+    /**
+     * @private
+     * @param {HTMLElement} item New Tab stop.
+     * @param {HTMLElement[]} [items] Every item, when already collected.
+     * @returns {void}
+     */
+    private _setCardTabStop;
+    /**
+     * While loading or empty there is no card to hold focus: the content takes it rather than
+     * letting it fall to the document, and gives the Tab order its old shape back afterwards.
+     * @private
+     * @param {boolean} hold Whether focus was inside and there is nothing to put it on.
+     * @returns {void}
+     */
+    private _syncCardEmptyFocus;
+    /** @private @returns {HTMLElement[]} Roving items in display order. */
+    private _cardItems;
+    /** @private @param {HTMLElement} item @returns {{kind:'card'|'group', id:unknown}|null} */
+    private _cardItemKey;
+    /** @private @param {{kind:'card'|'group', id:unknown}|null} key @returns {HTMLElement|null} */
+    private _cardItemFor;
+    /** @private @param {FocusEvent} event @returns {void} */
+    private _cardFocusIn;
+    /**
+     * The roving keyboard model; see the class description.
+     * @private
+     * @param {KeyboardEvent} event Key event.
+     * @returns {void}
+     */
+    private _cardRovingKeydown;
+    /** @private @param {HTMLElement[]} items @returns {unknown[]} Record ids of the card items. */
+    private _cardIdsOf;
     /** @private @returns {HTMLElement} */
     private _createCardSkeletons;
     /** @private @returns {HTMLElement} */
@@ -297,6 +488,53 @@ export declare class CardView extends RecordView {
     /** @private @returns {Readonly<CardViewOptions & RecordViewOptions>} */
     private _cardOptions;
 }
+/**
+ * Sorts item rectangles into visual rows: items whose tops are within `tolerance` pixels share a
+ * row, rows run top to bottom, and items within a row left to right.
+ * @param {Array<{top:number,left:number}>} rects Item rectangles in display order.
+ * @param {number} [tolerance=4] Pixels two tops may differ by and still share a row.
+ * @returns {number[][]} Item indexes per row.
+ */
+export declare function cardGridRows(rects: Array<{
+    top: number;
+    left: number;
+}>, tolerance?: number): number[][];
+/**
+ * How many columns the cards are laid out in: the length of the longest visual row.
+ * @param {Array<{top:number,left:number}>} rects Item rectangles.
+ * @returns {number} At least 1 for a non-empty list, 0 for an empty one.
+ */
+export declare function cardColumnCount(rects: Array<{
+    top: number;
+    left: number;
+}>): number;
+/**
+ * Where a navigation key moves in a laid-out card grid. ArrowUp/ArrowDown go to the previous or
+ * next visual row and PageUp/PageDown `page` rows, landing on the item nearest to `x` (the column
+ * the reader is travelling in); ArrowLeft/ArrowRight move within the row and stop at its ends;
+ * Home/End go to the first or last item.
+ * @param {Array<{top:number,left:number}>} rects Item rectangles in display order.
+ * @param {number} index Current item.
+ * @param {string} key `KeyboardEvent.key`.
+ * @param {{page?:number, x?:number}} [options={}] Rows per page (default 10) and preferred x.
+ * @returns {number|null} Next item index, or null when the key is not a move.
+ */
+export declare function cardGridTarget(rects: Array<{
+    top: number;
+    left: number;
+}>, index: number, key: string, options?: {
+    page?: number;
+    x?: number;
+}): number | null;
+/**
+ * How many rows a PageUp or PageDown moves: the rows that fit in the visible height, less one so
+ * the row focus leaves stays in view. Falls back when either height is unknown.
+ * @param {number} viewport Visible height of the scroll region.
+ * @param {number} rowHeight Height of one row of cards.
+ * @param {number} [fallback=10] Rows to move when the heights are unusable.
+ * @returns {number} At least 1.
+ */
+export declare function cardPageSize(viewport: number, rowHeight: number, fallback?: number): number;
 /**
  * Groups a cloned record list without mutating records or caller arrays. Explicit order entries
  * are always materialized, including empty groups; remaining values keep first-seen order.
@@ -304,8 +542,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/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/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.
@@ -55,6 +53,16 @@ export type DropdownOptions = {
  */
 /**
  * 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/field/field.d.ts

@@ -38,6 +38,12 @@ export type FieldOptions = {
      * Whether the control is disabled.
      */
     disabled?: boolean;
+    /**
+     * Whether the value is read-only: shown and focusable, not
+     * editable. Types whose control has no read-only state (`checkbox`, `select`, `optionlist`,
+     * `zxselect`, `date`, `time`, …) ignore it.
+     */
+    readonly?: boolean;
     /**
      * Select or option-list values.
      */
@@ -90,6 +96,11 @@ export type FieldAdapter = {
      * Set disabled state.
      */
     setDisabled: (disabled: boolean) => void;
+    /**
+     * Set read-only state; left out when the
+     * control has none.
+     */
+    setReadonly?: (readonly: boolean) => void;
     /**
      * Release adapter-owned resources.
      */
@@ -119,6 +130,9 @@ export type NumericCoercion = {
  * @property {string} [placeholder=''] Control placeholder.
  * @property {boolean} [required=false] Whether a value is required.
  * @property {boolean} [disabled=false] Whether the control is disabled.
+ * @property {boolean} [readonly=false] Whether the value is read-only: shown and focusable, not
+ *   editable. Types whose control has no read-only state (`checkbox`, `select`, `optionlist`,
+ *   `zxselect`, `date`, `time`, …) ignore it.
  * @property {string[]|Record<string, string>|null} [options=null] Select or option-list values.
  * @property {'stack'|'inline'} [layout='stack'] Label/control layout.
  * @property {Record<string, unknown>} [props={}] Adapter-specific control properties.
@@ -133,6 +147,8 @@ export type NumericCoercion = {
  * @property {(value: unknown, options?: {silent?: boolean}) => void} set Set the current value.
  * @property {() => void} focus Focus the control.
  * @property {(disabled: boolean) => void} setDisabled Set disabled state.
+ * @property {(readonly: boolean) => void} [setReadonly] Set read-only state; left out when the
+ *   control has none.
  * @property {() => void} [destroy] Release adapter-owned resources.
  * @property {Element} [labelTarget] The element the field's label, description, and validity
  *   belong to when it is not `el` — the text input inside a composite control. Left out, a
@@ -143,6 +159,7 @@ export type NumericCoercion = {
 /**
  * One labelled form control backed by a registered adapter.
  * @fires Field#change
+ * @fires Field#input
  * @fires Field#invalid
  * @extends {Component<FieldOptions>}
  */
@@ -213,6 +230,13 @@ export declare class Field extends Component<FieldOptions> {
      * @returns {this}
      */
     setDisabled(disabled: boolean): this;
+    /**
+     * Makes the value read-only or editable again, where the control has a read-only state (see
+     * the `readonly` option); reflected as `data-readonly` on the root either way.
+     * @param {boolean} readonly Read-only state.
+     * @returns {this}
+     */
+    setReadonly(readonly: boolean): this;
     /**
      * Displays a validation or status message.
      * @param {string} message Message text.
@@ -260,6 +284,12 @@ export declare function coerceFloat(input: unknown): NumericCoercion;
  * @event Field#change
  * @type {CustomEvent<{value: unknown}>}
  */
+/**
+ * Live edit before it is committed, from the types whose widget tells the two apart (`code`,
+ * `slider`): every keystroke or drag step, where `change` follows only on commit.
+ * @event Field#input
+ * @type {CustomEvent<{value: unknown}>}
+ */
 /**
  * Field validation failure event.
  * @event Field#invalid

package/dist/types/components/fieldset/external-adapter.d.ts

@@ -0,0 +1,83 @@
+export type Field = import('../field/field.js').Field;
+export type FieldAdapter = import('../field/field.js').FieldAdapter;
+export type ExternalSource = Element | {
+    el?: Element;
+    toElement?: () => Element;
+};
+/** @typedef {import('../field/field.js').Field} Field */
+/** @typedef {import('../field/field.js').FieldAdapter} FieldAdapter */
+/**
+ * An element or component a Fieldset adopts with `addField(id, source)`: anything that renders
+ * into an element. Components are read through the methods they have, elements through their
+ * native properties.
+ * @typedef {Element|{el?: Element, toElement?: () => Element}} ExternalSource
+ */
+/**
+ * The value accessor pairs the library's components use, in the order they are tried. A reader
+ * counts only when it takes no required argument (`Fieldset.getValue(id)` is not a reader), a
+ * writer of another pair only when the value is its sole required argument.
+ * - `getValue/setValue`: Field, CodeEditor, Filter, SortControl, Toggle (`getValue()` is the
+ *   configured on-value or `false`, the same as the `toggle` field type reads).
+ * - `get/set`: NumberField, Select, Slider, Rating, CheckButton, Datebox, Timebox, Search,
+ *   CopyInput, DatePicker and the other pickers.
+ * - `getValues/setValues`: Checklist, TagPicker, ValueList, MultiValueEditor, Fieldset, Form.
+ * - `isChecked/setChecked`: boolean controls that name their state that way.
+ * @type {ReadonlyArray<readonly [string, string]>}
+ */
+export declare const VALUE_METHODS: ReadonlyArray<readonly [string, string]>;
+/**
+ * The element a source renders into.
+ * @param {ExternalSource} source Element or component.
+ * @returns {Element}
+ */
+export declare function externalElement(source: ExternalSource): Element;
+/**
+ * Reads the current value of an element or component through the first value dialect it
+ * supports (see {@link VALUE_METHODS}), then a `value`, `values`, or `checked` property, then the
+ * element itself: `checked` for a checkbox or radio, `value` for any other control. Null when
+ * the source has no value at all.
+ * @param {ExternalSource} source Element or component.
+ * @returns {unknown}
+ */
+export declare function readExternalValue(source: ExternalSource): unknown;
+/**
+ * Reports whether an element or component is disabled: its `isDisabled()`, a `disabled`
+ * property, the element's own `disabled`, an `aria-disabled="true"` or `data-disabled` root, or
+ * a wrapper whose every form control is disabled.
+ * @param {ExternalSource} source Element or component.
+ * @returns {boolean}
+ */
+export declare function readExternalDisabled(source: ExternalSource): boolean;
+/**
+ * Reports whether an element or component is read-only: a `readonly`/`readOnly` property, the
+ * element's own `readOnly`, or an `aria-readonly="true"` or `data-readonly` root.
+ * @param {ExternalSource} source Element or component.
+ * @returns {boolean}
+ */
+export declare function readExternalReadonly(source: ExternalSource): boolean;
+/**
+ * Builds the Field adapter for an element or component that is not a registered field type.
+ *
+ * Values go through the source's own accessors ({@link readExternalValue}); disabling through
+ * `setDisabled(bool)`, then `enable()`/`disable()`, then a `disabled` property, and only then the
+ * DOM — the element's `disabled`, or for a plain wrapper `aria-disabled` plus `disabled` on every
+ * form control inside it. Read-only goes through `setReadonly(bool)`/`setReadOnly(bool)`, a
+ * `readonly`/`readOnly` property, or the element's own `readOnly`.
+ *
+ * Writes pass the caller's options to the component: `Field.setValue(v)` or
+ * `Fieldset.setValues(values)` without `silent` lets the component emit its own `change` to its
+ * own listeners, while the field emits one `change` for the write; with `silent` neither does.
+ *
+ * Given the field, a component's own `change` event becomes the field's `change`, and the native
+ * `change` its inner controls bubble is dropped unless it carries a value the component did not
+ * already report — so one edit is one field `change`, whether the component reports it, its
+ * input does, or (Search, CopyInput) only its input does.
+ *
+ * `destroy()` puts the element back where it was found and undoes what the adapter changed:
+ * attributes, the native value, disabled and read-only state.
+ * @param {ExternalSource} source Element or component to adopt.
+ * @param {Field|null} [field=null] The field the adapter serves; needed to forward events. Its
+ *   `listen()` owns every listener the adapter adds, so destroying the field removes them.
+ * @returns {FieldAdapter}
+ */
+export declare function externalAdapter(source: ExternalSource, field?: Field | null): FieldAdapter;

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

@@ -53,6 +53,13 @@ export declare class Fieldset extends Component<FieldsetOptions> {
      * Adds a field from options, an existing field, an element, or a component. The key becomes the
      * field's `name` and its `data-field-id`; the control's DOM id is `<idPrefix>-<key>`, unless the
      * field options give an `id` of their own that differs from the key.
+     *
+     * An element or a component that is not a registered field type is wrapped in a `custom` field
+     * that reads and writes it through its own API — `getValue`/`setValue`, `get`/`set`,
+     * `getValues`/`setValues`, `isChecked`/`setChecked`, or a `value` property — disables it
+     * through `setDisabled(bool)` or `enable()`/`disable()`, and makes it read-only through
+     * `setReadonly(bool)`, falling back to the element's native properties only when the component
+     * has none of these. The component's own `change` becomes the field's `change`, once per edit.
      * @param {string} id Logical field identifier.
      * @param {FieldOptions|Field|Element|Component} field Field source.
      * @returns {Field}