@zeyos/zx 4.3.4 → 5.0.0

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

@@ -0,0 +1,262 @@
+import { Component } from '../../core/component.js';
+import { EntityRef } from '../entity-ref/entity-ref.js';
+export type EntityRefContent = import('../entity-ref/entity-ref.js').EntityRefContent;
+export type EntityRefIcon = import('../entity-ref/entity-ref.js').EntityRefIcon;
+export type EntityRefMetadata = import('../entity-ref/entity-ref.js').EntityRefMetadata;
+export type EntityRefLinkValue = import('../entity-ref/entity-ref.js').EntityRefLinkValue;
+export type EntityRefActionEntry = import('../entity-ref/entity-ref.js').EntityRefActionEntry;
+export type FileStatus = 'ready' | 'temporary' | 'waiting' | 'uploading' | 'processing' | 'success' | 'error';
+export type FileItemOptions = {
+    /**
+     * Application-owned file identifier included in events.
+     */
+    id?: unknown;
+    /**
+     * File name.
+     */
+    name?: string;
+    /**
+     * Byte count; invalid and negative values are omitted.
+     */
+    size?: number | string | null;
+    /**
+     * MIME type. Shown as a readable type ("PDF", "Image"), never as
+     * the raw string, and used to pick the icon.
+     */
+    mime?: string;
+    /**
+     * Type shown beside the size; null derives it from the
+     * MIME type (or the name's extension when the MIME type is unfamiliar), an empty string hides it.
+     */
+    typeLabel?: string | null;
+    /**
+     * Optional supporting text before generated metadata.
+     */
+    subtitle?: EntityRefContent;
+    /**
+     * File icon name, node, component, or lazy renderer. The
+     * generic `'file'` glyph gives way to one for the MIME type when the active icon set has it.
+     */
+    icon?: EntityRefIcon;
+    /**
+     * Additional labelled metadata.
+     */
+    metadata?: EntityRefMetadata[];
+    /**
+     * Optional safe native file/download link.
+     */
+    link?: EntityRefLinkValue;
+    /**
+     * File actions; application policy stays external.
+     */
+    actions?: EntityRefActionEntry[];
+    /**
+     * Durable or transient presentation state.
+     */
+    status?: FileStatus;
+    /**
+     * Overrides the generated state label; an empty string hides it.
+     */
+    statusLabel?: string | null;
+    /**
+     * Completed percentage, clamped to 0–100.
+     */
+    progress?: number | null;
+    /**
+     * Whether active progress has no known amount.
+     */
+    indeterminate?: boolean;
+    /**
+     * Size of the file's icon and name.
+     */
+    identitySize?: 'sm' | 'md' | 'lg';
+    /**
+     * Whether long identity text may wrap.
+     */
+    wrap?: boolean;
+    /**
+     * Accessible name for secondary actions.
+     */
+    actionsLabel?: string;
+    /**
+     * Locale passed to `formatFileSize`.
+     */
+    locale?: string;
+    /**
+     * Preventable native-link listener.
+     */
+    onactivate?: (event: CustomEvent<{
+        id: unknown;
+        file: Readonly<FileItemState>;
+        href: string;
+        event: MouseEvent;
+    }>) => void;
+    /**
+     * Preventable file-action listener.
+     */
+    onaction?: (event: CustomEvent<{
+        id: string;
+        fileId: unknown;
+        action: object;
+        file: Readonly<FileItemState>;
+        event: MouseEvent;
+    }>) => void;
+};
+export type FileItemState = {
+    /**
+     * File identifier.
+     */
+    id: unknown;
+    /**
+     * File name.
+     */
+    name: string;
+    /**
+     * Byte count.
+     */
+    size: number | null;
+    /**
+     * MIME type.
+     */
+    mime: string;
+    /**
+     * Explicit type label, or null for the one derived from `mime`.
+     */
+    typeLabel: string | null;
+    /**
+     * Supporting content.
+     */
+    subtitle: EntityRefContent;
+    /**
+     * File visual.
+     */
+    icon: EntityRefIcon;
+    /**
+     * Additional metadata.
+     */
+    metadata: EntityRefMetadata[];
+    /**
+     * Safe native link.
+     */
+    link: import('../entity-ref/entity-ref.js').EntityRefLink | null;
+    /**
+     * Normalized actions.
+     */
+    actions: EntityRefActionEntry[];
+    /**
+     * Presentation state.
+     */
+    status: FileStatus;
+    /**
+     * Explicit state label, or null for the generated label.
+     */
+    statusLabel: string | null;
+    /**
+     * Completed percentage.
+     */
+    progress: number | null;
+    /**
+     * Unknown-progress state.
+     */
+    indeterminate: boolean;
+    /**
+     * Size of the file's icon and name.
+     */
+    identitySize: 'sm' | 'md' | 'lg';
+    /**
+     * Wrapping state.
+     */
+    wrap: boolean;
+    /**
+     * Action-group label.
+     */
+    actionsLabel: string;
+    /**
+     * File-size locale.
+     */
+    locale: string | undefined;
+};
+/**
+ * Durable or transient file presentation. The host owns upload/download transport, authorization,
+ * preview behavior, retry policy, and persistence.
+ * @fires FileItem#activate
+ * @fires FileItem#action
+ * @extends {Component<FileItemOptions>}
+ */
+export declare class FileItem extends Component<FileItemOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    _state: FileItemState;
+    _entity: EntityRef;
+    static cssName: string;
+    /** @type {Readonly<FileItemOptions>} */
+    static defaults: Readonly<FileItemOptions>;
+    /**
+     * Creates or enhances a file row.
+     * @param {Element|string|null} [target=null] Existing host, selector, or null.
+     * @param {FileItemOptions} [options={}] File presentation.
+     */
+    constructor(target?: Element | string | null, options?: FileItemOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Updates any subset of the file without replacing the row root.
+     * @param {Partial<FileItemOptions>} values Next values.
+     * @returns {this}
+     */
+    set(values?: Partial<FileItemOptions>): this;
+    /**
+     * Updates the file lifecycle state and, optionally, its visible label.
+     * @param {FileStatus} status State.
+     * @param {string|null} [statusLabel] Explicit label.
+     * @returns {this}
+     */
+    setStatus(status: FileStatus, statusLabel?: string | null): this;
+    /**
+     * Updates the progress meter.
+     * @param {number|null} progress Completed percentage, or null.
+     * @param {{indeterminate?: boolean}} [options={}] Unknown-progress override.
+     * @returns {this}
+     */
+    setProgress(progress: number | null, { indeterminate }?: {
+        indeterminate?: boolean;
+    }): this;
+    /** Returns a defensive file snapshot. @returns {Readonly<FileItemState>} */
+    getFile(): Readonly<FileItemState>;
+    /** Focuses the native destination or first enabled action. @returns {this} */
+    focus(): this;
+    /** Restores an enhanced target exactly, or removes an owned row. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+    /** @param {CustomEvent} event @returns {void} */
+    _forwardActivate(event: CustomEvent): void;
+    /** @param {CustomEvent} event @returns {void} */
+    _forwardAction(event: CustomEvent): void;
+}
+/**
+ * Normalizes a file presentation without touching the DOM.
+ * @param {Partial<FileItemOptions>|null|undefined} values Candidate values.
+ * @returns {FileItemState}
+ */
+export declare function normalizeFileItem(values?: Partial<FileItemOptions> | null | undefined): FileItemState;
+/**
+ * A readable name for a file's type: "PDF", "CSV", "Image", "Spreadsheet". An unfamiliar MIME type
+ * falls back to the name's extension in capitals ("EXE"); without a MIME type, or with neither,
+ * the result is empty — a raw MIME string is never shown.
+ * @param {string} mime MIME type, possibly with parameters (`text/csv; charset=utf-8`).
+ * @param {string} [name=''] File name, consulted only when the MIME type is unfamiliar.
+ * @returns {string}
+ */
+export declare function fileTypeLabel(mime: string, name?: string): string;
+/**
+ * The icon name for a MIME type: a type-specific glyph when the active icon set can draw one,
+ * `'file'` otherwise. Font Awesome resolves every name it is given; the bundled inline set only
+ * those it carries or that `registerIcons()` added, so a missing glyph never shows a placeholder.
+ * @param {string} mime MIME type, possibly with parameters.
+ * @returns {string}
+ */
+export declare function fileTypeIcon(mime: string): string;
+/** Fired before a native file link continues. @event FileItem#activate @type {CustomEvent<{id: unknown, file: Readonly<FileItemState>, href: string, event: MouseEvent}>} */
+/** Fired before a descriptor action callback runs. @event FileItem#action @type {CustomEvent<{id: string, fileId: unknown, action: object, file: Readonly<FileItemState>, event: MouseEvent}>} */

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;