@zeyos/zx 4.3.4 → 4.4.0

package/dist/types/components/file-list/file-list.d.ts

@@ -0,0 +1,171 @@
+import { Component } from '../../core/component.js';
+import { FileItem } from '../file-item/file-item.js';
+export type FileItemOptions = import('../file-item/file-item.js').FileItemOptions;
+export type FileItemState = import('../file-item/file-item.js').FileItemState;
+export type FileListOptions = {
+    /**
+     * Initial files in host-supplied order.
+     */
+    items?: FileItemOptions[];
+    /**
+     * Accessible collection name.
+     */
+    label?: string;
+    /**
+     * Whether initial or incremental files are loading.
+     */
+    loading?: boolean;
+    /**
+     * Placeholder rows shown for an empty loading list.
+     */
+    loadingCount?: number;
+    /**
+     * Loading status text.
+     */
+    loadingText?: string;
+    /**
+     * Empty-state content.
+     */
+    emptyText?: string | number | Node | Component | null;
+    /**
+     * Preventable native-file-link listener.
+     */
+    onactivate?: (event: CustomEvent<{
+        id: unknown;
+        index: number;
+        file: Readonly<FileItemState>;
+        href: string;
+        event: MouseEvent;
+    }>) => void;
+    /**
+     * Preventable file-action listener.
+     */
+    onaction?: (event: CustomEvent<{
+        id: string;
+        fileId: unknown;
+        index: number;
+        action: object;
+        file: Readonly<FileItemState>;
+        event: MouseEvent;
+    }>) => void;
+    /**
+     * Collection mutation listener.
+     */
+    ondatachange?: (event: CustomEvent<{
+        items: Readonly<FileItemState>[];
+    }>) => void;
+};
+/** @typedef {import('../file-item/file-item.js').FileItemOptions} FileItemOptions */
+/** @typedef {import('../file-item/file-item.js').FileItemState} FileItemState */
+/**
+ * @typedef {Object} FileListOptions
+ * @property {FileItemOptions[]} [items=[]] Initial files in host-supplied order.
+ * @property {string} [label='Files'] Accessible collection name.
+ * @property {boolean} [loading=false] Whether initial or incremental files are loading.
+ * @property {number} [loadingCount=3] Placeholder rows shown for an empty loading list.
+ * @property {string} [loadingText='Loading files'] Loading status text.
+ * @property {string|number|Node|Component|null} [emptyText='No files'] Empty-state content.
+ * @property {(event: CustomEvent<{id: unknown, index: number, file: Readonly<FileItemState>, href: string, event: MouseEvent}>) => void} [onactivate]
+ *   Preventable native-file-link listener.
+ * @property {(event: CustomEvent<{id: string, fileId: unknown, index: number, action: object, file: Readonly<FileItemState>, event: MouseEvent}>) => void} [onaction]
+ *   Preventable file-action listener.
+ * @property {(event: CustomEvent<{items: Readonly<FileItemState>[]}>) => void} [ondatachange]
+ *   Collection mutation listener.
+ */
+/**
+ * Accessible collection for durable and transient files. Ordering and mutation are local
+ * presentation concerns only; transport, authorization, and persistence remain host-owned.
+ * @fires FileList#activate
+ * @fires FileList#action
+ * @fires FileList#datachange
+ * @extends {Component<FileListOptions>}
+ */
+export declare class FileList extends Component<FileListOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    _items: import("../file-item/file-item.js").FileItemState[];
+    _loading: any;
+    _itemComponents: any[];
+    static cssName: string;
+    /** @type {Readonly<FileListOptions>} */
+    static defaults: Readonly<FileListOptions>;
+    /**
+     * Creates or enhances a file collection.
+     * @param {Element|string|null} [target=null] Existing host, selector, or null.
+     * @param {FileListOptions} [options={}] Collection presentation.
+     */
+    constructor(target?: Element | string | null, options?: FileListOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Replaces every file.
+     * @param {FileItemOptions[]} items Ordered file descriptors.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setItems(items: FileItemOptions[], options?: {
+        silent?: boolean;
+    }): this;
+    /** Returns defensive snapshots in display order. @returns {Readonly<FileItemState>[]} */
+    getItems(): Readonly<FileItemState>[];
+    /** Returns a defensive snapshot by stable ID. @param {unknown} id File id. @returns {Readonly<FileItemState>|null} */
+    getItem(id: unknown): Readonly<FileItemState> | null;
+    /**
+     * Adds one file at a bounded index.
+     * @param {FileItemOptions} item File descriptor.
+     * @param {number} [index] Insertion position; omitted means append.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    addItem(item: FileItemOptions, index?: number, options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Patches the first file whose ID is `Object.is`-equal to `id`.
+     * @param {unknown} id File id.
+     * @param {Partial<FileItemOptions>} values Replacement fields.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    updateItem(id: unknown, values: Partial<FileItemOptions>, options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Removes the first file whose ID is `Object.is`-equal to `id`.
+     * @param {unknown} id File id.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    removeItem(id: unknown, options?: {
+        silent?: boolean;
+    }): this;
+    /** Sets initial/incremental loading presentation. @param {boolean} loading Loading state. @returns {this} */
+    setLoading(loading: boolean): this;
+    /** Restores an enhanced target exactly, or removes an owned collection. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _renderList(): void;
+    /** @param {boolean} placeholders @returns {HTMLElement} */
+    _createLoading(placeholders: boolean): HTMLElement;
+    /** @returns {void} */
+    _destroyItems(): void;
+    /** @param {CustomEvent} event @returns {void} */
+    _forwardActivate(event: CustomEvent): void;
+    /** @param {CustomEvent} event @returns {void} */
+    _forwardAction(event: CustomEvent): void;
+    /** @param {CustomEvent} event @returns {FileItem|null} */
+    _componentForEvent(event: CustomEvent): FileItem | null;
+    /** @returns {void} */
+    _emitDataChange(): void;
+}
+/**
+ * Validates, normalizes, and clones file descriptors without mutating the input.
+ * Explicit duplicate IDs are rejected; id-less rows remain valid.
+ * @param {unknown} value Candidate descriptors.
+ * @returns {FileItemState[]}
+ */
+export declare function normalizeFileListItems(value: unknown): FileItemState[];
+/** File descriptors changed through a list mutation method. @event FileList#datachange @type {CustomEvent<{items:Readonly<FileItemState>[]}>} */
+/** A file link activated through the list. @event FileList#activate @type {CustomEvent<{id:unknown,index:number,file:Readonly<FileItemState>,href:string,event:MouseEvent}>} */
+/** A file action activated through the list. @event FileList#action @type {CustomEvent<{id:string,fileId:unknown,index:number,action:object,file:Readonly<FileItemState>,event:MouseEvent}>} */

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

@@ -95,6 +95,26 @@ export type FilterOptions = {
      * Maximum condition count.
      */
     maxConditions?: number;
+    /**
+     * Searchable field, operator and single-choice controls.
+     */
+    searchable?: boolean;
+    /**
+     * Condition layout; compact rows adapt to container width.
+     */
+    layout?: 'standard' | 'compact';
+    /**
+     * Restrict root logic without rewriting incompatible saved expressions.
+     */
+    rootLogic?: 'and' | 'or' | null;
+    /**
+     * Show the internal Apply button.
+     */
+    showApply?: boolean;
+    /**
+     * Show Add controls inside the root group as well as the footer.
+     */
+    showRootActions?: boolean;
     /**
      * Emit apply after every valid mutation.
      */
@@ -108,11 +128,11 @@ export type FilterOptions = {
      */
     disabled?: boolean;
     /**
-     * Apply button label.
+     * Apply button label. Omitted resolves `filter.apply`, English `Apply filters`.
      */
     applyLabel?: string;
     /**
-     * Clear button label.
+     * Clear button label. Omitted resolves `filter.clear`, English `Clear`.
      */
     clearLabel?: string;
     /**
@@ -140,40 +160,32 @@ export type FilterOptions = {
      */
     onerror?: (event: CustomEvent<Record<string, unknown>>) => void;
 };
-/** @typedef {import('./filter-model.js').FilterAst} FilterAst */
-/**
- * @typedef {Object} FilterField
- * @property {string} id Stable allowlisted field ID.
- * @property {string} label Display label.
- * @property {'text'|'number'|'money'|'date'|'datetime'|'boolean'|'enum'|'status'|'priority'|'country'|'currency'|'unit'|'entity'|'tags'|'custom'} type Editor/operator type.
- * @property {string[]} [operators] Explicit allowlisted operator IDs.
- * @property {string} [defaultOperator] Initial operator ID.
- * @property {Array<{value:string|number|boolean,label:string,icon?:Node|string,color?:string}>} [choices] Static choices.
- * @property {(context:{query:string,signal:AbortSignal,conditionId:string,field:FilterField})=>Promise<Array<{value:string|number|boolean,label:string}>>|Array<{value:string|number|boolean,label:string}>} [loadChoices] Async choices.
- * @property {(target:Element, context:{value:unknown,setValue:(value:unknown)=>void,field:FilterField,conditionId:string})=>({destroy?:()=>void}|void)} [editor] Custom editor.
- * @property {number} [minQuery=0] Async minimum query length.
- * @property {number} [debounce=200] Async debounce in milliseconds.
- */
-/**
- * @typedef {Object} FilterOptions
- * @property {FilterField[]} fields Field definitions.
- * @property {FilterAst} [value] Initial expression.
- * @property {Array<{id:string,label:string,arity:'none'|'single'|'pair'|'many',types:string[]}>} [operators] Additional/overridden operators.
- * @property {boolean} [allowGroups=true] Whether nested groups may be authored.
- * @property {number} [maxDepth=3] Maximum nested group depth.
- * @property {number} [maxConditions=50] Maximum condition count.
- * @property {boolean} [autoApply=false] Emit apply after every valid mutation.
- * @property {boolean} [readonly=false] Prevent mutations while keeping values readable.
- * @property {boolean} [disabled=false] Disable all controls.
- * @property {string} [applyLabel='Apply filters'] Apply button label.
- * @property {string} [clearLabel='Clear'] Clear button label.
- * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onchange] Draft-change listener.
- * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onapply] Valid-apply listener.
- * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [oninvalid] Invalid-apply listener.
- * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onquery] Async query listener.
- * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onloaded] Async loaded listener.
- * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onerror] Async failure listener.
- */
+export type FilterValueMessages = {
+    /**
+     * Empty-choice option label.
+     */
+    choose: string;
+    /**
+     * Boolean true label.
+     */
+    yes: string;
+    /**
+     * Boolean false label.
+     */
+    no: string;
+    /**
+     * Placeholder for a many-valued text input.
+     */
+    commaSeparated: string;
+    /**
+     * Accessible name for a single value control.
+     */
+    value: (label: string) => string;
+    /**
+     * Accessible name for one end of a pair.
+     */
+    valueAt: (label: string, position: number) => string;
+};
 /**
  * Backend-neutral dynamic filter expression editor.
  * @fires Filter#change
@@ -227,6 +239,8 @@ export declare class Filter extends Component<FilterOptions> {
     _disabled: boolean;
     _async: Map<any, any>;
     _customEditors: any[];
+    _selectEditors: any[];
+    _disposed: boolean;
     _value: import("./filter-model.js").FilterAst;
     _renderVersion: any;
     static cssName: string;
@@ -279,6 +293,20 @@ export declare class Filter extends Component<FilterOptions> {
     _renderCondition(node: any): HTMLElement;
     /** @param {any} node @param {FilterField|null} field @param {any} operator @returns {HTMLElement} */
     _renderValue(node: any, field: FilterField | null, operator: any): HTMLElement;
+    /**
+     * Owns a themed picker and defers mutation until Select finishes its selection event.
+     * @param {Array<{value:unknown,label:string}>} items Choices.
+     * @param {unknown} value Selected value.
+     * @param {string} label Accessible name.
+     * @param {string} nodeId Condition ID.
+     * @param {string} part Focus target name.
+     * @param {(value:unknown)=>void} changed Selection handler.
+     * @returns {HTMLElement} Picker root.
+     */
+    _searchSelect(items: Array<{
+        value: unknown;
+        label: string;
+    }>, value: unknown, label: string, nodeId: string, part: string, changed: (value: unknown) => void): HTMLElement;
     /** @param {Event} event @returns {void} */
     _handleChange(event: Event): void;
     /** @param {Event} event @returns {void} */
@@ -322,6 +350,26 @@ export declare class Filter extends Component<FilterOptions> {
     _defaultOperator(field: FilterField | null): string | null;
     /** @param {string} text @returns {void} */
     _announce(text: string): void;
+    /** Names a field or operator a saved expression refers to that this instance does not offer.
+     * @param {string} id Unknown field or operator ID. @returns {string} */
+    _unavailable(id: string): string;
+    /** @param {any} node Condition. @param {FilterField|null} field Resolved field. @returns {HTMLElement} */
+    _removeConditionButton(node: any, field: FilterField | null): HTMLElement;
+    /**
+     * Resolves the strings the two value builders need. They are module functions so that the
+     * markup they produce stays testable without a component, which means the words have to be
+     * handed to them rather than looked up inside.
+     * @returns {FilterValueMessages}
+     */
+    _valueMessages(): FilterValueMessages;
+    /**
+     * 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;
 }
 /** @event Filter#change @type {CustomEvent<Record<string,unknown>>} */
 /** @event Filter#apply @type {CustomEvent<{value:FilterAst}>} */
@@ -329,3 +377,10 @@ export declare class Filter extends Component<FilterOptions> {
 /** @event Filter#query @type {CustomEvent<Record<string,unknown>>} */
 /** @event Filter#loaded @type {CustomEvent<Record<string,unknown>>} */
 /** @event Filter#error @type {CustomEvent<Record<string,unknown>>} */
+/**
+ * Reports a restricted root mismatch without mutating the supplied expression.
+ * @param {FilterAst} value Expression to validate.
+ * @param {'and'|'or'|null} logic Required root logic.
+ * @returns {Record<string,string>|null} Actionable validation error, or null.
+ */
+export declare function rootLogicError(value: FilterAst, logic: 'and' | 'or' | null): Record<string, string> | null;