@guiexpert/table 1.1.96 → 1.1.98

package/lib/table/aria/aria-ids.d.ts

@@ -47,6 +47,13 @@ export declare class AriaIds {
      * @returns {string} e.g. `"ge-t1-rg-body-center"`
      */
     rowGroup(area: AreaIdent, side: SideIdent): string;
+    /**
+     * The ID of the row group of the detail rows (master/detail), referenced by `aria-owns` of the host.
+     *
+     * @returns {string} e.g. `"ge-t1-rg-detail"`
+     * @since 1.1.97
+     */
+    detailRowGroup(): string;
     /**
      * The ID of the live region (the element that speaks announcements, see {@link LiveAnnouncer}).
      *

package/lib/table/aria/aria-texts.d.ts

@@ -36,6 +36,8 @@ export declare class AriaTexts implements AriaTextsIf {
     rowMoveNotPossible(): string;
     rowDragCancelled(): string;
     cellsFilled(cellCount: number): string;
+    detailExpanded(): string;
+    detailCollapsed(): string;
     fillTooLarge(maxCells: number): string;
     pendingChanges(pendingCount: number): string;
     changesCommitted(cellCount: number): string;

package/lib/table/aria/aria-texts.if.d.ts

@@ -172,4 +172,18 @@ export interface AriaTextsIf {
      * @since 1.1.96
      */
     invalidValue?(message: string): string;
+    /**
+     * Announced after a detail row was expanded (master/detail).
+     *
+     * @returns {string} default: `"Details expanded"`
+     * @since 1.1.97
+     */
+    detailExpanded?(): string;
+    /**
+     * Announced after a detail row was collapsed (master/detail).
+     *
+     * @returns {string} default: `"Details collapsed"`
+     * @since 1.1.97
+     */
+    detailCollapsed?(): string;
 }

package/lib/table/crud/crud-object-edit.d.ts

@@ -17,6 +17,8 @@
 export declare class CrudObjectEdit<T extends Record<string, any>> {
     private idKey;
     dialogTitle: string;
+    /** Writing direction of the dialog (`dir`) – the CRUD factory sets the direction of the table. @since 1.1.98 */
+    direction?: "ltr" | "rtl";
     private object;
     /** Property path of every input (index = `data-field-index`) – a key may contain a dot itself. */
     private fieldPaths;

package/lib/table/crud/crud-object-view.d.ts

@@ -5,6 +5,8 @@
  * @category CRUD
  */
 export declare class CrudObjectView<T extends Record<string, any>> {
+    /** Writing direction of the dialog (`dir`) – the CRUD factory sets the direction of the table. @since 1.1.98 */
+    direction?: "ltr" | "rtl";
     private object;
     constructor(obj: T);
     openDialog(): void;

package/lib/table/crud/crud-table-model-factory.d.ts

@@ -59,6 +59,8 @@ export declare class CrudTableModelFactory implements ActionEventListenerIf {
      * While a request runs, the table shows its loading overlay ({@link TableApi.showLoadingOverlay}, since 1.1.92).
      * A failed request is logged with `console.error`; the table stays unchanged.
      */
+    /** The dialogs live outside the host: they get the writing direction of the table (since 1.1.98). */
+    private withDirection;
     onActionEvent(actionEvent: ActionEventIf): void;
     /** `createItem` without the id property (the server assigns it), then shows the new row. */
     private createItem;

package/lib/table/data/common/event/ge-detail-event.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What opened or closed a detail row: a click on the icon (`"mouse"`), Enter (`"keyboard"`), the {@link TableApi}
+ * (`"api"`) or a restored table state (`"state"`).
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export type GeDetailEventSource = "mouse" | "keyboard" | "api" | "state";
+/**
+ * Reported by {@link EventListenerIf.onDetailExpandedChanged}: a detail row was expanded or collapsed (master/detail,
+ * {@link MasterDetailOptionsIf}).
+ *
+ * @example
+ * const listener = new EventAdapter();
+ * listener.onDetailExpandedChanged = (evt: GeDetailEvent) => {
+ *   console.log(`order ${evt.row.id} ${evt.expanded ? "opened" : "closed"} (${evt.source})`);
+ * };
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export declare class GeDetailEvent<T = any> {
+    /** The master row. */
+    readonly row: T;
+    /** Its display index (`-1` if it is not shown, e.g. filtered out). */
+    readonly rowIndex: number;
+    /** `true` = expanded, `false` = collapsed. */
+    readonly expanded: boolean;
+    /** What changed it. */
+    readonly source: GeDetailEventSource;
+    constructor(
+    /** The master row. */
+    row: T, 
+    /** Its display index (`-1` if it is not shown, e.g. filtered out). */
+    rowIndex: number, 
+    /** `true` = expanded, `false` = collapsed. */
+    expanded: boolean, 
+    /** What changed it. */
+    source: GeDetailEventSource);
+}

package/lib/table/data/options/auto-restore-options.d.ts

@@ -44,6 +44,8 @@ export declare class AutoRestoreOptions<T> implements AutoRestoreOptionsIf<T> {
     autoRestoreHeaderGroupState: boolean;
     /** @since 1.1.92 */
     autoRestoreCustomState: boolean;
+    /** @since 1.1.97 */
+    autoRestoreDetailState: boolean;
     getStorageKeyFn: undefined;
     /** @deprecated since 1.1.92 – never used by the table. */
     isSame: (r1: T, r2: T, options: AutoRestoreOptionsIf<T>) => boolean;

package/lib/table/data/options/auto-restore-options.if.d.ts

@@ -51,6 +51,7 @@ export type GetStorageKeyFn = (() => string);
  * | {@link autoRestoreCheckedState} | checked rows | 1.1.92 (declared before, without effect) |
  * | {@link autoRestoreSelectedState} | selection | 1.1.92 (declared before, without effect) |
  * | {@link autoRestoreCustomState} | your data ({@link TableApi.setCustomState}) | 1.1.92 |
+ * | {@link autoRestoreDetailState} | expanded detail rows (master/detail) | 1.1.97 |
  *
  * Before 1.1.92 sorting, scroll position and tree were stored under three keys (`<key>sortingState`,
  * `<key>scrollState`, `<key>collapsedExpandedState`); they are read once and removed with the next save.
@@ -103,6 +104,11 @@ export interface AutoRestoreOptionsIf<T> {
      * @since 1.1.92
      */
     autoRestoreCustomState?: boolean;
+    /**
+     * Remember the expanded detail rows of master/detail ({@link TableOptionsIf.masterDetail}, by {@link getRowId}).
+     * @since 1.1.97
+     */
+    autoRestoreDetailState?: boolean;
     /**
      * A unique, stable id per row (tree: per node). With the default of {@link AutoRestoreOptions} the table uses the
      * property `id`, then `uuid`; rows without them are not stored (since 1.1.92 – the JSON of the row would write

package/lib/table/data/options/table-options.d.ts

@@ -1,3 +1,5 @@
+import { TableDirection } from '../../rtl/table-direction.type.js';
+import { MasterDetailOptionsIf } from '../../master-detail/master-detail-options.if.js';
 import { DefaultRowHeightsIf } from './default-row-heights.if.js';
 import { TableOptionsIf } from './table-options.if.js';
 import { TreeOptions } from './tree-options.js';
@@ -85,5 +87,11 @@ export declare class TableOptions implements TableOptionsIf {
     overlayOptions?: Partial<OverlayOptionsIf>;
     rowDragOptions?: Partial<RowDragOptionsIf>;
     fillHandle?: boolean | Partial<FillHandleOptionsIf>;
+    masterDetail?: Partial<MasterDetailOptionsIf>;
     batchEdit?: boolean | Partial<BatchEditOptionsIf>;
+    /**
+     * Writing direction (`"ltr"` | `"rtl"` | `"auto"`). Not set = `"ltr"`; a nested table (master/detail) without its
+     * own value takes the direction of the outer table. @since 1.1.98
+     */
+    direction?: TableDirection;
 }

package/lib/table/data/options/table-options.if.d.ts

@@ -1,3 +1,4 @@
+import { MasterDetailOptionsIf } from '../../master-detail/master-detail-options.if.js';
 import { RowDragOptionsIf } from '../../row-drag/row-drag-options.if.js';
 import { FillHandleOptionsIf } from '../../fill/fill-handle-options.if.js';
 import { BatchEditOptionsIf } from '../../batch-edit/batch-edit-options.if.js';
@@ -16,6 +17,7 @@ import { HeaderGroupOptionsIf } from './header-group-options.if.js';
 import { AriaTextsIf } from '../../aria/aria-texts.if.js';
 import { TableStateIf } from '../../state/table-state.if.js';
 import { OverlayOptionsIf } from './overlay-options.if.js';
+import { TableDirection } from '../../rtl/table-direction.type.js';
 
 /**
  * Represents the options for configuring a table.
@@ -361,6 +363,39 @@ export interface TableOptionsIf {
      * @since 1.1.96
      */
     batchEdit?: boolean | Partial<BatchEditOptionsIf>;
+    /**
+     * Master/detail: master rows get an expand icon; below an expanded row a detail row over the full width shows any
+     * content (a nested table, a form, a framework component – see {@link MasterDetailOptionsIf}). Only for flat body
+     * models. Fields you leave out keep their default ({@link MasterDetailOptions}); `detailRenderer` is required.
+     *
+     * @example
+     * const tableOptions: TableOptionsIf = {
+     *   ...new TableOptions(),
+     *   masterDetail: {
+     *     detailHeight: "auto",
+     *     detailRenderer: (container, row) => { container.textContent = `Notes: ${row.notes}`; }
+     *   }
+     * };
+     *
+     * @since 1.1.97
+     */
+    masterDetail?: Partial<MasterDetailOptionsIf>;
+    /**
+     * Writing direction: `"ltr"` (default), `"rtl"` for Arabic, Hebrew, Persian, Urdu … (first column on the right,
+     * horizontal scrolling, fixed columns, tree indent, resize handles and arrow keys mirrored) or `"auto"` (the
+     * direction of the page: `dir="rtl"` on `<html>` or a parent element). Read once when the table is built – a new
+     * options object rebuilds the table in the wrappers.
+     *
+     * In right-to-left, the "left" and "right" in names of the API mean **start** and **end**:
+     * `fixedLeftColumnCount` fixes columns at the start (right), `fixedRightColumnCount` at the end (left),
+     * `ge-table-text-align-left` aligns to the start. The table sets `dir` on its host element (also `dir="ltr"`).
+     *
+     * @example
+     * const tableOptions: TableOptionsIf = { ...new TableOptions(), direction: "rtl" };
+     *
+     * @since 1.1.98
+     */
+    direction?: TableDirection;
     /**
      * The state the table starts with: column layout, sorting, tree, checked and selected rows … – e.g. loaded from
      * your server ({@link TableApi.getState}, {@link EventListenerIf.onStateChanged}). A state stored by

package/lib/table/ele-scope.d.ts

@@ -7,6 +7,7 @@ import { AriaIds } from './aria/aria-ids.js';
 import { AreaIdent } from './data/tablemodel/area-ident.type.js';
 import { SideIdent } from './data/side-ident.type.js';
 import { TableOverlay } from './overlay/table-overlay.js';
+import { ResolvedTableDirection } from './rtl/table-direction.type.js';
 
 /**
  * Represents a store for HTML elements.
@@ -53,7 +54,43 @@ export declare class EleScope {
     readonly ariaIds: AriaIds;
     /** The overlay layer over the body ("Loading…", "No rows to show"). @since 1.1.92 */
     readonly tableOverlay: TableOverlay;
+    /**
+     * The resolved writing direction of the table ({@link TableOptionsIf.direction}; `"auto"` is decided when the table
+     * is built). @since 1.1.98
+     */
+    readonly direction: ResolvedTableDirection;
     constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, dom: ConvenienceDomService, tableOptions: TableOptionsIf);
+    /**
+     * Whether the table runs from right to left ({@link TableOptionsIf.direction}).
+     *
+     * @returns {boolean} true for `"rtl"` (also a resolved `"auto"`)
+     * @since 1.1.98
+     */
+    isRtl(): boolean;
+    /**
+     * The horizontal scroll position of the body as distance from the **start** (≥ 0) – `scrollLeft`, in
+     * right-to-left `-scrollLeft`.
+     *
+     * @returns {number} px
+     * @since 1.1.98
+     */
+    getViewportScrollLeft(): number;
+    /**
+     * Sets the horizontal scroll position of the body as distance from the **start** (see {@link getViewportScrollLeft}).
+     *
+     * @param {number} x - px from the start
+     * @since 1.1.98
+     */
+    setViewportScrollLeft(x: number): void;
+    /**
+     * A client x coordinate (e.g. `PointerEvent.clientX`) as x in the host from the start of its padding box – the
+     * coordinates in which the table positions everything (right-to-left: from the right edge).
+     *
+     * @param {number} clientX - x in client (viewport) coordinates
+     * @returns {number} px from the start
+     * @since 1.1.98
+     */
+    clientXToHostX(clientX: number): number;
     /**
      * Shows the overlay that fits the current state (requested by the API, or "no rows" for an empty body).
      * Overwritten in {@link RenderScope}.
@@ -98,6 +135,12 @@ export declare class EleScope {
      * @return {void}
      */
     adjustContainersAndRows(): void;
+    /**
+     * Position and size of the detail layer (master/detail) in the host – overwritten in {@link RenderScope}.
+     *
+     * @since 1.1.97
+     */
+    protected adjustDetailLayerBounds(_left: number, _top: number, _width: number, _height: number): void;
     /**
      * Adjusts the position or appearance of elements after scrolling.
      * This method must be overwritten in child classes.
@@ -105,6 +148,14 @@ export declare class EleScope {
      * @return {void}
      */
     adjustAfterScrolling(): void;
+    /**
+     * The height of all body rows in px – the model's content height plus, in {@link RenderScope}, the heights of open
+     * detail rows (master/detail).
+     *
+     * @returns {number} px
+     * @since 1.1.97
+     */
+    protected getBodyContentHeight(): number;
     /**
      * Resets the size of the wrapper div based on the content dimensions.
      *

package/lib/table/event-adapter.d.ts

@@ -1,3 +1,4 @@
+import { GeDetailEvent } from './data/common/event/ge-detail-event.js';
 import { GeModelChangeEvent } from './data/common/event/ge-model-change-event.js';
 import { GeMouseEvent } from './data/common/event/ge-mouse-event.js';
 import { GeScrollEvent } from './data/common/event/ge-scroll-event.js';
@@ -40,4 +41,6 @@ export declare class EventAdapter implements EventListenerIf {
     onRowDragEnd(_evt: GeRowDragEvent): void;
     /** @since 1.1.96 */
     onBatchEditChanged(_evt: GeBatchEditEvent): void;
+    /** @since 1.1.97 */
+    onDetailExpandedChanged(_evt: GeDetailEvent): void;
 }

package/lib/table/event-listener.if.d.ts

@@ -1,3 +1,4 @@
+import { GeDetailEvent } from './data/common/event/ge-detail-event.js';
 import { GeMouseEvent } from './data/common/event/ge-mouse-event.js';
 import { GeModelChangeEvent } from './data/common/event/ge-model-change-event.js';
 import { GeScrollEvent } from './data/common/event/ge-scroll-event.js';
@@ -95,4 +96,10 @@ export interface EventListenerIf extends EventFocusChangedListenerIf, EventSelec
      * @since 1.1.96
      */
     onBatchEditChanged?(evt: GeBatchEditEvent): void;
+    /**
+     * A detail row was expanded or collapsed (master/detail, {@link TableOptionsIf.masterDetail}).
+     *
+     * @since 1.1.97
+     */
+    onDetailExpandedChanged?(evt: GeDetailEvent): void;
 }

package/lib/table/master-detail/detail-renderer.if.d.ts

@@ -0,0 +1,99 @@
+import { TableApi } from '../table-api.js';
+import { TableModelIf } from '../data/tablemodel/table-model.if.js';
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { EventListenerIf } from '../event-listener.if.js';
+
+/**
+ * What {@link DetailRenderContextIf.createTable} needs for a nested table in a detail row.
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export interface DetailTableParamsIf {
+    /** The model of the nested table, e.g. `TableFactory.createTableModel({ rows: order.items, properties: [...] })`. */
+    tableModel: TableModelIf;
+    /** Its options (default: `new TableOptions()`). */
+    tableOptions?: TableOptionsIf;
+    /** Its event listener (default: none). */
+    eventListener?: EventListenerIf;
+    /**
+     * The height of the nested table: px or a CSS length. Default: `"100%"` with a fixed
+     * {@link MasterDetailOptionsIf.detailHeight}, otherwise {@link MasterDetailOptionsIf.estimatedDetailHeight} px.
+     */
+    height?: number | string;
+}
+/**
+ * The context a {@link DetailRendererIf} gets: the master row, the outer table and helpers whose resources are released
+ * together with the detail row.
+ *
+ * @example
+ * const renderDetail: DetailRenderFnType<Order> = (container, order, ctx) => {
+ *   const button = document.createElement("button");
+ *   button.textContent = `Open order ${order.id}`;
+ *   button.addEventListener("click", () => ctx.tableApi.announce(`Order ${order.id}`), { signal: ctx.signal });
+ *   container.appendChild(button);
+ * };
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export interface DetailRenderContextIf<T = any> {
+    /** The master row (the row object of the body model). */
+    readonly row: T;
+    /** The display index of the master row when the detail was created (it changes with sorting and filtering). */
+    readonly rowIndex: number;
+    /** The API of the outer (master) table. */
+    readonly tableApi: TableApi;
+    /**
+     * `true` if the content of this detail row existed before and was destroyed (too many rendered details, see
+     * {@link MasterDetailOptionsIf.maxRenderedDetails}, or {@link TableApi.refreshDetail}) – state that lives only in the
+     * DOM (inputs, scroll positions) is gone then.
+     */
+    readonly recreated: boolean;
+    /** Aborted when the detail row is destroyed – pass it to `addEventListener(…, { signal })`. */
+    readonly signal: AbortSignal;
+    /**
+     * Creates a GuiExpert table inside the detail row; it is destroyed (`TableScope.destroy()`) together with the detail
+     * row. The CSS variables of the page (light/dark theme) apply to it as well.
+     *
+     * @param {DetailTableParamsIf} params - model, options, listener, height
+     * @returns {TableApi} the API of the nested table
+     */
+    createTable(params: DetailTableParamsIf): TableApi;
+}
+/**
+ * Renders the content of a detail row – a function (see {@link DetailRendererIf}). It may return a cleanup function,
+ * called when the detail row is destroyed (collapsed, too many rendered details, new table model).
+ *
+ * @example
+ * const renderDetail: DetailRenderFnType<Order> = (container, order) => {
+ *   container.textContent = `${order.items.length} items, ordered on ${order.date}`;  // textContent: no HTML injection
+ * };
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export type DetailRenderFnType<T = any> = (container: HTMLDivElement, row: T, context: DetailRenderContextIf<T>) => (() => void) | void;
+/**
+ * Renders the content of a detail row – the object form of {@link DetailRenderFnType}, e.g. the
+ * `DetailComponentRendererWrapper` of the framework wrappers (React, Vue, Svelte …).
+ *
+ * The content is created once, when the detail row becomes visible for the first time, and lives until the row is
+ * collapsed – scrolling only hides and shows it (inputs, selections and scroll positions stay).
+ *
+ * @example
+ * class OrderNotesRenderer implements DetailRendererIf<Order> {
+ *   render(container: HTMLDivElement, order: Order): () => void {
+ *     const textarea = document.createElement("textarea");
+ *     textarea.value = order.notes ?? "";
+ *     container.appendChild(textarea);
+ *     return () => { order.notes = textarea.value; };   // cleanup: keep the text
+ *   }
+ * }
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export interface DetailRendererIf<T = any> {
+    render(container: HTMLDivElement, row: T, context: DetailRenderContextIf<T>): (() => void) | void;
+}

package/lib/table/master-detail/master-detail-options.d.ts

@@ -0,0 +1,30 @@
+import { DetailHeightType, MasterDetailOptionsIf } from './master-detail-options.if.js';
+import { DetailRendererIf, DetailRenderFnType } from './detail-renderer.if.js';
+
+/**
+ * The defaults of {@link MasterDetailOptionsIf}.
+ *
+ * @example
+ * const options = MasterDetailOptions.create({ detailRenderer: (el, row) => { el.textContent = String(row.id); } });
+ * options.detailHeight;          // "auto"
+ * options.maxRenderedDetails;    // 50
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export declare class MasterDetailOptions<T = any> implements MasterDetailOptionsIf<T> {
+    detailRenderer: DetailRendererIf<T> | DetailRenderFnType<T>;
+    isMaster?: (row: T, rowIndex: number) => boolean;
+    detailHeight: DetailHeightType | ((row: T, rowIndex: number) => DetailHeightType);
+    estimatedDetailHeight: number;
+    toggleColumn?: number | string;
+    maxRenderedDetails: number;
+    getRowId?: (row: T) => string | number;
+    /**
+     * The defaults, overridden by the given values (`undefined` keeps the default).
+     *
+     * @param {Partial<MasterDetailOptionsIf>} [options] - e.g. `tableOptions.masterDetail`
+     * @returns {MasterDetailOptionsIf} complete options
+     */
+    static create<T = any>(options?: Partial<MasterDetailOptionsIf<T>>): MasterDetailOptionsIf<T>;
+}

package/lib/table/master-detail/master-detail-options.if.d.ts

@@ -0,0 +1,60 @@
+import { DetailRendererIf, DetailRenderFnType } from './detail-renderer.if.js';
+
+/**
+ * The height of a detail row: px, or `"auto"` = measured from its content (a `ResizeObserver` follows changes).
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export type DetailHeightType = number | "auto";
+/**
+ * Master/detail: a master row can be expanded; below it a detail row over the full width of the table (fixed columns
+ * included) shows any content – a nested GuiExpert table, a form, a chart, a framework component. Works with virtual
+ * scrolling and millions of rows: the content is created when the detail row becomes visible and lives until it is
+ * collapsed (scrolling only hides and shows it). Only for flat body models (not for trees, row groups and pivot tables).
+ *
+ * Fields you leave out keep their default ({@link MasterDetailOptions}).
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   masterDetail: {
+ *     detailHeight: 180,
+ *     detailRenderer: (_container, order: Order, ctx) => {
+ *       ctx.createTable({
+ *         tableModel: TableFactory.createTableModel({ rows: order.items, properties: ["sku", "name", "qty", "price"] })
+ *       });
+ *     }
+ *   }
+ * };
+ *
+ * @see Training: [Master/detail](https://gui.expert/training/master-detail/)
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export interface MasterDetailOptionsIf<T = any> {
+    /** Renders the content of a detail row (function or object with `render()`). */
+    detailRenderer: DetailRendererIf<T> | DetailRenderFnType<T>;
+    /** Which rows can be expanded. Default: every row. */
+    isMaster?: (row: T, rowIndex: number) => boolean;
+    /** Height of the detail rows: px, `"auto"` (measured) or a function per row. Default `"auto"`. */
+    detailHeight: DetailHeightType | ((row: T, rowIndex: number) => DetailHeightType);
+    /** Height of an `"auto"` detail row before its content was measured (px). Default 200. */
+    estimatedDetailHeight: number;
+    /**
+     * The column with the expand/collapse icon: column index or property. Default: the first data column (behind a row
+     * number and a row checkbox column – where a tree has its arrow).
+     */
+    toggleColumn?: number | string;
+    /**
+     * At most this many detail contents exist at the same time. Beyond it the detail row that was out of view the
+     * longest is destroyed and created again when it scrolls back into view (`context.recreated`). Default 50.
+     */
+    maxRenderedDetails: number;
+    /**
+     * The id of a master row – keeps detail rows open when the rows are replaced by new objects with the same ids
+     * (`setRows`). Default: `autoRestoreOptions.getRowId`, otherwise the row object itself.
+     */
+    getRowId?: (row: T) => string | number;
+}