@zeyos/zx 4.3.0 → 4.4.0

package/dist/types/components/entity-ref/entity-ref.d.ts

@@ -0,0 +1,331 @@
+import { Component } from '../../core/component.js';
+export type EntityRefContent = string | number | Node | Component | null;
+export type EntityRefIcon = string | Node | Component | (() => string | Node | Component | null) | null;
+export type EntityRefLink = {
+    /**
+     * Native primary-link destination.
+     */
+    href: string;
+    /**
+     * Native browsing context.
+     */
+    target?: string;
+    /**
+     * Native link relationship.
+     */
+    rel?: string;
+    /**
+     * Native download hint; a string supplies the filename.
+     */
+    download?: boolean | string;
+    /**
+     * Optional callback after an uncanceled activation; navigation remains native.
+     */
+    onclick?: (event: MouseEvent, entity: Readonly<EntityRefState>, component: EntityRef) => void;
+};
+export type EntityRefMetadata = {
+    /**
+     * Metadata label.
+     */
+    label: string;
+    /**
+     * Metadata value.
+     */
+    value: EntityRefContent;
+    /**
+     * Optional Zx icon before the value.
+     */
+    icon?: string | null;
+    /**
+     * Whether the label is visible instead of visually hidden.
+     */
+    showLabel?: boolean;
+};
+export type EntityRefAction = {
+    /**
+     * Stable action identifier.
+     */
+    id: string;
+    /**
+     * Visible label.
+     */
+    label?: string;
+    /**
+     * Optional Zx icon.
+     */
+    icon?: string | null;
+    /**
+     * Accessible/native title, required when the label is empty.
+     */
+    title?: string;
+    /**
+     * Optional safe native link destination; otherwise a button is rendered.
+     */
+    href?: string;
+    /**
+     * Native link browsing context.
+     */
+    target?: string;
+    /**
+     * Native link relationship.
+     */
+    rel?: string;
+    /**
+     * Visual intent.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Whether activation is unavailable.
+     */
+    disabled?: boolean;
+    /**
+     * Callback after an uncanceled activation.
+     */
+    onselect?: (id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, component: EntityRef) => void;
+};
+export type EntityRefActionEntry = Element | EntityRefAction;
+export type EntityRefLinkValue = string | EntityRefLink | null;
+export type EntityRefOptions = {
+    /**
+     * Application-owned entity identifier included in events.
+     */
+    id?: unknown;
+    /**
+     * Primary identity text.
+     */
+    title?: string;
+    /**
+     * Secondary identity text or safe caller-supplied content.
+     */
+    subtitle?: EntityRefContent;
+    /**
+     * Icon name, node, component, or lazy renderer.
+     */
+    icon?: EntityRefIcon;
+    /**
+     * Labelled dense metadata.
+     */
+    metadata?: EntityRefMetadata[];
+    /**
+     * Optional native primary link.
+     */
+    link?: EntityRefLinkValue;
+    /**
+     * Secondary controls; element actions keep their own behavior.
+     */
+    actions?: EntityRefActionEntry[];
+    /**
+     * Density-independent identity size.
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Whether long identity text may wrap instead of truncating.
+     */
+    wrap?: boolean;
+    /**
+     * Accessible name for secondary actions.
+     */
+    actionsLabel?: string;
+    /**
+     * Preventable primary-link listener.
+     */
+    onactivate?: (event: CustomEvent<{
+        id: unknown;
+        entity: Readonly<EntityRefState>;
+        href: string;
+        event: MouseEvent;
+    }>) => void;
+    /**
+     * Preventable delegated-action listener.
+     */
+    onaction?: (event: CustomEvent<{
+        id: string;
+        action: Readonly<EntityRefAction>;
+        entity: Readonly<EntityRefState>;
+        event: MouseEvent;
+    }>) => void;
+};
+export type EntityRefState = {
+    /**
+     * Entity identifier.
+     */
+    id: unknown;
+    /**
+     * Primary identity.
+     */
+    title: string;
+    /**
+     * Secondary identity.
+     */
+    subtitle: EntityRefContent;
+    /**
+     * Identity icon.
+     */
+    icon: EntityRefIcon;
+    /**
+     * Normalized metadata copies.
+     */
+    metadata: EntityRefMetadata[];
+    /**
+     * Safe native link.
+     */
+    link: EntityRefLink | null;
+    /**
+     * Normalized action copies or elements.
+     */
+    actions: EntityRefActionEntry[];
+    /**
+     * Presentation size.
+     */
+    size: 'sm' | 'md' | 'lg';
+    /**
+     * Wrapping state.
+     */
+    wrap: boolean;
+    /**
+     * Action-group label.
+     */
+    actionsLabel: string;
+};
+/** @typedef {string|number|Node|Component|null} EntityRefContent */
+/** @typedef {string|Node|Component|(()=>string|Node|Component|null)|null} EntityRefIcon */
+/**
+ * @typedef {Object} EntityRefLink
+ * @property {string} href Native primary-link destination.
+ * @property {string} [target] Native browsing context.
+ * @property {string} [rel] Native link relationship.
+ * @property {boolean|string} [download] Native download hint; a string supplies the filename.
+ * @property {(event: MouseEvent, entity: Readonly<EntityRefState>, component: EntityRef) => void} [onclick]
+ *   Optional callback after an uncanceled activation; navigation remains native.
+ */
+/**
+ * @typedef {Object} EntityRefMetadata
+ * @property {string} label Metadata label.
+ * @property {EntityRefContent} value Metadata value.
+ * @property {string|null} [icon=null] Optional Zx icon before the value.
+ * @property {boolean} [showLabel=true] Whether the label is visible instead of visually hidden.
+ */
+/**
+ * @typedef {Object} EntityRefAction
+ * @property {string} id Stable action identifier.
+ * @property {string} [label=''] Visible label.
+ * @property {string|null} [icon=null] Optional Zx icon.
+ * @property {string} [title] Accessible/native title, required when the label is empty.
+ * @property {string} [href] Optional safe native link destination; otherwise a button is rendered.
+ * @property {string} [target] Native link browsing context.
+ * @property {string} [rel] Native link relationship.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='ghost'] Visual intent.
+ * @property {boolean} [disabled=false] Whether activation is unavailable.
+ * @property {(id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, component: EntityRef) => void} [onselect]
+ *   Callback after an uncanceled activation.
+ */
+/** @typedef {Element|EntityRefAction} EntityRefActionEntry */
+/** @typedef {string|EntityRefLink|null} EntityRefLinkValue */
+/**
+ * @typedef {Object} EntityRefOptions
+ * @property {unknown} [id=null] Application-owned entity identifier included in events.
+ * @property {string} [title=''] Primary identity text.
+ * @property {EntityRefContent} [subtitle=null] Secondary identity text or safe caller-supplied content.
+ * @property {EntityRefIcon} [icon=null] Icon name, node, component, or lazy renderer.
+ * @property {EntityRefMetadata[]} [metadata=[]] Labelled dense metadata.
+ * @property {EntityRefLinkValue} [link=null] Optional native primary link.
+ * @property {EntityRefActionEntry[]} [actions=[]] Secondary controls; element actions keep their own behavior.
+ * @property {'sm'|'md'|'lg'} [size='md'] Density-independent identity size.
+ * @property {boolean} [wrap=false] Whether long identity text may wrap instead of truncating.
+ * @property {string} [actionsLabel='Entity actions'] Accessible name for secondary actions.
+ * @property {(event: CustomEvent<{id: unknown, entity: Readonly<EntityRefState>, href: string, event: MouseEvent}>) => void} [onactivate]
+ *   Preventable primary-link listener.
+ * @property {(event: CustomEvent<{id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, event: MouseEvent}>) => void} [onaction]
+ *   Preventable delegated-action listener.
+ */
+/**
+ * @typedef {Object} EntityRefState
+ * @property {unknown} id Entity identifier.
+ * @property {string} title Primary identity.
+ * @property {EntityRefContent} subtitle Secondary identity.
+ * @property {EntityRefIcon} icon Identity icon.
+ * @property {EntityRefMetadata[]} metadata Normalized metadata copies.
+ * @property {EntityRefLink|null} link Safe native link.
+ * @property {EntityRefActionEntry[]} actions Normalized action copies or elements.
+ * @property {'sm'|'md'|'lg'} size Presentation size.
+ * @property {boolean} wrap Wrapping state.
+ * @property {string} actionsLabel Action-group label.
+ */
+/**
+ * Dense entity identity for tables, feeds, selectors, and detail metadata. It owns presentation and
+ * safe native-link/action semantics; routing, permissions, context menus, and persistence remain
+ * application-owned.
+ * @fires EntityRef#activate
+ * @fires EntityRef#action
+ * @extends {Component<EntityRefOptions>}
+ */
+export declare class EntityRef extends Component<EntityRefOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    _state: EntityRefState;
+    _renderedActions: any[] | EntityRefActionEntry[];
+    static cssName: string;
+    /** @type {Readonly<EntityRefOptions>} */
+    static defaults: Readonly<EntityRefOptions>;
+    /**
+     * Creates or enhances a dense entity reference.
+     * @param {Element|string|null} [target=null] Existing host, selector, or null.
+     * @param {EntityRefOptions} [options={}] Entity presentation.
+     */
+    constructor(target?: Element | string | null, options?: EntityRefOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Updates any subset of the identity without replacing the root.
+     * @param {Partial<EntityRefOptions>} values Next values.
+     * @returns {this}
+     */
+    set(values?: Partial<EntityRefOptions>): this;
+    /** Replaces the metadata collection. @param {EntityRefMetadata[]} metadata Metadata. @returns {this} */
+    setMetadata(metadata: EntityRefMetadata[]): this;
+    /** Replaces the secondary action controls. @param {EntityRefActionEntry[]} actions Actions. @returns {this} */
+    setActions(actions: EntityRefActionEntry[]): this;
+    /** Sets or clears the primary link. @param {EntityRefLinkValue} link Link. @returns {this} */
+    setLink(link: EntityRefLinkValue): this;
+    /**
+     * Returns a defensive presentation snapshot. Caller-supplied Nodes and Components retain their
+     * identity; arrays and descriptors are copied.
+     * @returns {Readonly<EntityRefState>}
+     */
+    getEntity(): Readonly<EntityRefState>;
+    /** Focuses the primary link or the first enabled action. @returns {this} */
+    focus(): this;
+    /** Restores an enhanced target exactly, or removes an owned reference. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _handleClick(event: MouseEvent): void;
+}
+/**
+ * Normalizes an entity-reference contract without touching the DOM.
+ * @param {Partial<EntityRefOptions>|null|undefined} values Candidate values.
+ * @returns {EntityRefState}
+ */
+export declare function normalizeEntityRef(values?: Partial<EntityRefOptions> | null | undefined): EntityRefState;
+/**
+ * Normalizes and secures a primary native link.
+ * @param {EntityRefLinkValue|unknown} value Candidate link.
+ * @returns {EntityRefLink|null}
+ */
+export declare function normalizeEntityRefLink(value: EntityRefLinkValue | unknown): EntityRefLink | null;
+/**
+ * Normalizes labelled metadata, omitting entries without a label or displayable value.
+ * @param {unknown} values Candidate metadata.
+ * @returns {EntityRefMetadata[]}
+ */
+export declare function normalizeEntityRefMetadata(values: unknown): EntityRefMetadata[];
+/**
+ * Normalizes delegated actions while preserving caller-supplied Elements.
+ * @param {unknown} values Candidate actions.
+ * @returns {EntityRefActionEntry[]}
+ */
+export declare function normalizeEntityRefActions(values: unknown): EntityRefActionEntry[];
+/** Fired when the native primary link is activated. @event EntityRef#activate @type {CustomEvent<{id: unknown, entity: Readonly<EntityRefState>, href: string, event: MouseEvent}>} */
+/** Fired when a delegated secondary action is activated. @event EntityRef#action @type {CustomEvent<{id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, event: MouseEvent}>} */

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

@@ -0,0 +1,234 @@
+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.
+     */
+    mime?: string;
+    /**
+     * Optional supporting text before generated metadata.
+     */
+    subtitle?: EntityRefContent;
+    /**
+     * File icon name, node, component, or lazy renderer.
+     */
+    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;
+    /**
+     * File-identity presentation size.
+     */
+    density?: '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;
+    /**
+     * 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;
+    /**
+     * Identity size.
+     */
+    density: '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;
+/** 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}>} */