@guiexpert/table 1.1.94 → 1.1.97

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;
+}

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

@@ -0,0 +1,223 @@
+import { TableScope } from '../table-scope.js';
+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';
+import { GeDetailEventSource } from '../data/common/event/ge-detail-event.js';
+import { MasterDetailOptionsIf } from './master-detail-options.if.js';
+
+/**
+ * The part of a nested table the master/detail service needs (a {@link TableScope}).
+ *
+ * @category Internals
+ * @since 1.1.97
+ */
+export interface NestedTableScopeIf {
+    firstInit(): unknown;
+    getApi(): TableApi;
+    destroy(): void;
+}
+/**
+ * Creates the {@link TableScope} of a nested table (given by `TableScope` – no import cycle).
+ *
+ * @category Internals
+ * @since 1.1.97
+ */
+export type NestedTableScopeFactory = (host: HTMLDivElement, tableModel: TableModelIf, tableOptions: TableOptionsIf | undefined, eventListener: EventListenerIf | undefined) => NestedTableScopeIf;
+/**
+ * Master/detail of a table ({@link TableOptionsIf.masterDetail}): the expanded master rows, the detail layer and the
+ * life cycle of the detail contents. Created by {@link TableScope} (`tableScope.masterDetailService`); use the
+ * {@link TableApi} (`setDetailExpanded`, `toggleDetail` …).
+ *
+ * - **Layer**: one div `ge-table-detail-layer` in the host, over the body (full width, fixed columns included, without
+ *   the scroll bars). It is never cleared by the virtual rendering and does not scroll horizontally.
+ * - **Positions**: the heights of the detail rows are extras of the body {@link RowLayout} (behind their master row);
+ *   `RenderScope` reports the detail rows in view after every render pass ({@link layoutVisible}).
+ * - **Life cycle**: the content is created when the detail row becomes visible, hidden (not destroyed) when it scrolls
+ *   out of view, destroyed when it is collapsed, beyond `maxRenderedDetails` or when the table is destroyed.
+ * - **Events**: mouse, keyboard and pointer events from a detail row are ignored by the outer table
+ *   ({@link isInLayer}); the mouse wheel over a detail row scrolls the outer table when nothing in the detail scrolls.
+ *
+ * @category Internals
+ * @since 1.1.97
+ */
+export declare class MasterDetailService {
+    private readonly scope;
+    private readonly createNestedScope;
+    /** The complete options (defaults + `tableOptions.masterDetail`). */
+    readonly options: MasterDetailOptionsIf;
+    private readonly active;
+    private layer?;
+    private readonly entries;
+    private byIndex;
+    private visibleNow;
+    private renderPass;
+    private renderedCount;
+    private toggleColumnIndex;
+    private resizeFrame;
+    private destroyed;
+    constructor(scope: TableScope, createNestedScope: NestedTableScopeFactory);
+    /** True if master/detail is configured (and the body is flat). */
+    isActive(): boolean;
+    /** True if at least one master row is expanded. */
+    hasExpanded(): boolean;
+    /** The detail layer (`undefined` without master/detail). */
+    getLayer(): HTMLDivElement | undefined;
+    /**
+     * True if an event comes from a detail row (or a nested table in it) – the outer table ignores it.
+     *
+     * @param {Event} evt - a DOM event while it is dispatched
+     * @returns {boolean} whether its path contains the detail layer
+     */
+    isInLayer(evt: Event): boolean;
+    /** The id of a master row: `options.getRowId`, `autoRestoreOptions.getRowId`, the row object or its index. */
+    keyOf(row: unknown, rowIndex: number): unknown;
+    /**
+     * True if the row at a display index can be expanded ({@link MasterDetailOptionsIf.isMaster}).
+     *
+     * @param {number} rowIndex - display index
+     * @returns {boolean} whether it is a master row
+     */
+    isMasterAt(rowIndex: number): boolean;
+    /**
+     * True if the master row at a display index is expanded.
+     *
+     * @param {number} rowIndex - display index
+     * @returns {boolean} whether its detail row is open
+     */
+    isExpandedAt(rowIndex: number): boolean;
+    /**
+     * True if a row (display index or row object) is expanded.
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} whether its detail row is open
+     */
+    isExpanded(rowOrIndex: unknown): boolean;
+    /**
+     * Expands or collapses a master row. The table repaints and reports the change ({@link TableScope}).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @param {boolean} expanded - the new state
+     * @param {GeDetailEventSource} [source] - what changed it (for the event)
+     * @returns {boolean} false if nothing changed (no master row, already in that state, no master/detail)
+     */
+    setExpanded(rowOrIndex: unknown, expanded: boolean, source?: GeDetailEventSource): boolean;
+    /**
+     * Expands all master rows that are shown (their contents are created only when they scroll into view).
+     * No event per row.
+     *
+     * @returns {number} the number of rows that were expanded
+     */
+    expandAll(): number;
+    /**
+     * Collapses all detail rows (their contents are destroyed). No event per row.
+     *
+     * @returns {number} the number of rows that were collapsed
+     */
+    collapseAll(): number;
+    /** The expanded master rows (row objects; for models without row objects: `undefined`). */
+    getExpandedRows(): unknown[];
+    /**
+     * Expands exactly these rows and collapses all others – the restore of the table state. Rows that are no master
+     * rows are skipped. No event per row.
+     *
+     * @param {unknown[]} rows - row objects of the body model
+     * @param {GeDetailEventSource} [source] - what changed it
+     * @returns {boolean} true if something changed
+     */
+    setExpandedRows(rows: readonly unknown[], source?: GeDetailEventSource): boolean;
+    /**
+     * Destroys the content of a detail row and creates it again (e.g. after the row's data changed).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} false if the row is not expanded
+     */
+    refresh(rowOrIndex: unknown): boolean;
+    /**
+     * The container of a detail row (the element `detailRenderer` renders into) – only while its content exists.
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {HTMLDivElement | undefined} the container
+     */
+    getDetailElement(rowOrIndex: unknown): HTMLDivElement | undefined;
+    /**
+     * The display index of the master row a DOM node belongs to (a detail row or something in it).
+     *
+     * @param {Node} node - a node in the detail layer
+     * @returns {number} the display index, -1 if none
+     */
+    getMasterRowIndexOf(node: Node | null): number;
+    /**
+     * The display indices and heights of the expanded master rows that are shown – the extras of the body row layout.
+     * Called by `RenderScope` when the row layout is built (after filtering, sorting, editing, a detail toggle …): one
+     * pass over the shown rows. Removes expanded rows that no longer exist in the model (`getAllRows()`).
+     *
+     * @returns {{ rowIndices: number[], heights: number[] } | undefined} the extras, `undefined` without expanded rows
+     */
+    computeExtras(): {
+        rowIndices: number[];
+        heights: number[];
+    } | undefined;
+    /**
+     * Called at the start of the body render pass: the column of the expand icon.
+     */
+    startRenderPass(): void;
+    /**
+     * Shows the detail rows in view (called by `RenderScope` after the body rows were rendered): creates missing
+     * contents, sets their positions, hides the ones that left the view and destroys the oldest hidden contents beyond
+     * {@link MasterDetailOptionsIf.maxRenderedDetails}.
+     *
+     * @param {number[]} triples - `rowIndex, top, height` of each detail row in view; `top` relative to the body top
+     */
+    layoutVisible(triples: number[]): void;
+    /**
+     * Position and size of the layer: the visible body including the fixed columns, without the scroll bars.
+     *
+     * @param {number} left - px in the host
+     * @param {number} top - px in the host (below the header)
+     * @param {number} width - px
+     * @param {number} height - px
+     */
+    setBounds(left: number, top: number, width: number, height: number): void;
+    /**
+     * Decorates a body cell of the toggle column of a master row with the expand icon (`ge-table-detail-toggle`).
+     *
+     * @param {HTMLDivElement} cell - the rendered cell
+     * @param {number} rowIndex - display index
+     * @param {number} columnIndex - model column index
+     */
+    decorateCell(cell: HTMLDivElement, rowIndex: number, columnIndex: number): void;
+    /**
+     * Called when the table is destroyed: destroys all detail contents and removes the layer.
+     */
+    destroy(): void;
+    private getBody;
+    private getAllRows;
+    /** isMaster for a row that is not shown (filtered out) – the index is unknown (-1). */
+    private isMasterRow;
+    /** `[row, rowIndex]` of a display index or a row object (index -1 if the row is not shown). */
+    private resolve;
+    private heightOf;
+    private detailHeightOf;
+    private computeToggleColumnIndex;
+    private pruneRemovedRows;
+    private createLayer;
+    private createContent;
+    private createNestedTable;
+    private place;
+    private park;
+    /** The focus is inside a detail row that is hidden or removed: the master table (row) takes it. */
+    private releaseFocus;
+    private onResize;
+    private enforceLimit;
+    private destroyContent;
+    private clearAll;
+    /** The mouse wheel over a detail row: scrolls the outer table if nothing in the detail row takes the movement. */
+    private onWheel;
+    private canScrollInside;
+    /** Tab on a master row with an open detail row: the focus moves to the first focusable element in it. */
+    private onHostKeyDown;
+    /** The host got the focus back from a detail row (Shift+Tab): its master row gets the focus. */
+    private onHostFocus;
+    private findFocusable;
+}

package/lib/table/pivot/pivot-value.type.d.ts

@@ -1,6 +1,7 @@
 import { ValueAccessor } from '../aggregation/value-accessor.type.js';
 import { AggregatorRef } from '../aggregation/aggregator-name.type.js';
 import { AggregatorIf } from '../aggregation/aggregator.if.js';
+import { ShowValuesAsConfig, ShowValuesAsIf } from '../calc/show-values-as.type.js';
 
 /**
  * One value of a pivot table in full form: where the value of a row comes from, how it is aggregated, and how its
@@ -32,6 +33,16 @@ export interface PivotValueIf<T = any> {
     label?: string;
     /** The text of a result in a cell. Default: numbers with at most two decimals (`"1,234.5"`). Excel gets the raw value. */
     format?: (result: unknown) => string;
+    /**
+     * „Show values as“ (since 1.1.95): `"percentOfRowTotal"` (each pivot row = 100 %), `"percentOfColumnTotal"`,
+     * `"percentOfGrandTotal"` or `"percentOfParentTotal"` (share of the parent row group). The cells then hold the
+     * fraction (Excel: number with percent format), the text is a percentage; `format` is not used. Other modes of
+     * {@link ShowValuesAs} don't apply to a pivot (the value is shown).
+     *
+     * @example
+     * values: [{ value: "umsatz", showValuesAs: "percentOfRowTotal" }]
+     */
+    showValuesAs?: ShowValuesAsConfig;
 }
 /**
  * A value of a pivot table: a property path or function (summed) or the full form {@link PivotValueIf}.
@@ -64,4 +75,6 @@ export interface PivotValueInfoIf {
     readonly aggregator: AggregatorIf;
     /** The format of a result, if one was given. */
     readonly format?: (result: unknown) => string;
+    /** „Show values as“, if one was given (since 1.1.95). */
+    readonly showValuesAs?: ShowValuesAsIf;
 }

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

@@ -1,3 +1,6 @@
+import { RowDragService } from './row-drag/row-drag-service.js';
+import { BatchEditService } from './batch-edit/batch-edit-service.js';
+import { FillHandleService } from './fill/fill-handle-service.js';
 import { TableOverlayChange } from './overlay/table-overlay.js';
 import { EleScope } from './ele-scope.js';
 import { TableModelIf } from './data/tablemodel/table-model.if.js';
@@ -23,6 +26,8 @@ import { AreaObjectMapType } from './data/common/area-map.type.js';
 import { TableCellUpdateEventIf } from './data/common/event/input/table-cell-update-event.if.js';
 import { AriaGridInfo } from './aria/aria-grid-info.js';
 import { AriaTextsIf } from './aria/aria-texts.if.js';
+import { RowLayout } from './row-layout/row-layout.js';
+import { MasterDetailService } from './master-detail/master-detail-service.js';
 
 /** @category Internals */
 export declare class RenderScope extends EleScope {
@@ -85,7 +90,136 @@ export declare class RenderScope extends EleScope {
      * first body row, see `TableScope`. `undefined`: the focus is in the body ({@link FocusModelIf}).
      */
     protected headerFocus?: [number, number];
+    /**
+     * Row drag of this table (drag handles, pointer and keyboard drag) – created by {@link TableScope}.
+     * @since 1.1.95
+     */
+    rowDragService?: RowDragService;
+    /**
+     * Batch edit of this table (pending values, shown in the cells) – created by {@link TableScope}.
+     * @since 1.1.96
+     */
+    batchEditService?: BatchEditService;
+    /**
+     * Fill handle of this table – created by {@link TableScope}.
+     * @since 1.1.96
+     */
+    fillHandleService?: FillHandleService;
+    /**
+     * Master/detail of this table (detail rows below master rows) – created by {@link TableScope} with
+     * `tableOptions.masterDetail`.
+     * @since 1.1.97
+     */
+    masterDetailService?: MasterDetailService;
+    /** Positions of the body rows (prefix sums of the heights + detail rows), see {@link getBodyRowLayout}. */
+    private readonly bodyRowLayout;
+    private bodyRowLayoutDirty;
+    private bodyRowLayoutModel?;
     constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, dom: ConvenienceDomService, tableOptions: TableOptionsIf);
+    /**
+     * The DOM service of this table (all DOM access of the table goes through it).
+     *
+     * @returns {ConvenienceDomService} the service
+     * @since 1.1.95
+     */
+    getDomService(): ConvenienceDomService;
+    /**
+     * The visible body in client (viewport) coordinates – including fixed west/east columns, without the scroll bar –
+     * and the content pixels scrolled out at its top. Row drag computes the row under the pointer with it.
+     *
+     * @returns {{ top: number, height: number, left: number, width: number, contentScrollTop: number }} the geometry
+     * @since 1.1.95
+     */
+    getBodyViewport(): {
+        top: number;
+        height: number;
+        left: number;
+        width: number;
+        contentScrollTop: number;
+    };
+    /**
+     * The rectangle of a body cell in host coordinates (relative to the padding box of the host) – computed from the
+     * row and column positions, also for cells that are not rendered – and the visible part of its area (`clip…`: the
+     * body between header and footer, horizontally the fixed west/east area or the scrollable center).
+     *
+     * @param {number} rowIndex - display index
+     * @param {number} columnIndex - model index
+     * @returns {{ left: number, top: number, width: number, height: number, clipLeft: number, clipRight: number, clipTop: number, clipBottom: number }} the geometry
+     * @since 1.1.96
+     */
+    getBodyCellRectInHost(rowIndex: number, columnIndex: number): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        clipLeft: number;
+        clipRight: number;
+        clipTop: number;
+        clipBottom: number;
+    };
+    /**
+     * The body cell at a point in host coordinates, clamped to the body (a point above the body = row 0, right of the
+     * columns = the last column …) – computed, not read from the DOM.
+     *
+     * @param {number} x - x relative to the host's padding box
+     * @param {number} y - y relative to the host's padding box
+     * @returns {[number, number]} row and column index, `[-1, -1]` without rows or columns
+     * @since 1.1.96
+     */
+    getBodyCellAtHostPoint(x: number, y: number): [number, number];
+    /**
+     * The positions of the body rows: prefix sums of the row heights (O(log n) lookups also for variable heights) plus
+     * the heights of open detail rows. Built lazily – again after {@link invalidateRowLayout}, a new body model or
+     * another row count.
+     *
+     * @returns {RowLayout} the layout of the body rows
+     * @since 1.1.97
+     */
+    getBodyRowLayout(): RowLayout;
+    /**
+     * Marks the positions of the body rows as outdated (rows filtered, sorted, edited, added or removed, a detail row
+     * opened or closed) – they are computed again on the next access.
+     *
+     * @since 1.1.97
+     */
+    invalidateRowLayout(): void;
+    /**
+     * Sets the height of the detail row behind one body row in the current row layout without building it again
+     * (a detail row was expanded or collapsed). Does nothing if the layout is outdated anyway.
+     *
+     * @param {number} rowIndex - display index of the master row
+     * @param {number} height - the detail height, 0 = none
+     * @returns {boolean} true if the layout was updated, false if it is outdated (it is built again on the next access)
+     * @since 1.1.97
+     */
+    setBodyRowExtra(rowIndex: number, height: number): boolean;
+    /** True if open detail rows take space between the body rows. */
+    protected hasBodyRowExtras(): boolean;
+    /**
+     * The top of a body row in content pixels: {@link AreaModelIf.getYPosByRowIndex} plus the heights of the open detail
+     * rows above it (master/detail).
+     *
+     * @param {number} rowIndex - display index
+     * @returns {number} px from the top of the first body row
+     * @since 1.1.97
+     */
+    getBodyRowTop(rowIndex: number): number;
+    /**
+     * The body row at a content position (a position in an open detail row belongs to its master row). Above the rows:
+     * 0, below: the last row, without rows: -1.
+     *
+     * @param {number} contentY - px from the top of the first body row
+     * @returns {number} display index
+     * @since 1.1.97
+     */
+    getBodyRowIndexAtY(contentY: number): number;
+    /**
+     * Scroll bar pixels per content pixel: 1, below 1 for a capped scroll height ({@link isScrollHeightCapped}).
+     *
+     * @returns {number} the factor for `scrollTop` changes
+     * @since 1.1.95
+     */
+    getScrollerToContentRatioY(): number;
     isEditing(): boolean;
     /**
      * Resets the editor renderer by clearing its values and state.
@@ -193,6 +327,11 @@ export declare class RenderScope extends EleScope {
      * @returns {void}
      */
     updateCells(events: TableCellUpdateEventIf[], repaintAll?: boolean): void;
+    /**
+     * After `updateCells()` without a repaint: draws the rendered cells of calculated and „Show values as“ columns of
+     * the body again (they depend on the changed cells, e.g. `total = price * quantity` or a share of the total).
+     */
+    protected rerenderCalculatedCells(): void;
     /**
      * After `updateCells()` without a repaint: draws the rendered aggregate cells of the group rows of a row grouping
      * again (they follow the changed rows; labels and counts don't change – a moved row repaints the whole table).
@@ -257,6 +396,15 @@ export declare class RenderScope extends EleScope {
      * scaled and scrollTop is no longer a content pixel position.
      */
     isScrollHeightCapped(): boolean;
+    /**
+     * The model's content height plus the heights of open detail rows (master/detail).
+     *
+     * @returns {number} px
+     * @since 1.1.97
+     */
+    /** The detail layer (master/detail) covers the visible body. @since 1.1.97 */
+    protected adjustDetailLayerBounds(left: number, top: number, width: number, height: number): void;
+    protected getBodyContentHeight(): number;
     /** Scrollable range of the content in content pixels (content height minus visible body height). */
     protected getContentScrollRangeY(): number;
     /** Scrollable range of the scroll viewport in scroll bar pixels. */
@@ -469,6 +617,12 @@ export declare class RenderScope extends EleScope {
      *
      * @returns {void}
      */
+    /**
+     * Hides the hover row and column – e.g. while the pointer is over a detail row (master/detail).
+     *
+     * @since 1.1.97
+     */
+    hideHover(): void;
     protected hideHoverRow(): void;
     /**
      * Adjusts the position and size of the hover column based on the mouse move event.

package/lib/table/renderer/edit/input-cell-renderer.d.ts

@@ -6,5 +6,5 @@ import { RendererCleanupFnType } from '../renderer-cleanup-fn.type.js';
 
 /** @category Renderers & editing */
 export declare class InputCellRenderer implements CellRendererIf {
-    render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, areaModel: AreaModelIf, _cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
+    render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, areaModel: AreaModelIf, cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
 }

package/lib/table/renderer/edit/select-cell-renderer.d.ts

@@ -10,5 +10,5 @@ export declare class SelectCellRenderer implements CellRendererIf {
     protected options: ValueLabelIf[];
     constructor(options: ValueLabelIf[]);
     static create(values: string[]): SelectCellRenderer;
-    render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, areaModel: AreaModelIf, _cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
+    render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, areaModel: AreaModelIf, cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
 }