@zeyos/zx 4.3.0 → 4.4.0

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.
@@ -190,7 +198,7 @@ export type CardRecordGroup = {
  * @property {string|((record:ViewRecord,index:number)=>unknown)|null} [groupBy=null]
  * Field id or local group resolver.
  * @property {unknown[]} [groupOrder=[]] Preferred group ids; missing ids render as empty groups.
- * @property {number|string} [minCardWidth='18rem'] Responsive minimum card width.
+ * @property {number|string} [minCardWidth='15rem'] Responsive minimum card width.
  * @property {number|null} [maxColumns=null] Maximum cards per row; null is unconstrained.
  * @property {'outlined'|'raised'|'filled'} [variant='outlined'] Card surface treatment.
  * @property {number} [loadingCount=6] Skeleton cards shown while loading.

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

@@ -1,6 +1,25 @@
 export type ViewRecord = Record<string, any>;
 export type ViewField = import('../view/record-view.js').ViewField;
 export type RecordCardValueSource = string | ((record: ViewRecord, index: number) => unknown) | null;
+export type RecordCardFieldSlot = 'eyebrow-start' | 'eyebrow-end' | 'title-prefix';
+export type RecordCardFieldGroups = {
+    /**
+     * Fields shown at the logical start of the eyebrow row.
+     */
+    eyebrowStart: ViewField[];
+    /**
+     * Fields shown at the logical end of the eyebrow row.
+     */
+    eyebrowEnd: ViewField[];
+    /**
+     * Fields shown immediately before, but outside, the heading.
+     */
+    titlePrefix: ViewField[];
+    /**
+     * Remaining labelled metadata fields.
+     */
+    metadata: ViewField[];
+};
 export type RecordCardPreviewDescriptor = {
     /**
      * Image URL.
@@ -100,6 +119,10 @@ export type RecordCardOptions = {
      * Selection presentation.
      */
     selectable?: false | 'single' | 'multi';
+    /**
+     * Selection affordance for owning views.
+     */
+    selectionTrigger?: 'checkbox' | 'card';
     /**
      * Current selection state.
      */
@@ -142,6 +165,14 @@ export type ResolvedRecordPreview = {
 /** @typedef {Record<string, any>} ViewRecord */
 /** @typedef {import('../view/record-view.js').ViewField} ViewField */
 /** @typedef {string|((record:ViewRecord,index:number)=>unknown)|null} RecordCardValueSource */
+/** @typedef {'eyebrow-start'|'eyebrow-end'|'title-prefix'} RecordCardFieldSlot */
+/**
+ * @typedef {Object} RecordCardFieldGroups
+ * @property {ViewField[]} eyebrowStart Fields shown at the logical start of the eyebrow row.
+ * @property {ViewField[]} eyebrowEnd Fields shown at the logical end of the eyebrow row.
+ * @property {ViewField[]} titlePrefix Fields shown immediately before, but outside, the heading.
+ * @property {ViewField[]} metadata Remaining labelled metadata fields.
+ */
 /**
  * @typedef {Object} RecordCardPreviewDescriptor
  * @property {string} src Image URL.
@@ -182,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.
@@ -200,11 +232,13 @@ export type ResolvedRecordPreview = {
  * becomes text, URLs are normalized before reaching native attributes, and actions expose stable
  * data attributes for a component-owned delegated listener.
  *
- * The returned `<li>` belongs in a semantic `<ul>`/`<ol>`. When selectable it carries
- * `aria-selected`; multi-selection adds a native checkbox. It deliberately retains list-item
- * semantics 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.
+ * 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 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.
  *
  * @param {ViewRecord} record Record to render.
  * @param {number} index Current display index.
@@ -212,6 +246,20 @@ export type ResolvedRecordPreview = {
  * @returns {HTMLLIElement} Semantic record card list item.
  */
 export declare function createRecordCard(record: ViewRecord, index: number, options?: RecordCardOptions): HTMLLIElement;
+/**
+ * Partitions ordered visible fields into the shared record-card slots. A recognized
+ * `field.view.card.slot` moves the field to that semantic region; absent or unknown values remain
+ * ordinary metadata. Title and subtitle fields retain the existing no-duplication rule.
+ *
+ * The input array and descriptors are never mutated. Each field appears in at most one result
+ * array, and the order within every result follows the supplied visible-field order.
+ *
+ * @param {ViewField[]} fields Ordered visible fields.
+ * @param {RecordCardValueSource} [titleSource=null] Active title field or resolver.
+ * @param {RecordCardValueSource} [subtitleSource=null] Active subtitle field or resolver.
+ * @returns {RecordCardFieldGroups} Partitioned fields.
+ */
+export declare function partitionRecordCardFields(fields: ViewField[], titleSource?: RecordCardValueSource, subtitleSource?: RecordCardValueSource): RecordCardFieldGroups;
 /**
  * Resolves a preview without touching the DOM. Unsafe, malformed, and non-image URL schemes are
  * rejected into the same descriptor shape so callers can still render the stable fallback.

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

@@ -0,0 +1,160 @@
+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;
+};
+/**
+ * @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.
+ * @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;
+    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/dialog/dialog.d.ts

@@ -17,6 +17,14 @@ export type DialogButton = {
      * Whether this button receives initial focus.
      */
     autofocus?: boolean;
+    /**
+     * Whether the footer button is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Visible shortcut hint; the host binds the action.
+     */
+    shortcut?: import('../button/button.js').ButtonShortcut;
 };
 export type DialogOptions = {
     /**
@@ -155,6 +163,8 @@ export type PromptOptions = {
  * @property {DialogButtonKind} [kind='default'] Visual button kind.
  * @property {'close'|'cancel'|((dialog: Dialog) => void)} [action='close'] Button action.
  * @property {boolean} [autofocus=false] Whether this button receives initial focus.
+ * @property {boolean} [disabled=false] Whether the footer button is disabled.
+ * @property {import('../button/button.js').ButtonShortcut} [shortcut] Visible shortcut hint; the host binds the action.
  */
 /**
  * @typedef {Object} DialogOptions
@@ -295,4 +305,23 @@ export declare class Dialog extends Modal {
      * @returns {void}
      */
     _applySize(size: 'sm' | 'md' | 'lg' | number): void;
+    /**
+     * Resolves a component message, 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;
 }
+/**
+ * Copies footer-button descriptors without mutating the caller's array or objects, and settles
+ * the two booleans the footer renders from.
+ *
+ * `autofocus` and `disabled` are resolved together because they contradict each other: a control
+ * that refuses activation must not be the one initial focus lands on, and a host that writes both
+ * has said what it wants twice. Deciding it here rather than at render time keeps `Sheet` — which
+ * takes the same descriptors through the same footer — on one answer.
+ * @param {DialogButton[]|null|undefined} list Button descriptors.
+ * @returns {DialogButton[]} Normalized copies.
+ */
+export declare function normalizeDialogButtons(list: DialogButton[] | null | undefined): DialogButton[];