@guiexpert/table 1.1.94 → 1.1.97

package/lib/table/action/action-id.type.d.ts

@@ -5,7 +5,7 @@
  *
  * @category Keyboard
  */
-export declare const actionIds: readonly ["COPY_2_CLIPBOARD", "START_EDITING", "TOGGLE_SELECTION", "SELECT_ALL", "DESELECT_ALL", "NAVIGATE_LEFT", "NAVIGATE_RIGHT", "NAVIGATE_UP", "NAVIGATE_DOWN", "NAVIGATE_ROW_START", "NAVIGATE_ROW_END", "NAVIGATE_FIRST_CELL", "NAVIGATE_LAST_CELL", "NAVIGATE_PAGE_UP", "NAVIGATE_PAGE_DOWN", "ACTIVATE_CELL"];
+export declare const actionIds: readonly ["COPY_2_CLIPBOARD", "START_EDITING", "TOGGLE_SELECTION", "SELECT_ALL", "DESELECT_ALL", "NAVIGATE_LEFT", "NAVIGATE_RIGHT", "NAVIGATE_UP", "NAVIGATE_DOWN", "NAVIGATE_ROW_START", "NAVIGATE_ROW_END", "NAVIGATE_FIRST_CELL", "NAVIGATE_LAST_CELL", "NAVIGATE_PAGE_UP", "NAVIGATE_PAGE_DOWN", "ACTIVATE_CELL", "MOVE_ROW_UP", "MOVE_ROW_DOWN", "FILL_DOWN", "FILL_RIGHT"];
 /**
  * Represents an action ID.
  *

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

@@ -31,4 +31,17 @@ export declare class AriaTexts implements AriaTextsIf {
     selectAllRows(): string;
     expandGroup(groupLabel: string): string;
     collapseGroup(groupLabel: string): string;
+    rowDragStarted(rowCount: number): string;
+    rowMoved(position: number, rowCount: number): string;
+    rowMoveNotPossible(): string;
+    rowDragCancelled(): string;
+    cellsFilled(cellCount: number): string;
+    detailExpanded(): string;
+    detailCollapsed(): string;
+    fillTooLarge(maxCells: number): string;
+    pendingChanges(pendingCount: number): string;
+    changesCommitted(cellCount: number): string;
+    changesDiscarded(): string;
+    commitBlocked(invalidCount: number): string;
+    invalidValue(message: string): string;
 }

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

@@ -85,4 +85,105 @@ export interface AriaTextsIf {
      * @returns {string} default: `"Collapse group Q1"`
      */
     collapseGroup(groupLabel: string): string;
+    /**
+     * Announced when a row drag starts (optional – {@link AriaTexts} has a default).
+     *
+     * @param {number} rowCount - number of dragged rows
+     * @returns {string} default: `"Dragging 1 row. Press Escape to cancel."`
+     * @since 1.1.95
+     */
+    rowDragStarted?(rowCount: number): string;
+    /**
+     * Announced after rows were moved by drag and drop or Ctrl+Alt+↑/↓ (optional – {@link AriaTexts} has a default).
+     *
+     * @param {number} position - 1-based position of the first moved row
+     * @param {number} rowCount - number of displayed rows
+     * @returns {string} default: `"Row moved to position 7 of 20"`
+     * @since 1.1.95
+     */
+    rowMoved?(position: number, rowCount: number): string;
+    /**
+     * Announced when rows cannot be moved: the table is sorted or filtered (managed row drag), or the row cannot move
+     * further (optional – {@link AriaTexts} has a default).
+     *
+     * @returns {string} default: `"Rows cannot be moved while the table is sorted or filtered"`
+     * @since 1.1.95
+     */
+    rowMoveNotPossible?(): string;
+    /**
+     * Announced when a row drag was cancelled (Escape) – optional, {@link AriaTexts} has a default.
+     *
+     * @returns {string} default: `"Drag cancelled"`
+     * @since 1.1.95
+     */
+    rowDragCancelled?(): string;
+    /**
+     * Announced after a fill (fill handle, Ctrl/⌘+D, Ctrl/⌘+R) – optional, {@link AriaTexts} has a default.
+     *
+     * @param {number} cellCount - the number of filled cells
+     * @returns {string} default: `"3 cells filled"`
+     * @since 1.1.96
+     */
+    cellsFilled?(cellCount: number): string;
+    /**
+     * Announced when a fill is refused because it covers too many cells ({@link FillHandleOptionsIf.maxCells}).
+     *
+     * @param {number} maxCells - the limit
+     * @returns {string} default: `"Too many cells to fill (at most 100000)"`
+     * @since 1.1.96
+     */
+    fillTooLarge?(maxCells: number): string;
+    /**
+     * Announced after a value was marked in a batch edit (or set back).
+     *
+     * @param {number} pendingCount - the number of pending cells
+     * @returns {string} default: `"3 changes not saved"`, `"No unsaved changes"`
+     * @since 1.1.96
+     */
+    pendingChanges?(pendingCount: number): string;
+    /**
+     * Announced after {@link TableApi.commitBatchEdit}.
+     *
+     * @param {number} cellCount - the number of written cells
+     * @returns {string} default: `"3 changes saved"`
+     * @since 1.1.96
+     */
+    changesCommitted?(cellCount: number): string;
+    /**
+     * Announced after {@link TableApi.cancelBatchEdit}.
+     *
+     * @returns {string} default: `"Changes discarded"`
+     * @since 1.1.96
+     */
+    changesDiscarded?(): string;
+    /**
+     * Announced when invalid values block {@link TableApi.commitBatchEdit}.
+     *
+     * @param {number} invalidCount - the number of invalid cells
+     * @returns {string} default: `"2 invalid values – nothing saved"`
+     * @since 1.1.96
+     */
+    commitBlocked?(invalidCount: number): string;
+    /**
+     * Announced when an edited value is invalid ({@link ColumnDefIf.validate}) and not written (without batch edit).
+     *
+     * @param {string} message - the message of the validator
+     * @returns {string} default: `"Invalid value: <message>"`
+     * @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/batch-edit/batch-edit-options.d.ts

@@ -0,0 +1,21 @@
+import { BatchEditOptionsIf } from './batch-edit-options.if.js';
+
+/**
+ * The defaults of {@link BatchEditOptionsIf}.
+ *
+ * @example
+ * BatchEditOptions.create(true).blockCommitOnInvalid;   // true
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare class BatchEditOptions implements BatchEditOptionsIf {
+    blockCommitOnInvalid: boolean;
+    /**
+     * The options of {@link TableOptionsIf.batchEdit} (`true`, `false` or an object) with defaults.
+     *
+     * @param {boolean | Partial<BatchEditOptionsIf>} [option] - `tableOptions.batchEdit`
+     * @returns {BatchEditOptionsIf} complete options
+     */
+    static create(option?: boolean | Partial<BatchEditOptionsIf>): BatchEditOptionsIf;
+}

package/lib/table/batch-edit/batch-edit-options.if.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Options of the batch edit ({@link TableOptionsIf.batchEdit}): changes are collected (marked, not written) and
+ * written with {@link TableApi.commitBatchEdit} or discarded with {@link TableApi.cancelBatchEdit}.
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   batchEdit: { blockCommitOnInvalid: false },   // always collect; invalid values don't block saving
+ * };
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface BatchEditOptionsIf {
+    /**
+     * `true` (default): {@link TableApi.commitBatchEdit} writes nothing while a pending value is invalid
+     * ({@link ColumnDefIf.validate}) and returns `false`.
+     */
+    blockCommitOnInvalid: boolean;
+}

package/lib/table/batch-edit/batch-edit-service.d.ts

@@ -0,0 +1,104 @@
+import { TableScope } from '../table-scope.js';
+import { CellChangeIf } from './cell-change.if.js';
+import { BatchEditOptionsIf } from './batch-edit-options.if.js';
+import { PendingCellIf } from './pending-cell-changes.js';
+
+/** A value to mark as pending – prepared by {@link TableScope.applyCellChanges}. */
+export interface PendingInputIf {
+    rowIndex: number;
+    columnIndex: number;
+    /** after the editInputPipe */
+    value: unknown;
+    /** as entered */
+    rawValue: unknown;
+    error?: string;
+}
+/**
+ * Batch edit of one table (`tableScope.batchEditService`): collects changes instead of writing them, shows them
+ * (`ge-table-cell-pending`) and writes them on commit. Use {@link TableApi.startBatchEdit},
+ * {@link TableApi.commitBatchEdit}, {@link TableApi.cancelBatchEdit} and {@link TableApi.getPendingChanges}.
+ *
+ * The pending values belong to the row **objects** – sorting and filtering keep them on their rows. They are shown, but
+ * sorting, filtering, totals, copy and the Excel export use the written data (like ag-Grid).
+ *
+ * @category Internals
+ * @since 1.1.96
+ */
+export declare class BatchEditService {
+    private readonly tableScope;
+    private readonly pending;
+    private started;
+    constructor(tableScope: TableScope);
+    /** The options of this table ({@link TableOptionsIf.batchEdit} + defaults). */
+    get options(): BatchEditOptionsIf;
+    /** `tableOptions.batchEdit` is set: changes are always collected. */
+    isPermanent(): boolean;
+    /** True while changes are collected (started, or {@link isPermanent}). */
+    isActive(): boolean;
+    /** True if values are pending. */
+    hasPending(): boolean;
+    /**
+     * Starts collecting changes (until commit or cancel).
+     *
+     * @returns {boolean} false if a batch edit is already running
+     */
+    start(): boolean;
+    /** The key of a shown row: its object (tree: the data), the index for models without objects. */
+    rowKeyOf(rowIndex: number): unknown;
+    /** The key of a column: its property, `#<index>` without one. */
+    propertyOf(columnIndex: number): string;
+    /**
+     * The pending value of a shown body cell – asked for every rendered cell (one map lookup, nothing while empty).
+     *
+     * @param {number} rowIndex - display index
+     * @param {number} columnIndex - model index
+     * @returns {PendingCellIf | undefined} the entry
+     */
+    getPendingAt(rowIndex: number, columnIndex: number): PendingCellIf | undefined;
+    /**
+     * The value a body cell shows: the pending value, otherwise the model value.
+     *
+     * @param {number} rowIndex - display index
+     * @param {number} columnIndex - model index
+     * @returns {unknown} the shown value
+     */
+    getShownValue(rowIndex: number, columnIndex: number): unknown;
+    /**
+     * Marks values as pending (B1, B6, B8) and reports the step (`onBatchEditChanged`, announcement). The caller repaints.
+     *
+     * @param {PendingInputIf[]} inputs - cells with piped and raw value
+     * @returns {CellChangeIf[]} the cells whose pending state changed
+     */
+    addPending(inputs: PendingInputIf[]): CellChangeIf[];
+    /**
+     * All pending changes with the current display indices (one scan of the shown rows).
+     *
+     * @returns {CellChangeIf[]} the pending cells
+     */
+    getPendingChanges(): CellChangeIf[];
+    /**
+     * Writes the pending values (B3): shown rows through `setValue` (the pipe runs once, row groupings regroup), rows a
+     * filter hides directly into their objects. One `onModelChanged` with all cells, then `onBatchEditChanged` "commit".
+     *
+     * @returns {boolean} false if invalid values block the commit ({@link BatchEditOptionsIf.blockCommitOnInvalid})
+     */
+    commit(): boolean;
+    /** Discards the pending values (B4) and ends a started batch edit. */
+    cancel(): void;
+    /**
+     * Forgets pending values of rows that are no longer in the model (`setRows`, a reloaded tree): they would never be
+     * shown, block a commit with an invalid value and be written into stale objects. Only for models whose rows are known
+     * (object arrays, trees, row groupings); others keep their entries.
+     *
+     * @returns {number} the number of removed entries
+     */
+    pruneOrphans(): number;
+    /** All row keys of the body (also filtered and collapsed rows) – `undefined` if the model can't tell. */
+    private collectRowKeys;
+    private toChange;
+    private findColumnIndex;
+    /** Row key → display index, for the rows with pending values only. */
+    private createRowIndexMap;
+    private fire;
+    private texts;
+}

package/lib/table/batch-edit/cell-change.if.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What started a change of cells: `"edit"` (cell editor), `"fill"` (fill handle, Ctrl/⌘+D, Ctrl/⌘+R),
+ * `"commit"` ({@link TableApi.commitBatchEdit}) or `"api"` ({@link TableApi.applyCellChanges}).
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export type CellChangeSource = "edit" | "fill" | "commit" | "api";
+/**
+ * One changed cell: row, column, old and new value – the unit of a change set ({@link GeModelChangeEvent.changes},
+ * {@link TableApi.getPendingChanges}). With old **and** new value it is enough for undo and redo.
+ *
+ * @example
+ * const listener = new EventAdapter();
+ * listener.onModelChanged = (evt: GeModelChangeEvent) => {
+ *   for (const change of evt.changes ?? []) {
+ *     console.log(change.property, change.oldValue, "→", change.newValue, change.row);
+ *   }
+ * };
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface CellChangeIf<T = any> {
+    /** The row object (tree: the data of the `TreeRow`); `undefined` for own area models without row objects. */
+    row: T;
+    /** Display index of the row when the change was reported, `-1` if a filter hides the row. */
+    rowIndex: number;
+    /** Model index of the column when the change was reported, `-1` if the column no longer exists. */
+    columnIndex: number;
+    /** The property of the column (`"#3"` for a column without property). */
+    property: string;
+    /** The value before the change (batch edit: before the first change of the cell). */
+    oldValue: unknown;
+    /** The new value (after the column's `editInputPipe`). */
+    newValue: unknown;
+    /** Batch edit: the message of {@link ColumnDefIf.validate} if the new value is invalid. */
+    error?: string;
+}

package/lib/table/batch-edit/cell-value-change.if.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A value to write into a body cell – the input of {@link TableApi.applyCellChanges} (and of the fill handle).
+ *
+ * @example
+ * const change: CellValueChangeIf = { rowIndex: 3, column: "price", value: 9.9 };
+ * tableApi.applyCellChanges([change]);
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface CellValueChangeIf {
+    /** Display index of the row in the body. */
+    rowIndex: number;
+    /** Model index of the column, or its property. */
+    column: number | string;
+    /** The new value – like typed into the editor: it runs through the column's `editInputPipe`. */
+    value: unknown;
+}

package/lib/table/batch-edit/pending-cell-changes.d.ts

@@ -0,0 +1,104 @@
+/**
+ * One pending (not yet written) cell value of a batch edit – an entry of {@link PendingCellChanges}.
+ *
+ * @category Internals
+ * @since 1.1.96
+ */
+export interface PendingCellIf {
+    /** The key of the row: the row object (tree: the data of the `TreeRow`), or the row index for models without objects. */
+    rowKey: unknown;
+    /** The property of the column (`"#3"` for a column without property). */
+    property: string;
+    /** The value before the first change. */
+    oldValue: unknown;
+    /** The value shown (after the column's `editInputPipe`). */
+    newValue: unknown;
+    /** The value as entered (written with `setValue` on commit – the pipe runs there once). */
+    rawValue: unknown;
+    /** The message of {@link ColumnDefIf.validate}, if the value is invalid. */
+    error?: string;
+}
+/**
+ * What {@link PendingCellChanges.set} did: a new entry, a changed entry, an entry removed because the value is the
+ * old one again (B8), or nothing (the value equals the old one and there was no entry).
+ *
+ * @category Internals
+ * @since 1.1.96
+ */
+export type PendingChangeResult = "added" | "changed" | "removed" | "unchanged";
+/**
+ * True if two cell values are the same for a batch edit: `Object.is`, dates by time, a number and the text of the same
+ * number (an editor without `editInputPipe` returns texts), and `null` / `undefined` / `""` as "empty".
+ *
+ * @param {unknown} a - one value
+ * @param {unknown} b - another value
+ * @returns {boolean} whether the cell would not change
+ *
+ * @example
+ * isSameCellValue(5, "5");                                        // true
+ * isSameCellValue(new Date(2026, 0, 1), new Date(2026, 0, 1));    // true
+ * isSameCellValue(undefined, "");                                 // true
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare function isSameCellValue(a: unknown, b: unknown): boolean;
+/**
+ * The pending values of a batch edit: per row (the row **object**, not its index – sorting and filtering don't
+ * change the assignment) and property one entry with old and new value. DOM-free; the table keeps one in its
+ * batch edit service.
+ *
+ * @example
+ * const pending = new PendingCellChanges();
+ * const row = { price: 10 };
+ * pending.set(row, "price", 10, 12, "12");   // "added"
+ * pending.set(row, "price", 12, 10, "10");   // "removed" – the old value again
+ *
+ * @category Internals
+ * @since 1.1.96
+ */
+export declare class PendingCellChanges {
+    private readonly rows;
+    private count;
+    /**
+     * Sets the pending value of a cell. The old value of an existing entry stays (the value before the first change);
+     * a value equal to it removes the entry (B8).
+     *
+     * @param {unknown} rowKey - the row object (or the row index for models without objects)
+     * @param {string} property - the property of the column
+     * @param {unknown} oldValue - the current value in the model (used for a new entry)
+     * @param {unknown} newValue - the new value (after the pipe)
+     * @param {unknown} rawValue - the value as entered
+     * @param {string} [error] - validation message
+     * @returns {PendingChangeResult} what happened
+     */
+    set(rowKey: unknown, property: string, oldValue: unknown, newValue: unknown, rawValue: unknown, error?: string): PendingChangeResult;
+    /**
+     * The pending entry of a cell.
+     *
+     * @param {unknown} rowKey - the row object (or index)
+     * @param {string} property - the property of the column
+     * @returns {PendingCellIf | undefined} the entry, `undefined` if the cell is unchanged
+     */
+    get(rowKey: unknown, property: string): PendingCellIf | undefined;
+    /**
+     * Removes the entry of a cell.
+     *
+     * @param {unknown} rowKey - the row object (or index)
+     * @param {string} property - the property of the column
+     * @returns {boolean} true if there was an entry
+     */
+    remove(rowKey: unknown, property: string): boolean;
+    /** @returns {boolean} true if the row has pending values */
+    hasRow(rowKey: unknown): boolean;
+    /** @returns {number} the number of pending cells */
+    size(): number;
+    /** @returns {boolean} true if nothing is pending */
+    isEmpty(): boolean;
+    /** @returns {number} the number of pending cells with a validation message */
+    invalidCount(): number;
+    /** @returns {PendingCellIf[]} all entries, in the order they were first changed */
+    entries(): PendingCellIf[];
+    /** Forgets all entries. */
+    clear(): void;
+}

package/lib/table/calc/column-values.d.ts

@@ -0,0 +1,55 @@
+import { ColumnDefIf } from '../data/tablemodel/column/column-def.if.js';
+import { ValueGetter } from './value-getter.type.js';
+import { ValueGetterContextIf } from './value-getter-context.if.js';
+import { AggregatorRef } from '../aggregation/aggregator-name.type.js';
+import { ShowValuesAsIf } from './show-values-as.type.js';
+
+/** What an area model provides to its {@link ColumnValues}. */
+export interface ColumnValuesOwner {
+    /** The column definitions (read lazily – they may be replaced, e.g. by a pivot). */
+    getColumnDefsForValues(): ColumnDefIf[];
+    /** The value of a property path (the model's own semantics – unchanged behaviour for normal columns). */
+    readPath(row: any, property: string): unknown;
+    /** The rows of column aggregates (filtered, data objects) and a cheap signal that changes with them. */
+    getAggregationSource(): {
+        signal: unknown;
+        length: number;
+        rows: () => ArrayLike<unknown>;
+    };
+}
+/**
+ * Resolves `valueGetter`s by property, detects cycles (`#CIRC!`), caches column aggregates.
+ * Without calculated columns `get()` is one empty-map lookup plus the model's own path read.
+ */
+export declare class ColumnValues {
+    private readonly owner;
+    private getters?;
+    private showValuesAs?;
+    private properties?;
+    private defsLength;
+    /** property → rows whose value is being computed (a getter may read the same column of another row) */
+    private readonly computing;
+    private readonly contexts;
+    private aggregates;
+    private aggSignal;
+    private aggLength;
+    constructor(owner: ColumnValuesOwner);
+    /** Drops the getter lookup and the cached aggregates (`invalidateDerivedValues`). */
+    invalidate(): void;
+    /** The getter of a calculated column. */
+    getter(property: string | undefined): ValueGetter | undefined;
+    hasGetters(): boolean;
+    isCalculated(property: string): boolean;
+    hasColumn(property: string): boolean;
+    /** The „Show values as“ options of a column. */
+    getShowValuesAs(property: string | undefined): ShowValuesAsIf | undefined;
+    hasShowValuesAs(): boolean;
+    /** The value of a column for a row: its getter (cycle-safe, exceptions → `#VALUE!`) or the path. */
+    get(row: any, property: string): unknown;
+    /** An aggregate of a column over the filtered rows – cached. */
+    aggregate(property: string, aggregator: AggregatorRef): unknown;
+    /** The context passed to a getter. */
+    context(property: string): ValueGetterContextIf;
+    private call;
+    private lookup;
+}

package/lib/table/calc/show-values-as-internals.d.ts

@@ -0,0 +1,4 @@
+import { ShowValuesAsConfig } from './show-values-as.type.js';
+
+/** The Excel number format of a shown value (percentages: `0.0%`), `undefined` for the default. */
+export declare function excelFormatOfShowValuesAs(config: ShowValuesAsConfig | undefined): string | undefined;

package/lib/table/calc/show-values-as.d.ts

@@ -0,0 +1,87 @@
+import { ShowValuesAs, ShowValuesAsConfig, ShowValuesAsIf } from './show-values-as.type.js';
+
+/**
+ * The full options of a „Show values as“ configuration – `undefined` for none or an unknown mode.
+ *
+ * @param {ShowValuesAsConfig | undefined} config - a mode or mode with options
+ * @returns {ShowValuesAsIf | undefined} the options
+ *
+ * @example
+ * resolveShowValuesAs("rank");   // { mode: "rank" }
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function resolveShowValuesAs(config: ShowValuesAsConfig | undefined | null): ShowValuesAsIf | undefined;
+/**
+ * All modes of {@link ShowValuesAs}, e.g. for an own select box.
+ *
+ * @example
+ * select.append(...SHOW_VALUES_AS_MODES.map(mode => new Option(mode, mode)));
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare const SHOW_VALUES_AS_MODES: readonly ShowValuesAs[];
+/**
+ * True for the modes that show a share (a fraction, shown as percentage).
+ *
+ * @param {ShowValuesAs} mode - the mode
+ * @returns {boolean} whether the shown value is a fraction
+ *
+ * @example
+ * isPercentShowValuesAs("percentOfColumnTotal");   // true
+ * isPercentShowValuesAs("rank");                   // false
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function isPercentShowValuesAs(mode: ShowValuesAs | undefined): boolean;
+/**
+ * The text of a shown value: percentages with one decimal (`"66.7%"`), ranks without decimals, differences and
+ * running totals like totals (`"1,234.5"`). Not a number → `""`.
+ *
+ * @param {unknown} value - the shown value (a fraction for percentages)
+ * @param {ShowValuesAsConfig} config - the configuration of the column
+ * @returns {string} the text
+ *
+ * @example
+ * formatShowValuesAs(0.667, "percentOfColumnTotal");                          // "66.7%"
+ * formatShowValuesAs(0.667, { mode: "percentOfColumnTotal", fractionDigits: 2 }); // "66.70%"
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function formatShowValuesAs(value: unknown, config: ShowValuesAsConfig): string;
+/**
+ * The sum of the numbers of a list (Neumaier, like {@link Aggregators}.sum); other values are skipped.
+ *
+ * @param {ArrayLike<unknown>} values - the values
+ * @returns {number} the sum, 0 for none
+ *
+ * @example
+ * sumOfNumbers([1, "2", 3, undefined]);   // 4
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function sumOfNumbers(values: ArrayLike<unknown>): number;
+/**
+ * „Show values as“ over a list of values in display order – DOM-free, for own area models. Percentages are
+ * fractions (`0.667`); the reference is the list itself (`percentOfRowTotal` is not applicable to a list: the values are
+ * returned unchanged). Values that are no numbers → `undefined`.
+ *
+ * @param {ArrayLike<unknown>} values - the raw values in display order
+ * @param {ShowValuesAs} mode - the mode
+ * @returns {(number | undefined)[]} the shown values
+ *
+ * @example
+ * calculateShowValuesAs([2598, 1047, 250], "percentOfColumnTotal");   // [0.667…, 0.268…, 0.064…]
+ * calculateShowValuesAs([10, 20, 20, 5], "rank");                      // [3, 1, 1, 4]
+ * calculateShowValuesAs([10, 20, 5], "runningTotal");                  // [10, 30, 35]
+ * calculateShowValuesAs([10, 20, 5], "differenceFromPrevious");        // [undefined, 10, -15]
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function calculateShowValuesAs(values: ArrayLike<unknown>, mode: ShowValuesAs): (number | undefined)[];

package/lib/table/calc/show-values-as.type.d.ts

@@ -0,0 +1,55 @@
+/**
+ * How a column shows its numbers – without changing the data („Show values as“):
+ *
+ * | Mode | Shows | Flat table | Tree / row groups | Pivot |
+ * |---|---|---|---|---|
+ * | `"percentOfColumnTotal"` | value / sum of the column | ✓ | sum of the (filtered) leaf rows | cell / column total |
+ * | `"percentOfGrandTotal"` | value / grand total | = column total | = column total | cell / grand total |
+ * | `"percentOfParentTotal"` | value / total of the parent | = column total | value / sum of its siblings (each group = 100 %) | cell / parent row |
+ * | `"percentOfRowTotal"` | value / row total | – | – | cell / row total |
+ * | `"differenceFromPrevious"` | value − value of the row above | ✓ (first row empty) | among siblings | – |
+ * | `"runningTotal"` | sum up to this row (display order) | ✓ | among siblings | – |
+ * | `"rank"` | 1 = largest value, ties share a rank (1, 2, 2, 4) | ✓ | among siblings | – |
+ *
+ * The reference are the **filtered** rows (like the total row). Not applicable (–): the raw value is shown.
+ * Values that are no numbers and a total of 0 give an empty cell.
+ *
+ * @example
+ * ColumnDef.create({ property: "share", headerLabel: "Share", valueGetter: o => o.total,
+ *                    showValuesAs: "percentOfColumnTotal" });
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export type ShowValuesAs = "percentOfColumnTotal" | "percentOfGrandTotal" | "percentOfParentTotal" | "percentOfRowTotal" | "differenceFromPrevious" | "runningTotal" | "rank";
+/**
+ * „Show values as“ with options: mode, decimals, own text.
+ *
+ * @example
+ * ColumnDef.create({
+ *   property: "total", headerLabel: "Share",
+ *   showValuesAs: { mode: "percentOfColumnTotal", fractionDigits: 2 }   // "66.70%"
+ * });
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export interface ShowValuesAsIf {
+    /** The mode. */
+    mode: ShowValuesAs;
+    /** Decimals of the text. Default: 1 for percentages, at most 2 otherwise, 0 for `rank`. */
+    fractionDigits?: number;
+    /** An own text of the shown value (a fraction for percentages, e.g. `0.667`). Text only – never HTML. */
+    format?: (value: number) => string;
+}
+/**
+ * The configuration of a column: a mode or a mode with options.
+ *
+ * @example
+ * const share: ShowValuesAsConfig = "percentOfColumnTotal";
+ * const precise: ShowValuesAsConfig = { mode: "percentOfColumnTotal", fractionDigits: 2 };
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export type ShowValuesAsConfig = ShowValuesAs | ShowValuesAsIf;