@zeyos/zx 4.3.0 → 4.4.0

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

@@ -62,6 +62,35 @@ export type ViewSort = {
      */
     dir: ViewSortDirection;
 };
+export type ViewFieldControlsConfig = {
+    /**
+     * Trigger label. Omitted resolves `recordView.fields`, English `Fields`.
+     */
+    label?: string;
+    /**
+     * Element or selector the disclosure is mounted into
+     * instead of the view's own toolbar. An unresolvable target falls back to the view.
+     */
+    target?: Element | string | null;
+};
+export type ViewFieldControlsSettings = {
+    /**
+     * Whether a concrete view renders the chooser at all.
+     */
+    enabled: boolean;
+    /**
+     * Whether the option was given as a `ViewFieldControlsConfig` object.
+     */
+    custom: boolean;
+    /**
+     * Configured trigger label, or null to resolve the message.
+     */
+    label: string | null;
+    /**
+     * Configured mount point, before resolution.
+     */
+    target: Element | string | null;
+};
 export type RecordViewState = {
     /**
      * State schema version.
@@ -118,9 +147,12 @@ export type RecordViewOptions = {
      */
     hiddenFields?: string[];
     /**
-     * Whether concrete views show the shared field chooser.
+     * Whether concrete views show the
+     * shared field chooser. `true` renders it in the view's own toolbar and `false` omits it; a
+     * `ViewFieldControlsConfig` object renders the same control with a translated `label` and, with
+     * `target`, mounts it into a host element such as a list toolbar.
      */
-    fieldControls?: boolean;
+    fieldControls?: boolean | ViewFieldControlsConfig;
     /**
      * Empty-result content.
      */
@@ -174,6 +206,21 @@ export type RecordViewOptions = {
  * @property {string} id Field id.
  * @property {ViewSortDirection} dir Sort direction.
  */
+/**
+ * Trigger customisation for the shared field chooser. Passing this object in place of `true` keeps
+ * the control and its state model exactly as they are; only its wording and mount point change.
+ * @typedef {Object} ViewFieldControlsConfig
+ * @property {string} [label] Trigger label. Omitted resolves `recordView.fields`, English `Fields`.
+ * @property {Element|string|null} [target=null] Element or selector the disclosure is mounted into
+ * instead of the view's own toolbar. An unresolvable target falls back to the view.
+ */
+/**
+ * @typedef {Object} ViewFieldControlsSettings
+ * @property {boolean} enabled Whether a concrete view renders the chooser at all.
+ * @property {boolean} custom Whether the option was given as a `ViewFieldControlsConfig` object.
+ * @property {string|null} label Configured trigger label, or null to resolve the message.
+ * @property {Element|string|null} target Configured mount point, before resolution.
+ */
 /**
  * @typedef {Object} RecordViewState
  * @property {1} version State schema version.
@@ -192,7 +239,10 @@ export type RecordViewOptions = {
  * @property {unknown[]} [selection=[]] Initially selected record ids.
  * @property {string[]} [fieldOrder=[]] Field ids in preferred order.
  * @property {string[]} [hiddenFields=[]] Initially hidden field ids.
- * @property {boolean} [fieldControls=true] Whether concrete views show the shared field chooser.
+ * @property {boolean|ViewFieldControlsConfig} [fieldControls=true] Whether concrete views show the
+ * shared field chooser. `true` renders it in the view's own toolbar and `false` omits it; a
+ * `ViewFieldControlsConfig` object renders the same control with a translated `label` and, with
+ * `target`, mounts it into a host element such as a list toolbar.
  * @property {string|Node|(() => string|Node)|null} [emptyText=null] Empty-result content.
  * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onrecordclick]
  * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onrecorddblclick]
@@ -226,6 +276,8 @@ export declare class RecordView extends Component<RecordViewOptions> {
     _viewSelectionAnchor: unknown;
     _viewFieldControls: HTMLElement;
     _viewFieldList: HTMLElement;
+    _viewFieldSettings: ViewFieldControlsSettings;
+    _viewFieldControlsTarget: Element;
     _viewInitialized: boolean;
     static cssName: string;
     /** @type {Readonly<RecordViewOptions>} */
@@ -384,10 +436,42 @@ export declare class RecordView extends Component<RecordViewOptions> {
     /**
      * Builds the shared show/hide and ordering disclosure for a concrete view toolbar.
      * @protected
-     * @param {string} [label='Fields'] Trigger label.
+     * @param {string|null} [label=null] Explicit trigger label. Omitted resolves the configured
+     * `fieldControls.label` and then the `recordView.fields` message.
      * @returns {HTMLElement} Disclosure element.
      */
-    protected _createViewFieldControls(label?: string): HTMLElement;
+    protected _createViewFieldControls(label?: string | null): HTMLElement;
+    /**
+     * Builds the shared field disclosure and mounts it where `fieldControls` asks for it: the host
+     * element named by `target`, or the view's own toolbar when no target resolves.
+     * @protected
+     * @param {Element} toolbar The view's own toolbar.
+     * @param {string|null} [label=null] Explicit trigger label, for views that own their wording.
+     * @returns {HTMLElement} The mounted disclosure.
+     */
+    protected _mountViewFieldControls(toolbar: Element, label?: string | null): HTMLElement;
+    /**
+     * Removes the shared field disclosure from wherever it was mounted. An external `target` keeps
+     * every node it had before the view was created.
+     * @protected
+     * @returns {void}
+     */
+    protected _removeViewFieldControls(): void;
+    /**
+     * Resolves the field-chooser trigger label: the configured one, else the translated message.
+     * @protected
+     * @returns {string} Trigger label.
+     */
+    protected _viewFieldControlsLabel(): string;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @protected
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string} Translated or built-in text.
+     */
+    protected _message(key: string, fallback: string, ...args: unknown[]): string;
     /** Concrete renderers override this hook. @protected @param {string} _reason Refresh reason. @returns {void} */
     protected _refreshView(_reason: string): void;
     /** Reads one record's stable id. @protected @param {ViewRecord} record Record. @returns {unknown} */
@@ -407,6 +491,13 @@ export declare class RecordView extends Component<RecordViewOptions> {
     /** @private @param {string|null} [focusId=null] @returns {void} */
     private _renderViewFieldControls;
 }
+/**
+ * Reads the `fieldControls` option in its three shapes. `true` and `false` keep their exact
+ * meaning; an object additionally carries the trigger label and the host element to mount into.
+ * @param {boolean|ViewFieldControlsConfig|null|undefined} value Raw option value.
+ * @returns {ViewFieldControlsSettings} Normalized settings.
+ */
+export declare function normalizeViewFieldControls(value: boolean | ViewFieldControlsConfig | null | undefined): ViewFieldControlsSettings;
 /**
  * Validates and clones field descriptors.
  * @param {ViewField[]} fields Fields.

package/dist/types/core/component.d.ts

@@ -73,10 +73,15 @@ export declare class Component<TOptions extends ComponentOptions = ComponentOpti
      * Dispatches a component event and a bubbling, composed `zx-*` DOM event.
      * @param {string} type Lowercase event name.
      * @param {Record<string, unknown>} [detail={}] Single event detail object.
+     * @param {{honorDomCancellation?:boolean}} [options={}] Mirrored DOM-event behavior. Components
+     * with a cancelable mutation boundary may opt into treating `preventDefault()` on the bubbling
+     * `zx-*` event exactly like cancellation of the component event.
      * @returns {Event & {detail: Record<string, unknown>}}
      * @fires Component#event
      */
-    emit(type: string, detail?: Record<string, unknown>): Event & {
+    emit(type: string, detail?: Record<string, unknown>, options?: {
+        honorDomCancellation?: boolean;
+    }): Event & {
         detail: Record<string, unknown>;
     };
     /**

package/dist/types/core/icons.d.ts

@@ -33,6 +33,12 @@ export type IconOptions = {
      * Adds Font Awesome's `fa-fw` for column-aligned glyphs.
      */
     fixedWidth?: boolean;
+    /**
+     * Throws `RangeError` on a name the bundled glyph set does not
+     * carry, instead of returning the placeholder. For call sites that can afford to fail — a test,
+     * a build-time check — rather than a screen rendering server data.
+     */
+    strict?: boolean;
 };
 /**
  * @typedef {Object} IconOptions
@@ -42,6 +48,9 @@ export type IconOptions = {
  * @property {string} [style] Font Awesome style for this icon only (`'solid'`, `'duotone'`, …).
  * @property {string} [family] Font Awesome family for this icon only (`'classic'`, `'sharp'`, …).
  * @property {boolean} [fixedWidth] Adds Font Awesome's `fa-fw` for column-aligned glyphs.
+ * @property {boolean} [strict=false] Throws `RangeError` on a name the bundled glyph set does not
+ *   carry, instead of returning the placeholder. For call sites that can afford to fail — a test,
+ *   a build-time check — rather than a screen rendering server data.
  */
 /**
  * Icon glyphs from Font Awesome Free 6 (solid, plus `square` from regular), fontawesome.com,
@@ -130,8 +139,16 @@ export declare function iconNames(): string[];
  * its renderer itself — `'fa:user'`, `'duotone:user'`, `'kit:zeyos-notes'`, `'builtin:check'`, or
  * a literal Font Awesome class list such as `'fa-solid fa-user'`.
  *
+ * **A name this cannot resolve never throws.** Icon names routinely arrive from a server, and one
+ * unconfigured name must not take down the screen it appears on. An inline glyph the bundled set
+ * does not carry renders as the placeholder described in `missingIcon()` and is reported once per
+ * distinct name through `console.warn`; pass `{ strict: true }` to get a `RangeError` instead.
+ * Only the inline-SVG path can fail this way: Font Awesome resolves names in the browser at render
+ * time, so a name under a loaded kit or stylesheet is never "unknown" here and never warns.
+ *
  * @param {string} name Icon name or spec.
  * @param {IconOptions} [options={}] Display and accessibility options.
  * @returns {SVGSVGElement|HTMLElement} An `<svg>` for inline glyphs, an `<i>` for Font Awesome.
+ * @throws {RangeError} With `{ strict: true }` only, when the bundled set has no such glyph.
  */
 export declare function icon(name: string, options?: IconOptions): SVGSVGElement | HTMLElement;

package/dist/types/index.d.ts

@@ -34,10 +34,12 @@ export { stack, grid, aspect } from './components/layout/layout.js';
 export { truncate, isTruncated } from './components/truncate/truncate.js';
 export { copyButton } from './components/copy/copy-button.js';
 export { CopyInput } from './components/copy/copy-input.js';
+export { CodeEditor, indentSelection, editorPosition } from './components/code-editor/code-editor.js';
 export { Toolbar } from './components/toolbar/toolbar.js';
 export { Toggle } from './components/toggle/toggle.js';
 export { Groupbox } from './components/groupbox/groupbox.js';
 export { Card } from './components/card/card.js';
+export { StatTile, statTile } from './components/stat-tile/stat-tile.js';
 export { Aurora } from './components/aurora/aurora.js';
 export { Panel } from './components/panel/panel.js';
 export { MasterPanel } from './components/master-panel/master-panel.js';
@@ -52,6 +54,11 @@ export { Search } from './components/search/search.js';
 export { AppIcon, appIcon } from './components/app-icon/app-icon.js';
 export { Launcher, rankLauncherItems } from './components/launcher/launcher.js';
 export { Avatar, avatarInitials } from './components/avatar/avatar.js';
+export { EntityRef, normalizeEntityRef, normalizeEntityRefLink, normalizeEntityRefMetadata, normalizeEntityRefActions } from './components/entity-ref/entity-ref.js';
+export { FileItem, normalizeFileItem } from './components/file-item/file-item.js';
+export { FileList, normalizeFileListItems } from './components/file-list/file-list.js';
+export { ActivityItem, resolveActivityActions, normalizeActivityAction, normalizeActivityTimestamp } from './components/activity-item/activity-item.js';
+export { ActivityList, groupActivityItems, normalizeActivityItems } from './components/activity-list/activity-list.js';
 export { AccountMenu } from './components/account-menu/account-menu.js';
 export { normalizeAppItems } from './internal/app-rail.js';
 export { AppSidebar } from './components/app-sidebar/app-sidebar.js';
@@ -78,17 +85,22 @@ export { DateRangePicker, clampRange, defaultDateRangePresets, normalizeRange, r
 export { DateRangeBox, formatRangeText, parseRangeText } from './components/datebox/date-range-box.js';
 export { Timebox, splitTime, joinTime } from './components/timebox/timebox.js';
 export { Calendar } from './components/calendar/calendar.js';
-export { CALENDAR_VIEWS, addCalendarDays, calendarDayDifference, calendarDayKey, calendarEventIntersects, calendarEventSpansDays, calendarRange, cloneCalendarEvent, layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents, shiftCalendarEvent, startOfCalendarDay, startOfCalendarWeek } from './components/calendar/calendar-model.js';
+export { CALENDAR_VIEWS, addCalendarDays, addCalendarMonths, calendarDayDifference, calendarDayKey, calendarEventIntersects, calendarEventSpansDays, calendarPageDate, calendarRange, cloneCalendarEvent, layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents, shiftCalendarEvent, startOfCalendarDay, startOfCalendarWeek } from './components/calendar/calendar-model.js';
 export { RecordView, normalizeViewFields, reconcileFieldOrder, moveViewField, readViewField, renderViewField, sortViewRecords, normalizeViewState, viewRecordId } from './components/view/record-view.js';
 export { Table, reorderTableRows } from './components/table/table.js';
 export { TableView } from './components/table-view/table-view.js';
 export { CardView } from './components/card-view/card-view.js';
 export { KanbanView } from './components/kanban-view/kanban-view.js';
+export { absoluteKanbanIndex, allowsKanbanTransition, createKanbanHistory, evaluateKanbanMove, kanbanSearchTerms, locateKanbanRecord, matchesKanbanSearch, normalizeKanbanRules, reorderKanbanRecords, resolveKanbanRules } from './components/kanban-view/kanban-policy.js';
+export { createKanbanAvatars, createKanbanCardHead, createKanbanIndicator, createKanbanProgress, kanbanAvatarLimit, resolveKanbanAssignees, resolveKanbanIndicator, resolveKanbanProgress } from './components/kanban-view/kanban-card.js';
 export { Grid, billingColumns, isBillingLine } from './components/grid/grid.js';
 export { Chart, ChartJsAdapter, chartSummaryTable, cloneChartValue, isEmptyChartData } from './components/chart/chart.js';
 export { TreeView } from './components/tree/tree.js';
 export { Finder } from './components/finder/finder.js';
 export { DataFilter } from './components/data-filter/data-filter.js';
+export { FilterPanel, isActiveValue, pruneValue, serializeFilterValue } from './components/filter-panel/filter-panel.js';
+export { SortControl } from './components/sort-control/sort-control.js';
+export { ListToolbar } from './components/list-toolbar/list-toolbar.js';
 export { Filter } from './components/filter/filter.js';
 export { filterOperators, emptyFilterAst, filterCondition, filterGroup, parseFilterAst, cloneFilterAst, stringifyFilterAst, validateFilterAst } from './components/filter/filter-model.js';
 export { Field } from './components/field/field.js';

package/dist/types/internal/app-rail.d.ts

@@ -238,6 +238,16 @@ export declare class AppRailPresenter extends Component<AppRailPresenterOptions>
     _syncActive(): void;
     /** @returns {void} */
     _clearArtifacts(): void;
+    /**
+     * Resolves one message through `msg()`, which falls back to the host translator. Copied from
+     * `Pagination` rather than invented: the rail's flyout label was the last user-visible string
+     * in the navigation stack with no way to change it.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @param {...unknown} args Interpolation arguments.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
 }
 /** Owns listeners attached to one dynamic rail render so `setItems()` can release them immediately. */
 declare class RailListenerScope extends Component {

package/dist/types/internal/menu-items.d.ts

@@ -0,0 +1,134 @@
+export type MenuItemRole = 'menuitem' | 'menuitemcheckbox' | 'menuitemradio';
+export type MenuController = {
+    /**
+     * Close the owning menu.
+     */
+    close: () => unknown;
+};
+export type MenuItem = {
+    /**
+     * Item label.
+     */
+    label: string;
+    /**
+     * Kernel icon name.
+     */
+    icon?: string;
+    /**
+     * Value emitted on selection.
+     */
+    value?: unknown;
+    /**
+     * Whether selection is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the action is dangerous.
+     */
+    danger?: boolean;
+    /**
+     * Native-link destination.
+     */
+    href?: string;
+    /**
+     * Native-link target.
+     */
+    target?: string;
+    /**
+     * Native-link relationship.
+     */
+    rel?: string;
+    /**
+     * Supporting text under the label.
+     */
+    description?: string;
+    /**
+     * Compact trailing metadata.
+     */
+    badge?: string | number;
+    /**
+     * Keyboard shortcut label.
+     */
+    shortcut?: string;
+    /**
+     * Additional trailing content.
+     */
+    adornment?: string | number | Node;
+    /**
+     * APG role.
+     */
+    role?: MenuItemRole;
+    /**
+     * Checked state for checkbox/radio roles.
+     */
+    checked?: boolean;
+    /**
+     * Selection callback.
+     */
+    onselect?: (value: unknown, item: MenuItem, controller: MenuController) => void;
+};
+export type MenuHeading = {
+    /**
+     * Entry kind.
+     */
+    type: 'heading';
+    /**
+     * Visible heading.
+     */
+    label: string;
+};
+export type MenuSeparator = {
+    type: 'separator';
+};
+export type MenuEntry = MenuItem | MenuHeading | MenuSeparator | '-';
+/** @typedef {'menuitem'|'menuitemcheckbox'|'menuitemradio'} MenuItemRole */
+/**
+ * @typedef {Object} MenuController
+ * @property {() => unknown} close Close the owning menu.
+ */
+/**
+ * @typedef {Object} MenuItem
+ * @property {string} label Item label.
+ * @property {string} [icon] Kernel icon name.
+ * @property {unknown} [value] Value emitted on selection.
+ * @property {boolean} [disabled=false] Whether selection is disabled.
+ * @property {boolean} [danger=false] Whether the action is dangerous.
+ * @property {string} [href] Native-link destination.
+ * @property {string} [target] Native-link target.
+ * @property {string} [rel] Native-link relationship.
+ * @property {string} [description] Supporting text under the label.
+ * @property {string|number} [badge] Compact trailing metadata.
+ * @property {string} [shortcut] Keyboard shortcut label.
+ * @property {string|number|Node} [adornment] Additional trailing content.
+ * @property {MenuItemRole} [role='menuitem'] APG role.
+ * @property {boolean} [checked=false] Checked state for checkbox/radio roles.
+ * @property {(value: unknown, item: MenuItem, controller: MenuController) => void} [onselect]
+ *   Selection callback.
+ */
+/**
+ * @typedef {Object} MenuHeading
+ * @property {'heading'} type Entry kind.
+ * @property {string} label Visible heading.
+ */
+/** @typedef {{type: 'separator'}} MenuSeparator */
+/** @typedef {MenuItem|MenuHeading|MenuSeparator|'-'} MenuEntry */
+export declare const MENU_ITEM_SELECTOR: string;
+/**
+ * Reports whether an entry is an interactive menu action.
+ * @param {MenuEntry|unknown} entry Candidate entry.
+ * @returns {entry is MenuItem}
+ */
+export declare function isMenuItem(entry: MenuEntry | unknown): entry is MenuItem;
+/**
+ * Resolves the only APG roles accepted by the shared action model.
+ * @param {MenuItem} item Item definition.
+ * @returns {MenuItemRole}
+ */
+export declare function menuItemRole(item: MenuItem): MenuItemRole;
+/**
+ * Builds one menu's entries with shared structure and link safety.
+ * @param {MenuEntry[]} entries Entry definitions.
+ * @param {string} block CSS block name, without the `zx-` prefix.
+ * @returns {HTMLElement[]}
+ */
+export declare function renderMenuEntries(entries: MenuEntry[], block: string): HTMLElement[];