@zeyos/zx 2.2.1 → 3.0.0

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

@@ -4,10 +4,27 @@ export type TableSortDirection = 'asc' | 'desc';
 export type TableSelectionMode = false | 'single' | 'multi';
 export type TableEditMode = false | 'cell' | 'row';
 export type TableEditorType = 'text' | 'number' | 'select' | 'date' | 'checkbox' | 'textarea' | 'custom';
+export type TableColumnType = 'text' | 'number' | 'currency' | 'percent' | 'unit';
 export type TableEditorOption = {
     value: unknown;
     label: string;
 };
+export type TableHierarchyOptions = {
+    /**
+     * Row property or callback returning its
+     * parent row id. Null and undefined identify a root row.
+     */
+    parentId: string | ((row: TableRow) => unknown);
+    /**
+     * Column that receives indentation and the disclosure control; the
+     * first column is used when omitted.
+     */
+    column?: string;
+    /**
+     * Initially expanded branches: all, none, or ids.
+     */
+    expanded?: boolean | unknown[];
+};
 export type TableEditorApi = {
     /**
      * Value the cell holds when the editor opens.
@@ -65,14 +82,37 @@ export type TableColumn = {
      * Header tooltip.
      */
     headerTitle?: string;
+    /**
+     * Built-in display formatter used when `render` is absent.
+     */
+    type?: TableColumnType;
+    /**
+     * BCP 47 formatting locale.
+     */
+    locale?: string | ((row: TableRow) => string | null | undefined);
+    /**
+     * Fraction digits.
+     */
+    decimals?: number | ((row: TableRow) => number | null | undefined);
+    /**
+     * ISO 4217 code used by a
+     * `currency` column.
+     */
+    currency?: string | ((row: TableRow) => string | null | undefined);
+    /**
+     * Suffix used by a `unit`
+     * column. Row callbacks support mixed units in one transaction table.
+     */
+    unit?: string | ((row: TableRow) => string | null | undefined);
     /**
      * While stacked, whether this column becomes a labelled line.
      * `false` keeps it in the card's headline — the identifying columns usually want that.
      */
     popin?: boolean;
     /**
-     * Editor for this column while the table runs with `editMode`. `true` means `'text'`; a function is
-     * evaluated per row so individual rows stay read-only.
+     * Editor for this column while the table runs with `editMode`. `true` infers `'number'` for numeric
+     * display types and `'text'` otherwise; a function is evaluated per row so individual rows stay
+     * read-only.
      */
     editable?: boolean | TableEditorType | ((row: TableRow) => boolean | TableEditorType);
     /**
@@ -177,6 +217,11 @@ export type TableOptions = {
      * inert while this is `false`.
      */
     editMode?: TableEditMode;
+    /**
+     * Flat parent references projected as an
+     * expandable treegrid. Row data and mutation APIs remain flat.
+     */
+    hierarchy?: false | TableHierarchyOptions;
     onrowclick?: (event: CustomEvent<TableRowClickDetail>) => void;
     onrowdblclick?: (event: CustomEvent<TableRowClickDetail>) => void;
     onsort?: (event: CustomEvent<TableSortDetail>) => void;
@@ -201,6 +246,7 @@ export type TableOptions = {
     oneditcommit?: (event: CustomEvent<TableEditCommitDetail>) => void;
     oneditcancel?: (event: CustomEvent<TableEditCancelDetail>) => void;
     oneditinvalid?: (event: CustomEvent<TableEditInvalidDetail>) => void;
+    onrowtoggle?: (event: CustomEvent<TableRowToggleDetail>) => void;
 };
 export type TableRowClickDetail = {
     row: TableRow;
@@ -219,6 +265,35 @@ export type TableSelectionDetail = {
 export type TableDataDetail = {
     rows: TableRow[];
 };
+export type TableRowToggleDetail = {
+    row: TableRow;
+    id: unknown;
+    expanded: boolean;
+};
+export type TableHierarchyEntry = {
+    row: TableRow;
+    id: unknown;
+    /**
+     * Index in the flat input data.
+     */
+    index: number;
+    /**
+     * Zero-based visual depth.
+     */
+    depth: number;
+    hasChildren: boolean;
+    /**
+     * Canonical parent id, or null for a root.
+     */
+    parentId: unknown;
+};
+export type TableHierarchyNode = {
+    row: TableRow;
+    id: unknown;
+    index: number;
+    parent: TableHierarchyNode | null;
+    children: TableHierarchyNode[];
+};
 export type TableEditStartDetail = {
     /**
      * Row being edited.
@@ -363,6 +438,9 @@ export type TableEditorEntry = {
  * @fires Table#editcommit
  * @fires Table#editcancel
  * @fires Table#editinvalid
+ * @fires Table#rowtoggle
+ * @fires Table#stackedchange
+ * @fires Table#grow
  * @extends {Component<TableOptions>}
  */
 export declare class Table extends Component<TableOptions> {
@@ -376,6 +454,11 @@ export declare class Table extends Component<TableOptions> {
         render?: (row: TableRow, rowIndex: number) => Node | string | number | null | undefined;
         sortValue?: (row: TableRow) => unknown;
         headerTitle?: string;
+        type?: TableColumnType;
+        locale?: string | ((row: TableRow) => string | null | undefined);
+        decimals?: number | ((row: TableRow) => number | null | undefined);
+        currency?: string | ((row: TableRow) => string | null | undefined);
+        unit?: string | ((row: TableRow) => string | null | undefined);
         popin?: boolean;
         editable?: boolean | TableEditorType | ((row: TableRow) => boolean | TableEditorType);
         options?: TableEditorOption[] | Record<string, string> | ((row: TableRow) => TableEditorOption[] | Record<string, string>);
@@ -415,6 +498,10 @@ export declare class Table extends Component<TableOptions> {
     };
     _rovingCell: any;
     _rovingMatched: boolean;
+    _hierarchy: TableHierarchyOptions & {
+        column: string;
+    };
+    _expanded: Set<unknown>;
     _table: HTMLElement;
     _colgroup: HTMLElement;
     _thead: HTMLElement;
@@ -422,6 +509,7 @@ export declare class Table extends Component<TableOptions> {
     _scroll: HTMLElement;
     _selectAll: HTMLElement;
     _headers: Map<any, any>;
+    _hierarchyMeta: Map<unknown, TableHierarchyEntry>;
     static cssName: string;
     /** @type {TableOptions} */
     static defaults: TableOptions;
@@ -481,7 +569,10 @@ export declare class Table extends Component<TableOptions> {
      * @returns {TableRow|null} Matching row or null.
      */
     getRow(id: unknown): TableRow | null;
-    /** @returns {TableRow[]} Shallow copy of current rows in display order. */
+    /**
+     * Returns a shallow copy of the current rows in display order.
+     * @returns {TableRow[]} Current table rows.
+     */
     getData(): TableRow[];
     /**
      * Removes all rows.
@@ -504,7 +595,10 @@ export declare class Table extends Component<TableOptions> {
     setSort(id: string, dir?: TableSortDirection, options?: {
         silent?: boolean;
     }): this;
-    /** @returns {TableRow[]} Selected rows in current display order. */
+    /**
+     * Returns selected rows in current display order.
+     * @returns {TableRow[]} Selected rows.
+     */
     getSelection(): TableRow[];
     /**
      * Replaces selected ids, ignoring ids absent from the current data.
@@ -519,6 +613,58 @@ export declare class Table extends Component<TableOptions> {
      * @fires Table#selectionchange
      */
     clearSelection(): this;
+    /**
+     * Toggles one hierarchy branch. A leaf or an id absent from the table is a no-op.
+     * @param {unknown} id Row id.
+     * @param {{silent?: boolean}} [options={}] Event behavior.
+     * @returns {this}
+     * @fires Table#rowtoggle
+     */
+    toggleRow(id: unknown, options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Expands one hierarchy branch.
+     * @param {unknown} id Row id.
+     * @param {{silent?: boolean}} [options={}] Event behavior.
+     * @returns {this}
+     * @fires Table#rowtoggle
+     */
+    expandRow(id: unknown, options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Collapses one hierarchy branch without discarding its descendants or their expansion state.
+     * @param {unknown} id Row id.
+     * @param {{silent?: boolean}} [options={}] Event behavior.
+     * @returns {this}
+     * @fires Table#rowtoggle
+     */
+    collapseRow(id: unknown, options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Expands every row that currently has children.
+     * @param {{silent?: boolean}} [options={}] Event behavior. When not silent, one `rowtoggle`
+     * event is emitted per branch whose state changed.
+     * @returns {this}
+     */
+    expandAll(options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Collapses every hierarchy branch.
+     * @param {{silent?: boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    collapseAll(options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Returns expanded branch ids in current flat-data order.
+     * @returns {unknown[]} Expanded branch ids.
+     */
+    getExpanded(): unknown[];
     /**
      * Opens the editor for a cell. No-op unless the table runs with `editMode` and the column
      * resolves to an editable type for that row. In `'row'` mode every editable cell of the row is
@@ -548,9 +694,15 @@ export declare class Table extends Component<TableOptions> {
      * @fires Table#editcancel
      */
     cancelEdit(): this;
-    /** @returns {boolean} Whether a cell or row is currently open for editing. */
+    /**
+     * Reports whether a cell or row is currently open for editing.
+     * @returns {boolean} Whether an edit is open.
+     */
     isEditing(): boolean;
-    /** @returns {{id: unknown, columnId: string}|null} Row id and focused column id, or null. */
+    /**
+     * Returns the row id and focused column id for the open edit.
+     * @returns {{id: unknown, columnId: string}|null} Editing location, or null.
+     */
     getEditing(): {
         id: unknown;
         columnId: string;
@@ -560,6 +712,10 @@ export declare class Table extends Component<TableOptions> {
      * @returns {TableRow[]}
      */
     _visibleData(): TableRow[];
+    /** @returns {TableHierarchyEntry[]} Rows visible after hierarchy expansion, before growing. */
+    _projectedData(): TableHierarchyEntry[];
+    /** @returns {TableHierarchyEntry[]} Rows that currently have DOM entries. */
+    _visibleEntries(): TableHierarchyEntry[];
     /**
      * Renders the next batch of rows.
      * @param {number} [count] How many to add; defaults to the configured batch size.
@@ -645,17 +801,25 @@ export declare class Table extends Component<TableOptions> {
      * @returns {Node|string}
      */
     _emptyContent(): Node | string;
-    /** @param {TableRow} row @param {number} index @returns {HTMLTableRowElement} */
-    _createRow(row: TableRow, index: number): HTMLTableRowElement;
+    /**
+     * @param {TableRow} row
+     * @param {number} index
+     * @param {TableHierarchyEntry & {visibleIndex: number}} tree
+     * @returns {HTMLTableRowElement}
+     */
+    _createRow(row: TableRow, index: number, tree: TableHierarchyEntry & {
+        visibleIndex: number;
+    }): HTMLTableRowElement;
     /**
      * Fills a cell with the column's rendered value, replacing anything already in it.
      * @param {HTMLTableCellElement} cell Target cell.
      * @param {TableColumn} column Column definition.
      * @param {TableRow} row Row data.
      * @param {number} index Row index.
+     * @param {TableHierarchyEntry} [tree] Hierarchy metadata for the row.
      * @returns {void}
      */
-    _renderCellContent(cell: HTMLTableCellElement, column: TableColumn, row: TableRow, index: number): void;
+    _renderCellContent(cell: HTMLTableCellElement, column: TableColumn, row: TableRow, index: number, tree?: TableHierarchyEntry): void;
     /** @param {MouseEvent} event @returns {void} */
     _handleBodyClick(event: MouseEvent): void;
     /** @param {MouseEvent} event @returns {void} @fires Table#editstart */
@@ -749,11 +913,12 @@ export declare class Table extends Component<TableOptions> {
      * @returns {string}
      */
     _msgOr(key: string, fallback: string): string;
-    /** @param {{row: TableRow, id: unknown, index: number}} meta @param {boolean} checked @param {boolean} shiftKey @returns {void} */
+    /** @param {{row: TableRow, id: unknown, index: number, visibleIndex?: number}} meta @param {boolean} checked @param {boolean} shiftKey @returns {void} */
     _toggleMultiSelection(meta: {
         row: TableRow;
         id: unknown;
         index: number;
+        visibleIndex?: number;
     }, checked: boolean, shiftKey: boolean): void;
     /** @returns {void} */
     _syncSelection(): void;
@@ -763,6 +928,14 @@ export declare class Table extends Component<TableOptions> {
     _syncSortHeader(): void;
     /** @returns {void} */
     _sortData(): void;
+    /** @param {unknown} id @param {boolean} expanded @param {{silent?: boolean}} options @returns {this} */
+    _setRowExpanded(id: unknown, expanded: boolean, options: {
+        silent?: boolean;
+    }): this;
+    /** @param {unknown} id @param {boolean} expanded @returns {void} */
+    _emitRowToggle(id: unknown, expanded: boolean): void;
+    /** Keeps the reader's current expansion state limited to branches still present in the data. */
+    _reconcileExpanded(): void;
     /** @returns {boolean} Whether selection changed. */
     _pruneSelection(): boolean;
     /** @param {TableRow} row @returns {unknown} */
@@ -785,6 +958,9 @@ export declare class Table extends Component<TableOptions> {
 /** @event Table#sort @type {CustomEvent<TableSortDetail>} */
 /** @event Table#selectionchange @type {CustomEvent<TableSelectionDetail>} */
 /** @event Table#datachange @type {CustomEvent<TableDataDetail>} */
+/** @event Table#rowtoggle @type {CustomEvent<TableRowToggleDetail>} */
+/** @event Table#stackedchange @type {CustomEvent<{stacked: boolean}>} */
+/** @event Table#grow @type {CustomEvent<{rendered: number, total: number}>} */
 /**
  * Editor opened for a cell (or, in row mode, for the row).
  * @event Table#editstart
@@ -807,12 +983,43 @@ export declare class Table extends Component<TableOptions> {
  * @event Table#editinvalid
  * @type {CustomEvent<TableEditInvalidDetail>}
  */
+/**
+ * Applies a column's built-in display type. A custom renderer always wins and may still return a
+ * Node; all built-in results are strings so `_renderCellContent` can insert them as text.
+ * @param {TableColumn} column Column definition.
+ * @param {TableRow} row Source row.
+ * @param {number} [index=0] Flat row index.
+ * @returns {Node|string|number|null|undefined} Rendered cell value.
+ */
+export declare function formatTableCell(column: TableColumn, row: TableRow, index?: number): Node | string | number | null | undefined;
+/**
+ * Projects flat parent references into the currently visible stable depth-first order. Orphans
+ * become roots. A cycle is broken at its first source row, so every row is emitted once and the
+ * traversal can never recurse forever.
+ * @param {TableRow[]} rows Flat source rows.
+ * @param {string|((row: TableRow) => unknown)} rowId Row id accessor.
+ * @param {string|((row: TableRow) => unknown)} parentId Parent id accessor.
+ * @param {Set<unknown>|unknown[]} [expanded=[]] Expanded branch ids.
+ * @returns {TableHierarchyEntry[]} Visible hierarchy entries.
+ */
+export declare function projectHierarchyRows(rows: TableRow[], rowId: string | ((row: TableRow) => unknown), parentId: string | ((row: TableRow) => unknown), expanded?: Set<unknown> | unknown[]): TableHierarchyEntry[];
+/**
+ * Sorts roots and each sibling set independently, returning all rows in depth-first order. Parent
+ * and child rows never cross levels merely because their cell values compare differently.
+ * @param {TableRow[]} rows Flat source rows.
+ * @param {string|((row: TableRow) => unknown)} rowId Row id accessor.
+ * @param {string|((row: TableRow) => unknown)} parentId Parent id accessor.
+ * @param {(row: TableRow) => unknown} getValue Sort accessor.
+ * @param {TableSortDirection} direction Sort direction.
+ * @returns {TableRow[]} Sorted flat rows.
+ */
+export declare function sortHierarchyRows(rows: TableRow[], rowId: string | ((row: TableRow) => unknown), parentId: string | ((row: TableRow) => unknown), getValue: (row: TableRow) => unknown, direction: TableSortDirection): TableRow[];
 /**
  * Resolves the editor type of a column for one row.
  *
  * `column.editor` wins over `column.editable`, except that a per-row `editable` function returning
- * `false` still marks the cell read-only. `editable: true` means `'text'`; unknown type names are
- * treated as not editable.
+ * `false` still marks the cell read-only. `editable: true` infers `'number'` for number, currency,
+ * percent, and unit columns and `'text'` otherwise; unknown type names are treated as not editable.
  * @param {TableColumn} column Column definition.
  * @param {TableRow} row Row the cell belongs to.
  * @returns {TableEditorType|false} Editor type, or false when the cell is read-only.

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

@@ -11,7 +11,7 @@ export type TooltipOptions = {
     /**
      * Preferred side; flips when it would overflow.
      */
-    placement?: 'top' | 'bottom' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+    placement?: 'top' | 'bottom' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left' | 'right' | 'left-start' | 'left-end' | 'right-start' | 'right-end';
     /**
      * Gap between anchor and bubble in pixels.
      */
@@ -57,7 +57,7 @@ export type TooltipOptions = {
 /**
  * @typedef {Object} TooltipOptions
  * @property {TooltipContent} [content=''] Bubble content, re-evaluated on each open when a function.
- * @property {'top'|'bottom'|'top-start'|'top-end'|'bottom-start'|'bottom-end'} [placement='top'] Preferred side; flips when it would overflow.
+ * @property {'top'|'bottom'|'top-start'|'top-end'|'bottom-start'|'bottom-end'|'left'|'right'|'left-start'|'left-end'|'right-start'|'right-end'} [placement='top'] Preferred side; flips when it would overflow.
  * @property {number} [offset=6] Gap between anchor and bubble in pixels.
  * @property {number} [delay=400] Delay before a hover opens the tooltip, in milliseconds.
  * @property {number} [hideDelay=80] Delay before a leave or blur closes it, in milliseconds.

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

@@ -24,6 +24,24 @@ export type ValueListOptions = {
      * Value validator.
      */
     validate?: ((value: string) => boolean | string) | null;
+    /**
+     * Values change listener.
+     */
+    onchange?: (event: CustomEvent<{
+        values: string[];
+    }>) => void;
+    /**
+     * Value added listener.
+     */
+    onadd?: (event: CustomEvent<{
+        value: string;
+    }>) => void;
+    /**
+     * Value removed listener.
+     */
+    onremove?: (event: CustomEvent<{
+        value: string;
+    }>) => void;
 };
 /**
  * @typedef {Object} ValueListOptions
@@ -33,6 +51,9 @@ export type ValueListOptions = {
  * @property {boolean} [sortable=true] Whether values can be reordered.
  * @property {boolean} [unique=true] Whether duplicate strings are rejected.
  * @property {((value: string) => boolean|string)|null} [validate=null] Value validator.
+ * @property {(event: CustomEvent<{values: string[]}>) => void} [onchange] Values change listener.
+ * @property {(event: CustomEvent<{value: string}>) => void} [onadd] Value added listener.
+ * @property {(event: CustomEvent<{value: string}>) => void} [onremove] Value removed listener.
  */
 /**
  * Tag/chip editor. It uses the APG listbox/option focus model: each chip is an option, arrow keys
@@ -129,15 +150,15 @@ export declare class ValueList extends Component<ValueListOptions> {
 /**
  * Values changed event.
  * @event ValueList#change
- * @type {CustomEvent<{values: string[]}>
+ * @type {CustomEvent<{values: string[]}>}
  */
 /**
  * Value added event.
  * @event ValueList#add
- * @type {CustomEvent<{value: string}>
+ * @type {CustomEvent<{value: string}>}
  */
 /**
  * Value removed event.
  * @event ValueList#remove
- * @type {CustomEvent<{value: string}>
+ * @type {CustomEvent<{value: string}>}
  */

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

@@ -2,6 +2,7 @@ export type ElementProvider = {
     toElement: () => Node | null;
 };
 export type DomChild = Node | string | number | ElementProvider | null | undefined | Array<DomChild>;
+export type DomBuilderProperties = Record<string, any>;
 export type HProps = {
     /**
      * Class name or names.
@@ -20,6 +21,91 @@ export type HProps = {
      */
     ref?: string;
 };
+export type CompactTag = {
+    /**
+     * Element tag, defaulting to `div`.
+     */
+    tag: string;
+    /**
+     * Element id.
+     */
+    id: string;
+    /**
+     * Space-delimited class string.
+     */
+    className: string;
+};
+/**
+ * @typedef {Object} CompactTag
+ * @property {string} tag Element tag, defaulting to `div`.
+ * @property {string} id Element id.
+ * @property {string} className Space-delimited class string.
+ */
+/**
+ * Parses the compact ZeyOS builder grammar: `tag#id.class names`. The order intentionally matches
+ * the established function—class text begins at the first dot, then id is read from the remaining
+ * tag portion—so thousands of existing call sites retain the same meaning.
+ * @param {string} compact Compact element description.
+ * @returns {CompactTag}
+ */
+export declare function parseCompactTag(compact: string): CompactTag;
+/**
+ * ZeyOS's compact DOM builder, now a first-class Zx primitive. Primitive content is assigned as
+ * text and object content is appended as a Node; HTML strings are never parsed.
+ *
+ * Existing syntax is preserved (`__('button.primary', {Daction: 'save'}, 'Save')`). Zx components
+ * exposing `toElement()` are the one additive extension, so a component may replace a UI factory
+ * without changing the surrounding builder call.
+ * @param {string} compact `tag#id.class names`; an omitted tag creates a `div`.
+ * @param {DomBuilderProperties|null} [properties=null] ZeyOS builder properties.
+ * @param {unknown} [content=null] Text-safe content.
+ * @returns {HTMLElement}
+ */
+export declare function compactElement(compact: string, properties?: DomBuilderProperties | null, content?: unknown): HTMLElement;
+/** Exact migration-facing alias retained for existing ZeyOS builder calls. */
+export declare const __: typeof compactElement;
+/**
+ * Applies the established ZeyOS property rules to an existing element:
+ * `Dname` → `data-name`, `SfontSize` → `style.fontSize`, `on*` → a legacy-compatible listener,
+ * booleans/built-ins → DOM properties, and everything else → attributes.
+ * @param {HTMLElement} element Target element.
+ * @param {DomBuilderProperties} properties Properties to apply.
+ * @returns {HTMLElement} The target, for chaining.
+ */
+export declare function applyCompactProperties(element: HTMLElement, properties: DomBuilderProperties): HTMLElement;
+/**
+ * Appends one child and returns the parent: the pure-function equivalent of `parent._(child)`.
+ * Primitive values become text; a component exposing `toElement()` is accepted additively.
+ * @param {Node} parent Parent node.
+ * @param {unknown} child Child content.
+ * @returns {Node}
+ */
+export declare function appendContent(parent: Node, child: unknown): Node;
+/**
+ * Creates and appends a compact element, returning the parent: the pure equivalent of `parent.__`.
+ * @param {Node} parent Parent node.
+ * @param {string} compact Compact element description.
+ * @param {DomBuilderProperties|null} [properties=null] Builder properties.
+ * @param {unknown} [content=null] Text-safe content.
+ * @returns {Node}
+ */
+export declare function appendCompact(parent: Node, compact: string, properties?: DomBuilderProperties | null, content?: unknown): Node;
+/**
+ * Creates and appends a compact element, returning the child: the pure equivalent of `parent.$__`.
+ * @param {Node} parent Parent node.
+ * @param {string} compact Compact element description.
+ * @param {DomBuilderProperties|null} [properties=null] Builder properties.
+ * @param {unknown} [content=null] Text-safe content.
+ * @returns {HTMLElement}
+ */
+export declare function appendCompactChild(parent: Node, compact: string, properties?: DomBuilderProperties | null, content?: unknown): HTMLElement;
+/**
+ * Creates a document fragment with normalized modern Zx children. Unlike the exact compact
+ * builder, this convenience accepts arrays and flattens them like `h()`.
+ * @param {...(DomChild|boolean)} children Fragment children.
+ * @returns {DocumentFragment}
+ */
+export declare function fragment(...children: (DomChild | boolean)[]): DocumentFragment;
 /**
  * Creates an element and appends normalized children.
  * @param {string} tag Element tag name.
@@ -84,3 +170,31 @@ export declare function highlightMatch(text: unknown, query: unknown, options?:
  * @returns {Element|null}
  */
 export declare function resolveElement(target: Element | string | ElementProvider | null | undefined): Element | null;
+/**
+ * Registers an event with the established ZeyOS callback contract: handlers run newest-first,
+ * receive `(event, event.target)` (or the key code for keyboard events), and may return false to
+ * prevent the default action. This exported registry is shared by compact properties, removal,
+ * and synthetic firing so the legacy `DOM` facade can delegate all three operations to it.
+ * @param {EventTarget} target Event target.
+ * @param {string} type Event name.
+ * @param {Function} handler Listener.
+ * @param {boolean} [passive=false] Native passive-listener hint.
+ * @returns {EventTarget}
+ */
+export declare function onCompactEvent(target: EventTarget, type: string, handler: Function, passive?: boolean): EventTarget;
+/**
+ * Removes one registered handler, matching the established duplicate-registration behavior.
+ * @param {EventTarget} target Event target.
+ * @param {string} type Event name.
+ * @param {Function} handler Handler to remove.
+ * @returns {EventTarget}
+ */
+export declare function offCompactEvent(target: EventTarget, type: string, handler: Function): EventTarget;
+/**
+ * Invokes compact handlers without dispatching unrelated native listeners.
+ * @param {EventTarget} target Event target.
+ * @param {string} type Event name.
+ * @param {Event|Record<string, any>|null} [event=null] Event-like object.
+ * @returns {EventTarget}
+ */
+export declare function fireCompactEvent(target: EventTarget, type: string, event?: Event | Record<string, any> | null): EventTarget;