@zeyos/zx 4.1.0 → 4.2.0

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

@@ -0,0 +1,303 @@
+import { RecordView } from '../view/record-view.js';
+export type ViewRecord = Record<string, any>;
+export type ViewField = import('../view/record-view.js').ViewField;
+export type RecordViewOptions = import('../view/record-view.js').RecordViewOptions;
+export type RecordCardValueSource = import('./record-card.js').RecordCardValueSource;
+export type RecordCardPreview = import('./record-card.js').RecordCardPreview;
+export type RecordCardLink = import('./record-card.js').RecordCardLink;
+export type RecordCardAction = import('./record-card.js').RecordCardAction;
+export type CardViewOptions = {
+    /**
+     * Shared ordered field descriptors.
+     */
+    fields?: ViewField[];
+    /**
+     * Initial records.
+     */
+    data?: ViewRecord[];
+    /**
+     * Stable record id accessor.
+     */
+    recordId?: string | ((record: ViewRecord) => unknown);
+    /**
+     * Initial shared sort.
+     */
+    sort?: import('../view/record-view.js').ViewSort | null;
+    /**
+     * Local sorting or event-only server sorting.
+     */
+    sortMode?: 'local' | 'server';
+    /**
+     * Record selection behavior.
+     */
+    selectable?: false | 'single' | 'multi';
+    /**
+     * Initially selected record ids.
+     */
+    selection?: unknown[];
+    /**
+     * Preferred shared field order.
+     */
+    fieldOrder?: string[];
+    /**
+     * Initially hidden metadata fields.
+     */
+    hiddenFields?: string[];
+    /**
+     * Whether to expose shared field controls.
+     */
+    fieldControls?: boolean;
+    /**
+     * Empty-result content.
+     */
+    emptyText?: string | Node | (() => string | Node) | null;
+    /**
+     * Title field id or explicit resolver.
+     */
+    titleField?: RecordCardValueSource;
+    /**
+     * Subtitle field id or explicit resolver.
+     */
+    subtitleField?: RecordCardValueSource;
+    /**
+     * Preview field id or explicit resolver.
+     */
+    preview?: string | ((record: ViewRecord, index: number) => RecordCardPreview);
+    /**
+     * Preview alt field, literal, or resolver.
+     */
+    previewAlt?: string | ((record: ViewRecord, index: number) => unknown) | null;
+    /**
+     * Safe native title link or resolver.
+     */
+    link?: RecordCardLink | ((record: ViewRecord, index: number) => RecordCardLink);
+    /**
+     * Listener-free action descriptors or resolver.
+     */
+    actions?: RecordCardAction[] | ((record: ViewRecord, index: number) => RecordCardAction[]);
+    /**
+     * Field id or local group resolver.
+     */
+    groupBy?: string | ((record: ViewRecord, index: number) => unknown) | null;
+    /**
+     * Preferred group ids; missing ids render as empty groups.
+     */
+    groupOrder?: unknown[];
+    /**
+     * Responsive minimum card width.
+     */
+    minCardWidth?: number | string;
+    /**
+     * Maximum cards per row; null is unconstrained.
+     */
+    maxColumns?: number | null;
+    /**
+     * Card surface treatment.
+     */
+    variant?: 'outlined' | 'raised' | 'filled';
+    /**
+     * Skeleton cards shown while loading.
+     */
+    loadingCount?: number;
+    /**
+     * Per-card title heading level.
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Accessible collection label.
+     */
+    label?: string;
+    onrecordaction?: (event: CustomEvent<Record<string, unknown>>) => void;
+};
+export type CardViewState = {
+    /**
+     * State schema version.
+     */
+    version: 1;
+    /**
+     * Shared field order.
+     */
+    fieldOrder: string[];
+    /**
+     * Shared hidden fields.
+     */
+    hiddenFields: string[];
+    /**
+     * Shared sort.
+     */
+    sort: import('../view/record-view.js').ViewSort | null;
+    /**
+     * Preferred group ids.
+     */
+    groupOrder: string[];
+    /**
+     * Responsive minimum card width.
+     */
+    minCardWidth: string;
+    /**
+     * Maximum cards per row.
+     */
+    maxColumns: number | null;
+    /**
+     * Surface treatment.
+     */
+    variant: 'outlined' | 'raised' | 'filled';
+};
+export type CardRecordGroup = {
+    /**
+     * Normalized group id, null for an ungrouped collection.
+     */
+    id: string | null;
+    /**
+     * Display label.
+     */
+    label: string;
+    /**
+     * Records in current shared display order.
+     */
+    records: ViewRecord[];
+};
+/** @typedef {Record<string, any>} ViewRecord */
+/** @typedef {import('../view/record-view.js').ViewField} ViewField */
+/** @typedef {import('../view/record-view.js').RecordViewOptions} RecordViewOptions */
+/** @typedef {import('./record-card.js').RecordCardValueSource} RecordCardValueSource */
+/** @typedef {import('./record-card.js').RecordCardPreview} RecordCardPreview */
+/** @typedef {import('./record-card.js').RecordCardLink} RecordCardLink */
+/** @typedef {import('./record-card.js').RecordCardAction} RecordCardAction */
+/**
+ * @typedef {Object} CardViewOptions
+ * @property {ViewField[]} [fields=[]] Shared ordered field descriptors.
+ * @property {ViewRecord[]} [data=[]] Initial records.
+ * @property {string|((record:ViewRecord)=>unknown)} [recordId='ID'] Stable record id accessor.
+ * @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 {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 {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.
+ * @property {string|((record:ViewRecord,index:number)=>RecordCardPreview)} [preview]
+ * Preview field id or explicit resolver.
+ * @property {string|((record:ViewRecord,index:number)=>unknown)|null} [previewAlt=null]
+ * Preview alt field, literal, or resolver.
+ * @property {RecordCardLink|((record:ViewRecord,index:number)=>RecordCardLink)} [link]
+ * Safe native title link or resolver.
+ * @property {RecordCardAction[]|((record:ViewRecord,index:number)=>RecordCardAction[])} [actions=[]]
+ * Listener-free action descriptors or resolver.
+ * @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|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.
+ * @property {1|2|3|4|5|6} [headingLevel=3] Per-card title heading level.
+ * @property {string} [label='Card view'] Accessible collection label.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onrecordaction]
+ */
+/**
+ * @typedef {Object} CardViewState
+ * @property {1} version State schema version.
+ * @property {string[]} fieldOrder Shared field order.
+ * @property {string[]} hiddenFields Shared hidden fields.
+ * @property {import('../view/record-view.js').ViewSort|null} sort Shared sort.
+ * @property {string[]} groupOrder Preferred group ids.
+ * @property {string} minCardWidth Responsive minimum card width.
+ * @property {number|null} maxColumns Maximum cards per row.
+ * @property {'outlined'|'raised'|'filled'} variant Surface treatment.
+ */
+/**
+ * @typedef {Object} CardRecordGroup
+ * @property {string|null} id Normalized group id, null for an ungrouped collection.
+ * @property {string} label Display label.
+ * @property {ViewRecord[]} records Records in current shared display order.
+ */
+/**
+ * Responsive, schema-friendly record cards with shared fields, sorting, selection, state, groups,
+ * safe preview media, native title links, and delegated actions.
+ * @fires CardView#recordaction
+ * @extends {RecordView}
+ */
+export declare class CardView extends RecordView {
+    _cardCreatedRoot: boolean;
+    _cardOriginal: import("../../core/dom.js").TargetSnapshot;
+    _cardCleaned: boolean;
+    _cardNodesById: Map<any, any>;
+    _cardGroupOrder: string[];
+    _cardMinWidth: string;
+    _cardMaxColumns: number;
+    _cardVariant: "filled" | "outlined" | "raised";
+    _cardLoadingCount: number;
+    _cardHeadingLevel: 1 | 2 | 3 | 4 | 5 | 6;
+    static cssName: string;
+    /** @type {Readonly<CardViewOptions & RecordViewOptions>} */
+    static defaults: Readonly<CardViewOptions & RecordViewOptions>;
+    /**
+     * Creates or enhances a card view.
+     * @param {Element|string|null} [target=null] Existing root, selector, or null.
+     * @param {CardViewOptions & RecordViewOptions} [options={}] Card and shared view options.
+     */
+    constructor(target?: Element | string | null, options?: CardViewOptions & RecordViewOptions);
+    /** @returns {HTMLElement} Card-view root. */
+    render(): HTMLElement;
+    /** Returns shared plus CardView configuration, never records or rendered values. @returns {CardViewState} */
+    getViewState(): CardViewState;
+    /**
+     * Restores shared and CardView configuration. Unknown shared fields reconcile in RecordView.
+     * @param {Partial<CardViewState>|null} state Saved JSON-safe state.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setViewState(state: Partial<CardViewState> | null, options?: {
+        silent?: boolean;
+    }): this;
+    /** Restores an enhanced target exactly, or removes an owned root. @returns {void} */
+    destroy(): void;
+    /** @protected @param {string} reason Refresh reason. @returns {void} */
+    protected _refreshView(reason: string): void;
+    /** @private @returns {void} */
+    private _applyCardLayout;
+    /** @private @returns {void} */
+    private _renderCardSort;
+    /** @private @returns {void} */
+    private _changeCardSort;
+    /** @private @returns {void} */
+    private _renderCards;
+    /** @private @param {CardRecordGroup} group @param {ViewField[]} fields @param {ViewField[]} visibleFields @param {number} groupIndex @returns {HTMLElement} */
+    private _createCardGroup;
+    /** @private @returns {HTMLElement} */
+    private _createCardSkeletons;
+    /** @private @returns {HTMLElement} */
+    private _createCardEmpty;
+    /** @private @returns {void} */
+    private _syncCardSelection;
+    /** @private @param {MouseEvent} event @returns {void} */
+    private _cardClick;
+    /** @private @param {MouseEvent} event @returns {void} */
+    private _cardDoubleClick;
+    /** @private @param {KeyboardEvent} event @returns {void} */
+    private _cardKeydown;
+    /** @private @param {ViewRecord} record @param {unknown} id @param {number} index @param {Event} event @returns {void} */
+    private _activateCard;
+    /** @private @param {ViewRecord} record @param {unknown} id @param {number} index @param {string|undefined} actionId @param {MouseEvent} event @returns {void} */
+    private _activateCardAction;
+    /** @private @param {Event} event @returns {void} */
+    private _cardPreviewError;
+    /** @private @returns {Readonly<CardViewOptions & RecordViewOptions>} */
+    private _cardOptions;
+}
+/**
+ * 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.
+ * @param {ViewRecord[]} records Records in display order.
+ * @param {CardViewOptions['groupBy']} groupBy Group field or resolver.
+ * @param {unknown[]} [groupOrder=[]] Preferred group ids.
+ * @param {ViewField[]} [fields=[]] Complete fields for accessor-aware grouping.
+ * @returns {CardRecordGroup[]} Deterministic groups.
+ */
+export declare function groupCardRecords(records: ViewRecord[], groupBy: CardViewOptions['groupBy'], groupOrder?: unknown[], fields?: ViewField[]): CardRecordGroup[];
+/** @param {unknown} value @returns {string} */
+export declare function normalizeCardWidth(value: unknown): string;

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

@@ -0,0 +1,242 @@
+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 RecordCardPreviewDescriptor = {
+    /**
+     * Image URL.
+     */
+    src: string;
+    /**
+     * Image alternative text.
+     */
+    alt?: string;
+    /**
+     * Image fitting behavior.
+     */
+    fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+};
+export type RecordCardPreview = string | Node | RecordCardPreviewDescriptor | null;
+export type RecordCardLinkDescriptor = {
+    /**
+     * Native link destination.
+     */
+    href: string;
+    /**
+     * Native browsing context.
+     */
+    target?: string;
+    /**
+     * Native link relationship.
+     */
+    rel?: string;
+};
+export type RecordCardLink = string | RecordCardLinkDescriptor | null;
+export type RecordCardAction = {
+    /**
+     * Stable delegated-action identifier.
+     */
+    id: string;
+    /**
+     * Visible action label.
+     */
+    label?: string;
+    /**
+     * Optional Zx icon name.
+     */
+    icon?: string | null;
+    /**
+     * Accessible/native title, especially for an icon-only action.
+     */
+    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;
+    /**
+     * Whether a button action is unavailable.
+     */
+    disabled?: boolean;
+    /**
+     * Callback invoked by an owning view's delegated listener; this helper never installs listeners.
+     */
+    onclick?: (record: ViewRecord, index: number, event: MouseEvent) => void;
+};
+export type RecordCardOptions = {
+    /**
+     * Complete fields, used to resolve title and subtitle sources.
+     */
+    fields?: ViewField[];
+    /**
+     * Ordered fields rendered as labelled metadata.
+     */
+    visibleFields?: ViewField[];
+    /**
+     * Field id or explicit value resolver.
+     */
+    titleField?: RecordCardValueSource;
+    /**
+     * Field id or explicit value resolver.
+     */
+    subtitleField?: RecordCardValueSource;
+    /**
+     * Preview field id or explicit resolver.
+     */
+    preview?: string | ((record: ViewRecord, index: number) => RecordCardPreview);
+    /**
+     * Alternative-text field, literal text, or resolver.
+     */
+    previewAlt?: string | ((record: ViewRecord, index: number) => unknown) | null;
+    link?: RecordCardLink | ((record: ViewRecord, index: number) => RecordCardLink);
+    actions?: RecordCardAction[] | ((record: ViewRecord, index: number) => RecordCardAction[]);
+    /**
+     * Selection presentation.
+     */
+    selectable?: false | 'single' | 'multi';
+    /**
+     * Current selection state.
+     */
+    selected?: boolean;
+    /**
+     * Surface treatment.
+     */
+    variant?: 'outlined' | 'raised' | 'filled';
+    /**
+     * Card title heading level.
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Listener-free, owner-created controls such as a move handle.
+     */
+    controls?: Node[];
+};
+export type ResolvedRecordPreview = {
+    /**
+     * Explicit preview node.
+     */
+    node: Node | null;
+    /**
+     * Safe image URL, or null when rejected.
+     */
+    src: string | null;
+    /**
+     * Alternative text.
+     */
+    alt: string;
+    /**
+     * Image fitting behavior.
+     */
+    fit: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    /**
+     * Whether a supplied URL was unsafe or malformed.
+     */
+    rejected: boolean;
+};
+/** @typedef {Record<string, any>} ViewRecord */
+/** @typedef {import('../view/record-view.js').ViewField} ViewField */
+/** @typedef {string|((record:ViewRecord,index:number)=>unknown)|null} RecordCardValueSource */
+/**
+ * @typedef {Object} RecordCardPreviewDescriptor
+ * @property {string} src Image URL.
+ * @property {string} [alt] Image alternative text.
+ * @property {'cover'|'contain'|'fill'|'none'|'scale-down'} [fit='cover'] Image fitting behavior.
+ */
+/** @typedef {string|Node|RecordCardPreviewDescriptor|null} RecordCardPreview */
+/**
+ * @typedef {Object} RecordCardLinkDescriptor
+ * @property {string} href Native link destination.
+ * @property {string} [target] Native browsing context.
+ * @property {string} [rel] Native link relationship.
+ */
+/** @typedef {string|RecordCardLinkDescriptor|null} RecordCardLink */
+/**
+ * @typedef {Object} RecordCardAction
+ * @property {string} id Stable delegated-action identifier.
+ * @property {string} [label=''] Visible action label.
+ * @property {string|null} [icon=null] Optional Zx icon name.
+ * @property {string} [title] Accessible/native title, especially for an icon-only action.
+ * @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 {boolean} [disabled=false] Whether a button action is unavailable.
+ * @property {(record:ViewRecord,index:number,event:MouseEvent)=>void} [onclick]
+ * Callback invoked by an owning view's delegated listener; this helper never installs listeners.
+ */
+/**
+ * @typedef {Object} RecordCardOptions
+ * @property {ViewField[]} [fields=[]] Complete fields, used to resolve title and subtitle sources.
+ * @property {ViewField[]} [visibleFields=fields] Ordered fields rendered as labelled metadata.
+ * @property {RecordCardValueSource} [titleField=null] Field id or explicit value resolver.
+ * @property {RecordCardValueSource} [subtitleField=null] Field id or explicit value resolver.
+ * @property {string|((record:ViewRecord,index:number)=>RecordCardPreview)} [preview]
+ * Preview field id or explicit resolver.
+ * @property {string|((record:ViewRecord,index:number)=>unknown)|null} [previewAlt=null]
+ * Alternative-text field, literal text, or resolver.
+ * @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 {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.
+ * @property {Node[]} [controls=[]] Listener-free, owner-created controls such as a move handle.
+ */
+/**
+ * @typedef {Object} ResolvedRecordPreview
+ * @property {Node|null} node Explicit preview node.
+ * @property {string|null} src Safe image URL, or null when rejected.
+ * @property {string} alt Alternative text.
+ * @property {'cover'|'contain'|'fill'|'none'|'scale-down'} fit Image fitting behavior.
+ * @property {boolean} rejected Whether a supplied URL was unsafe or malformed.
+ */
+/**
+ * Builds the listener-free card anatomy shared by CardView and KanbanView. All primitive content
+ * 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.
+ *
+ * @param {ViewRecord} record Record to render.
+ * @param {number} index Current display index.
+ * @param {RecordCardOptions} [options={}] Rendering options.
+ * @returns {HTMLLIElement} Semantic record card list item.
+ */
+export declare function createRecordCard(record: ViewRecord, index: number, options?: RecordCardOptions): HTMLLIElement;
+/**
+ * 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.
+ * @param {ViewRecord} record Record.
+ * @param {number} index Display index.
+ * @param {RecordCardOptions['preview']} preview Preview field or resolver.
+ * @param {RecordCardOptions['previewAlt']} previewAlt Alt field, literal, or resolver.
+ * @param {ViewField[]} [fields=[]] Complete fields.
+ * @returns {ResolvedRecordPreview|null} Resolved preview.
+ */
+export declare function resolveRecordPreview(record: ViewRecord, index: number, preview: RecordCardOptions['preview'], previewAlt: RecordCardOptions['previewAlt'], fields?: ViewField[]): ResolvedRecordPreview | null;
+/**
+ * Resolves and validates a native title link without touching the DOM.
+ * @param {ViewRecord} record Record.
+ * @param {number} index Display index.
+ * @param {RecordCardOptions['link']} link Link value or resolver.
+ * @returns {RecordCardLinkDescriptor|null} Safe normalized link.
+ */
+export declare function resolveRecordLink(record: ViewRecord, index: number, link: RecordCardOptions['link']): RecordCardLinkDescriptor | null;
+/**
+ * Resolves and clones delegated action descriptors. Invalid entries are omitted rather than
+ * creating unnamed or ambiguously interactive controls.
+ * @param {ViewRecord} record Record.
+ * @param {number} index Display index.
+ * @param {RecordCardOptions['actions']} actions Actions or resolver.
+ * @returns {RecordCardAction[]} Normalized action copies.
+ */
+export declare function resolveRecordActions(record: ViewRecord, index: number, actions: RecordCardOptions['actions']): RecordCardAction[];