@guiexpert/table 1.1.96 → 1.1.98

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/render-scope.d.ts

@@ -26,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 {
@@ -103,6 +105,16 @@ export declare class RenderScope extends EleScope {
      * @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).
@@ -155,6 +167,52 @@ export declare class RenderScope extends EleScope {
      * @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}).
      *
@@ -338,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. */
@@ -550,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/row-layout/row-layout.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Vertical positions of the body rows: the row heights as prefix sums plus optional extra heights behind single rows
+ * (the detail rows of master/detail). DOM-free; the table keeps one instance for its body
+ * ({@link RenderScope.getBodyRowTop}, {@link RenderScope.getBodyRowIndexAtY}).
+ *
+ * - Constant row height: positions are computed (`i * h`), no array.
+ * - Variable row heights: a `Float64Array` of `rowCount + 1` prefix sums, built lazily on the first access after
+ *   {@link setRows} – then {@link getTop} is O(1) and {@link findIndexAt} O(log n) (before 1.1.97 the table summed the
+ *   heights of all rows above the viewport in every scroll frame).
+ * - Extras: sorted row indices with their extra heights and the prefix sums of the extras (O(log k) per lookup,
+ *   k = number of extras). Changing one extra height ({@link setExtraHeight}) costs O(k), not O(n).
+ *
+ * The slot of a row is the row plus its extra height below it: `getTop(i + 1) = getTop(i) + getRowHeight(i) +
+ * getExtraHeight(i)`.
+ *
+ * @example
+ * const layout = new RowLayout();
+ * layout.setRows(1000, i => i % 2 ? 30 : 50);       // variable heights
+ * layout.setExtras([12, 40], [180, 240]);            // details behind rows 12 and 40
+ * const top = layout.getTop(41);                     // top of row 41 below both details
+ * const row = layout.findIndexAt(5000);              // the row whose slot contains y = 5000
+ *
+ * @category Internals
+ * @since 1.1.97
+ */
+export declare class RowLayout {
+    private rowCount;
+    private constantHeight?;
+    private heightOf;
+    private prefix?;
+    private extraIndices;
+    private extraHeights;
+    private extraPrefix;
+    /**
+     * Sets the rows. Prefix sums of variable heights are built lazily on the first access.
+     * Extras behind rows that no longer exist are dropped.
+     *
+     * @param {number} rowCount - number of rows
+     * @param {(rowIndex: number) => number} heightOf - height of a row (called only for variable heights)
+     * @param {number} [constantHeight] - the height of every row, if they are all equal (`AreaModelIf.getConstantRowHeight`)
+     */
+    setRows(rowCount: number, heightOf: (rowIndex: number) => number, constantHeight?: number): void;
+    /**
+     * Sets the extra heights (e.g. detail rows) behind rows. Unsorted input is fine; heights of the same row add up;
+     * indices outside the rows and heights ≤ 0 are ignored. Replaces all previous extras.
+     *
+     * @param {ArrayLike<number>} rowIndices - the rows with an extra height below them
+     * @param {ArrayLike<number>} heights - the extra heights (same order as `rowIndices`)
+     */
+    setExtras(rowIndices: ArrayLike<number>, heights: ArrayLike<number>): void;
+    /**
+     * Changes the extra height behind one row that already has one (see {@link setExtras}).
+     *
+     * @param {number} rowIndex - the row
+     * @param {number} height - the new extra height (> 0)
+     * @returns {boolean} false if the row has no extra or the height did not change
+     */
+    setExtraHeight(rowIndex: number, height: number): boolean;
+    /**
+     * Sets, changes or (height ≤ 0) removes the extra height behind one row – O(k), the other extras stay.
+     *
+     * @param {number} rowIndex - the row (ignored outside the rows)
+     * @param {number} height - the extra height, ≤ 0 removes it
+     * @returns {boolean} true if something changed
+     */
+    setExtra(rowIndex: number, height: number): boolean;
+    /** The number of rows. */
+    getRowCount(): number;
+    /** The number of rows with an extra height. */
+    getExtraCount(): number;
+    /** True after the prefix sums of variable heights were built (never for constant heights). */
+    hasPrefixSums(): boolean;
+    /**
+     * The height of a row (without its extra).
+     *
+     * @param {number} rowIndex - the row
+     * @returns {number} the height in px
+     */
+    getRowHeight(rowIndex: number): number;
+    /**
+     * The extra height below a row (0 = none).
+     *
+     * @param {number} rowIndex - the row
+     * @returns {number} the extra height in px
+     */
+    getExtraHeight(rowIndex: number): number;
+    /**
+     * The sum of the extra heights of the rows above a row.
+     *
+     * @param {number} rowIndex - the row (`rowCount` = all extras)
+     * @returns {number} px
+     */
+    getExtraBefore(rowIndex: number): number;
+    /** The sum of all extra heights. */
+    getExtraTotal(): number;
+    /**
+     * The top of a row: heights and extras of all rows above it. `getTop(rowCount)` = total height. The index is
+     * clamped to `0 … rowCount`.
+     *
+     * @param {number} rowIndex - the row
+     * @returns {number} px from the top of the first row
+     */
+    getTop(rowIndex: number): number;
+    /** The height of all rows and extras. */
+    getTotalHeight(): number;
+    /**
+     * The row whose slot (row + extra) contains `y`; rows of height 0 are skipped. Above the first row: 0, below the
+     * last: the last row, without rows: -1. O(1) for constant heights without extras, otherwise O(log n).
+     *
+     * @param {number} y - px from the top of the first row
+     * @returns {number} the row index
+     */
+    findIndexAt(y: number): number;
+    private getBaseTop;
+    private ensurePrefix;
+    private rebuildExtraPrefix;
+    /** The number of extras behind rows with an index < rowIndex (lower bound). */
+    private countExtrasBelow;
+    private findExtra;
+}

package/lib/table/rtl/rtl-util.d.ts

@@ -0,0 +1,126 @@
+import { ResolvedTableDirection, TableDirection } from './table-direction.type.js';
+
+/**
+ * Decides the direction of a table: `"rtl"` and `"ltr"` as given, `"auto"` from the computed `direction` of the host
+ * (inherited from `<html dir="rtl">` or any parent) – for a host that is not in the document yet from the nearest
+ * `dir` attribute of the host or a parent. Missing (`undefined`) = `"ltr"`.
+ *
+ * Must be called before the table sets the `dir` attribute of the host.
+ *
+ * @param {TableDirection | undefined} direction - the option ({@link TableOptionsIf.direction})
+ * @param {HTMLElement} [host] - the host element of the table (needed for `"auto"`)
+ * @returns {ResolvedTableDirection} `"ltr"` or `"rtl"`
+ *
+ * @example
+ * resolveTableDirection("auto", document.getElementById("table")!); // "rtl" on a page with <html dir="rtl">
+ *
+ * @since 1.1.98
+ * @category Utilities
+ */
+export declare function resolveTableDirection(direction: TableDirection | undefined, host?: HTMLElement): ResolvedTableDirection;
+/**
+ * The horizontal scroll position of an element as distance from the **start** (≥ 0): in left-to-right `scrollLeft`,
+ * in right-to-left `-scrollLeft` (browsers report 0 at the right start and negative values when scrolled to the left,
+ * CSSOM View).
+ *
+ * @param {{ scrollLeft: number }} element - a scroll container
+ * @param {boolean} rtl - the container is right-to-left
+ * @returns {number} px from the start
+ *
+ * @example
+ * const fromStart = getLogicalScrollLeft(tableApi.getTableScope().scrollViewport, tableApi.getDirection() === "rtl");
+ *
+ * @since 1.1.98
+ * @category Utilities
+ */
+export declare function getLogicalScrollLeft(element: {
+    scrollLeft: number;
+}, rtl: boolean): number;
+/**
+ * Sets the horizontal scroll position of an element as distance from the **start** (see {@link getLogicalScrollLeft}).
+ *
+ * @param {{ scrollLeft: number }} element - a scroll container
+ * @param {number} x - px from the start
+ * @param {boolean} rtl - the container is right-to-left
+ *
+ * @example
+ * setLogicalScrollLeft(tableApi.getTableScope().scrollViewport, 0, true); // back to the (right) start
+ *
+ * @since 1.1.98
+ * @category Utilities
+ */
+export declare function setLogicalScrollLeft(element: {
+    scrollLeft: number;
+}, x: number, rtl: boolean): void;
+/**
+ * The horizontal scroll position for `element.scrollTo(…)` – physical, i.e. negative in right-to-left.
+ *
+ * @param {number} x - px from the start
+ * @param {boolean} rtl - right-to-left
+ * @returns {number} the value for `scrollLeft` / `scrollTo()`
+ *
+ * @example
+ * tableApi.getTableScope().scrollViewport.scrollTo(toPhysicalScrollLeft(200, true), 0); // 200 px from the right start
+ *
+ * @since 1.1.98
+ * @category Utilities
+ */
+export declare function toPhysicalScrollLeft(x: number, rtl: boolean): number;
+/**
+ * Whether a scroll container can still scroll horizontally by `dx` (physical: `dx > 0` = to the right) – for
+ * left-to-right and right-to-left containers alike.
+ *
+ * @param {{ scrollLeft: number, scrollWidth: number, clientWidth: number }} element - a scroll container
+ * @param {number} dx - physical delta (e.g. `WheelEvent.deltaX`)
+ * @param {boolean} rtl - the container is right-to-left
+ * @returns {boolean} true if a scroll by `dx` would move the content
+ *
+ * @example
+ * host.addEventListener("wheel", e => {
+ *   const takesIt = canScrollHorizontally(host, e.deltaX, getComputedStyle(host).direction === "rtl");
+ *   console.info(takesIt ? "the element scrolls itself" : "pass it on");
+ * });
+ *
+ * @since 1.1.98
+ * @category Utilities
+ */
+export declare function canScrollHorizontally(element: {
+    scrollLeft: number;
+    scrollWidth: number;
+    clientWidth: number;
+}, dx: number, rtl: boolean): boolean;
+/**
+ * A client x coordinate (e.g. `PointerEvent.clientX`) as position in a box measured from the box's **start**:
+ * left-to-right from its left edge, right-to-left from its right edge.
+ *
+ * @param {number} clientX - x in client (viewport) coordinates
+ * @param {number} boxLeft - the left edge of the box in client coordinates
+ * @param {number} boxWidth - the width of the box
+ * @param {boolean} rtl - right-to-left
+ * @returns {number} px from the start of the box
+ *
+ * @example
+ * host.addEventListener("pointerdown", e => {
+ *   const r = host.getBoundingClientRect();
+ *   console.info(toLogicalX(e.clientX, r.left + host.clientLeft, host.clientWidth, true)); // px from the right edge
+ * });
+ *
+ * @since 1.1.98
+ * @category Utilities
+ */
+export declare function toLogicalX(clientX: number, boxLeft: number, boxWidth: number, rtl: boolean): number;
+/**
+ * Swaps the arrow keys "left" and "right" in a harmonized shortcut (e.g. `"cmd left"` → `"cmd right"`) – the
+ * keyboard handling of a right-to-left table, so that → moves backwards in reading direction.
+ *
+ * @param {string} shortcut - a harmonized shortcut (`harmonizeShortcut`)
+ * @returns {string} the shortcut with swapped arrow keys
+ *
+ * @example
+ * mirrorArrowKeys("left");       // "right"
+ * mirrorArrowKeys("cmd right");  // "cmd left"
+ *
+ * @since 1.1.98
+ * @category Keyboard
+ */
+export declare function mirrorArrowKeys(shortcut: string): string;

package/lib/table/rtl/table-direction.type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The writing direction of a table ({@link TableOptionsIf.direction}):
+ *
+ * - `"ltr"` (default): left to right – the first column on the left.
+ * - `"rtl"`: right to left (Arabic, Hebrew, Persian, Urdu …) – the first column on the right, horizontal scrolling,
+ *   fixed columns, tree indent, resize handles and arrow keys mirrored.
+ * - `"auto"`: the direction of the page where the table is created (`dir="rtl"` on `<html>`, a parent element or the
+ *   host itself → `"rtl"`).
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = { ...new TableOptions(), direction: "rtl" };
+ *
+ * @since 1.1.98
+ * @category Options
+ */
+export type TableDirection = "ltr" | "rtl" | "auto";
+/**
+ * A resolved writing direction – what {@link TableApi.getDirection} returns (`"auto"` is already decided).
+ *
+ * @since 1.1.98
+ * @category Options
+ */
+export type ResolvedTableDirection = "ltr" | "rtl";

package/lib/table/service/convenience-dom.service.d.ts

@@ -10,6 +10,7 @@ import { SideIdent } from '../data/side-ident.type.js';
 import { SortState } from '../data/common/sort-state.type.js';
 import { SortedOptionsIf } from '../data/options/sorted-options.if.js';
 import { HtmlStyle } from './data/html-style.type.js';
+import { ResolvedTableDirection } from '../rtl/table-direction.type.js';
 
 /** @category DOM */
 export interface AddColumnDivPara {
@@ -37,7 +38,54 @@ export declare class ConvenienceDomService {
     readonly domService: DomServiceIf;
     /** Width of the focus frame of a cell in px (WCAG 2.4.7: visible focus, not only a color). @since 1.1.91 */
     static focusBorderWidthInPx: number;
+    /** Right-to-left: `left` is written as `right` and vice versa (see {@link setDirection}). */
+    private rtl;
+    /** The physical CSS property of the inline start (`left`, right-to-left `right`). */
+    private startKey;
+    /** The physical CSS property of the inline end (`right`, right-to-left `left`). */
+    private endKey;
     constructor(domService: DomServiceIf);
+    /**
+     * Sets the writing direction of the table. All positions of the table are computed from the **start** of a row
+     * (x = 0 is the first column); in right-to-left this service writes them as `right` instead of `left` – in
+     * {@link setStyle}, {@link applyStyle}, {@link applyStyleInPx} and all `add…` methods – so that the whole table is
+     * mirrored. Called once by the table before anything is positioned.
+     *
+     * @param {ResolvedTableDirection} direction - `"ltr"` or `"rtl"`
+     *
+     * @example
+     * const dom = new ConvenienceDomService(new SimpleDomService());
+     * dom.setDirection("rtl");
+     * const div = document.createElement("div");
+     * dom.setStyle(div, "left", "20px"); // div.style.right = "20px"
+     *
+     * @since 1.1.98
+     */
+    setDirection(direction: ResolvedTableDirection): void;
+    /**
+     * The writing direction set with {@link setDirection} (default `"ltr"`).
+     *
+     * @returns {ResolvedTableDirection} `"ltr"` or `"rtl"`
+     * @since 1.1.98
+     */
+    getDirection(): ResolvedTableDirection;
+    /**
+     * The physical CSS property for a logical position key: in right-to-left `left` ↔ `right`, everything else as is.
+     *
+     * @param {string} key - a CSS property
+     * @returns {string} the property to write
+     * @since 1.1.98
+     */
+    toPhysicalStyleKey(key: string): string;
+    /**
+     * The position of an element from the inline start in px, as written by this service (`style.left`, right-to-left
+     * `style.right`); 0 if it has none.
+     *
+     * @param {HTMLElement} ele - an element positioned by this service
+     * @returns {number} px
+     * @since 1.1.98
+     */
+    getInlineStart(ele: HTMLElement): number;
     setStyle(el: any, style: string, value: any): any;
     applyStyle(ele: HTMLDivElement, style: HtmlStyle): HTMLDivElement;
     applyDisplayNoneStyle(ele: HTMLDivElement): HTMLDivElement;
@@ -46,7 +94,7 @@ export declare class ConvenienceDomService {
     applyStylePosistionRelative(ele: HTMLDivElement): HTMLDivElement;
     applyStylePosistionAbsolute(ele: HTMLDivElement): HTMLDivElement;
     applyStyleFullSize(ele: HTMLDivElement): HTMLDivElement;
-    applyStyleOverflowAuto(overflowX: "scroll" | "auto" | undefined, overflowY: "scroll" | "auto" | undefined, ele: HTMLDivElement): HTMLDivElement;
+    applyStyleOverflowAuto(overflowX: "auto" | "scroll" | undefined, overflowY: "auto" | "scroll" | undefined, ele: HTMLDivElement): HTMLDivElement;
     applyStyleNoPadding(ele: HTMLDivElement): HTMLDivElement;
     appendRelativeChildDiv(parent: HTMLDivElement): DivScope;
     appendText(parent: HTMLDivElement, text: string): HTMLElement;