@guiexpert/table 1.1.96 → 1.1.98

package/lib/table/service/excel-export-options.if.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Options of an Excel export ({@link ExcelService.downloadExcel}, {@link ExcelService.createExcelBlob}).
+ *
+ * @example
+ * // an Arabic sheet: column A on the right, like the table
+ * await new ExcelService().downloadExcel(matrix, "sales.xlsx", "", { rightToLeft: true });
+ *
+ * @since 1.1.98
+ * @category Export & clipboard
+ */
+export interface ExcelExportOptionsIf {
+    /**
+     * The worksheet runs from right to left (`<sheetView rightToLeft="1">`): column A on the right.
+     * {@link TableApi.downloadExcel} sets it for a right-to-left table ({@link TableOptionsIf.direction}).
+     */
+    rightToLeft?: boolean;
+}

package/lib/table/service/excel-service.d.ts

@@ -1,3 +1,4 @@
+import { ExcelExportOptionsIf } from './excel-export-options.if.js';
 import { ExcelServiceIf } from './excel-service.if.js';
 
 /**
@@ -32,18 +33,23 @@ export declare class ExcelService implements ExcelServiceIf {
      * @param {Array<Array<any>>} matrix - A 2D array representing the data to be included in the Excel file. Each inner array corresponds to a row in the sheet.
      * @param {string} [filename='file.xlsx'] - The name of the Excel file to be downloaded. Defaults to 'file.xlsx'.
      * @param {string} [author=''] - The author's name to include as metadata in the Excel file. Optional parameter.
+     * @param {ExcelExportOptionsIf} [options] - e.g. `{ rightToLeft: true }` for a sheet from right to left (since 1.1.98)
      * @return {void} Does not return a value.
      * @throws {Error} Throws an error if the input matrix is not a valid 2D array or if the filename is an empty string.
      */
-    downloadExcel(matrix: Array<Array<any>>, filename?: string, author?: string): Promise<void>;
+    downloadExcel(matrix: Array<Array<any>>, filename?: string, author?: string, options?: ExcelExportOptionsIf): Promise<void>;
     /**
      * Creates the .xlsx file as a Blob (compressed), e.g. to upload it instead of downloading it.
      *
      * @example
      * const blob = await new ExcelService().createExcelBlob([["Name", "City"], ["Ann", "Berlin"]]);
      * await fetch("/api/upload", { method: "POST", body: blob });
+     *
+     * @example
+     * // a sheet from right to left (column A on the right), since 1.1.98
+     * const rtlBlob = await new ExcelService().createExcelBlob([["المدينة"], ["الرياض"]], "", { rightToLeft: true });
      */
-    createExcelBlob(matrix: Array<Array<any>>, author?: string): Promise<Blob>;
+    createExcelBlob(matrix: Array<Array<any>>, author?: string, options?: ExcelExportOptionsIf): Promise<Blob>;
     private generateMap;
     private getX1WorksheetsSheet1Xml;
     /** Number format → cell style index (1-based; 0 = default), filled by withNumberFormats() before the sheet is written. */

package/lib/table/service/excel-service.if.d.ts

@@ -1,3 +1,5 @@
+import { ExcelExportOptionsIf } from './excel-export-options.if.js';
+
 /**
  * Writes an Excel file from a matrix of values. The default implementation is {@link ExcelService};
  * pass your own as last argument of the `TableScope` constructor to change how {@link TableApi.downloadExcel} exports.
@@ -6,7 +8,7 @@
  */
 export interface ExcelServiceIf {
     /** Creates the file from `matrix` (rows of values) and hands it to the browser as download. */
-    downloadExcel(matrix: Array<Array<any>>, filename: string, author?: string): void | Promise<void>;
+    downloadExcel(matrix: Array<Array<any>>, filename: string, author?: string, options?: ExcelExportOptionsIf): void | Promise<void>;
     /**
      * True if the service understands cells of the form {@link ExcelFormattedValueIf} (`{ value, numberFormat }`).
      * Only then {@link TableApi.downloadExcel} exports percentages of „Show values as“ columns with the format `0.0%`;

package/lib/table/state/table-state.if.d.ts

@@ -21,11 +21,12 @@ export type TableStateRowId = string | number;
  * | `selection` | selected rows, columns, cells or ranges | `autoRestoreSelectedState` |
  * | `headerGroups` | collapsed header groups | `autoRestoreHeaderGroupState` |
  * | `custom` | data of your application ({@link TableApi.setCustomState}) | `autoRestoreCustomState` |
+ * | `details` | expanded detail rows of master/detail (since 1.1.97) | `autoRestoreDetailState` |
  *
  * @category State
  * @since 1.1.92
  */
-export type TableStatePart = "columns" | "sort" | "scroll" | "tree" | "checked" | "selection" | "headerGroups" | "custom";
+export type TableStatePart = "columns" | "sort" | "scroll" | "tree" | "checked" | "selection" | "headerGroups" | "custom" | "details";
 /**
  * The state of a table as plain JSON: column layout, sorting, scroll position, tree, checked and selected rows,
  * header groups and data of your own. Get it with {@link TableApi.getState}, apply it with
@@ -72,6 +73,8 @@ export interface TableStateIf {
     tree?: TableTreeStateIf;
     /** The ids of the checked rows. */
     checkedRowIds?: TableStateRowId[];
+    /** The ids of the master rows with an expanded detail row (master/detail). @since 1.1.97 */
+    detailRowIds?: TableStateRowId[];
     /** The selection. */
     selection?: TableSelectionStateIf;
     /** The state of the header groups with a toggle. */

package/lib/table/state/table-state.service.d.ts

@@ -115,6 +115,10 @@ export declare class TableStateService {
     private computeScroll;
     private computeTree;
     private computeChecked;
+    /** The ids of the expanded master rows (master/detail, since 1.1.97); `undefined` without master/detail. */
+    private computeDetails;
+    /** Expands exactly the master rows with these ids (master/detail, since 1.1.97). */
+    private applyDetails;
     private computeSelection;
     /**
      * A cell range → ids and properties. A range to the last row / column (`MAX_SAFE_INTEGER`) has no `toRowId` /

package/lib/table/table-api.d.ts

@@ -1,3 +1,4 @@
+import { ResolvedTableDirection } from './rtl/table-direction.type.js';
 import { GeOverlayKind } from './overlay/ge-overlay-kind.type.js';
 import { TableStateIf, TableStatePart } from './state/table-state.if.js';
 import { SortState } from './data/common/sort-state.type.js';
@@ -52,6 +53,7 @@ import { CellRange } from './data/common/cell-range.js';
  * | columns | {@link autoResizeColumns}, {@link setColumnWidth}, {@link recalcColumnWidths}, {@link getColumnIndex} |
  * | tree | {@link expandAll}, {@link collapseAll}, {@link setRowExpanded} |
  * | state | {@link getState}, {@link applyState}, {@link resetState} (with {@link TableOptionsIf.autoRestoreOptions}) |
+ * | right-to-left | {@link getDirection} (with {@link TableOptionsIf.direction}) |
  * | lifecycle | {@link destroy} |
  *
  * @example
@@ -218,7 +220,8 @@ export declare class TableApi {
      * This method allows programmatic scrolling of the table viewport to exact pixel positions.
      * It delegates the scrolling operation to the underlying TableScope instance.
      *
-     * @param {number} px - The horizontal pixel coordinate to scroll to. Defaults to 0 (leftmost position).
+     * @param {number} px - The horizontal pixel coordinate to scroll to: px from the start of the row – 0 = the first
+     *   column (leftmost position; right-to-left the rightmost, see {@link TableOptionsIf.direction}). Defaults to 0.
      * @param {number} py - The vertical pixel coordinate to scroll to. Defaults to 0 (topmost position).
      * @returns {void}
      *
@@ -233,7 +236,7 @@ export declare class TableApi {
      * @example
      * // Scroll only vertically, keeping the current horizontal position
      * // (an omitted or undefined px means 0; for rows use scrollToIndex(-1, rowIndex))
-     * tableApi.scrollToPixel(tableApi.getTableScope().scrollViewport.scrollLeft, 300);
+     * tableApi.scrollToPixel(tableApi.getTableScope().getViewportScrollLeft(), 300);
      *
      * @example
      * // Example in a component that needs precise scrolling control
@@ -263,6 +266,23 @@ export declare class TableApi {
      * @see {@link ensureRowIsVisible} - For scrolling to make a specific row visible
      */
     scrollToPixel(px?: number, py?: number): void;
+    /**
+     * The writing direction of the table – {@link TableOptionsIf.direction} with `"auto"` already decided (from the page
+     * when the table was built).
+     *
+     * In `"rtl"` the first column is on the right; positions of the API stay "from the start": {@link scrollToPixel},
+     * {@link GeScrollEvent.scrollLeft} and the scroll part of {@link getState} count from the right edge.
+     *
+     * @returns {ResolvedTableDirection} `"ltr"` or `"rtl"`
+     *
+     * @example
+     * if (tableApi.getDirection() === "rtl") {
+     *   console.info("first column on the right");
+     * }
+     *
+     * @since 1.1.98
+     */
+    getDirection(): ResolvedTableDirection;
     /**
      * Scrolls the table to display the specified row and column indices at the top-left corner of the viewport.
      *
@@ -1538,6 +1558,107 @@ export declare class TableApi {
      * @since 1.1.96
      */
     cancelFill(): void;
+    /**
+     * Expands or collapses the detail row of a master row (master/detail, {@link TableOptionsIf.masterDetail}). The
+     * content is created when the detail row becomes visible; collapsing destroys it. Reports
+     * {@link EventListenerIf.onDetailExpandedChanged} (source `"api"`).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @param {boolean} expanded - `true` = expand, `false` = collapse
+     * @returns {boolean} false if nothing changed (no master row, already in that state, no master/detail)
+     *
+     * @example
+     * tableApi.setDetailExpanded(0, true);                  // the first shown row
+     * tableApi.setDetailExpanded(orders[42], true);         // a row object (also if it is filtered out)
+     *
+     * @since 1.1.97
+     */
+    setDetailExpanded(rowOrIndex: number | object, expanded: boolean): boolean;
+    /**
+     * Expands a collapsed or collapses an expanded detail row (master/detail).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} false if it is no master row (or no master/detail)
+     *
+     * @example
+     * tableApi.toggleDetail(3);   // e.g. from a button outside the table
+     *
+     * @since 1.1.97
+     */
+    toggleDetail(rowOrIndex: number | object): boolean;
+    /**
+     * True if the detail row of a master row is expanded (master/detail).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} whether it is expanded
+     *
+     * @example
+     * const open = tableApi.isDetailExpanded(3);
+     *
+     * @since 1.1.97
+     */
+    isDetailExpanded(rowOrIndex: number | object): boolean;
+    /**
+     * The master rows whose detail rows are expanded, in the order they were expanded (also rows that are filtered out).
+     *
+     * @returns {T[]} the row objects
+     *
+     * @example
+     * const openOrders = tableApi.getExpandedDetailRows<Order>().map(order => order.id);
+     *
+     * @since 1.1.97
+     */
+    getExpandedDetailRows<T = any>(): T[];
+    /**
+     * Expands the detail rows of all shown master rows. The contents are created only when they scroll into view, so this
+     * is cheap also for many rows. No event per row.
+     *
+     * @returns {number} the number of rows that were expanded
+     *
+     * @example
+     * document.querySelector("#expand-all")!.addEventListener("click", () => tableApi.expandAllDetails());
+     *
+     * @since 1.1.97
+     */
+    expandAllDetails(): number;
+    /**
+     * Collapses all detail rows (their contents are destroyed). No event per row.
+     *
+     * @returns {number} the number of rows that were collapsed
+     *
+     * @example
+     * tableApi.collapseAllDetails();
+     *
+     * @since 1.1.97
+     */
+    collapseAllDetails(): number;
+    /**
+     * Destroys the content of an expanded detail row and creates it again (`context.recreated` is `true`) – e.g. after
+     * the data it shows changed.
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} false if the row is not expanded
+     *
+     * @example
+     * order.items.push(newItem);
+     * tableApi.refreshDetail(order);
+     *
+     * @since 1.1.97
+     */
+    refreshDetail(rowOrIndex: number | object): boolean;
+    /**
+     * The container of a detail row (the element your `detailRenderer` renders into) – only while its content exists
+     * (it is created when the detail row becomes visible).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {HTMLDivElement | undefined} the container
+     *
+     * @example
+     * const notes = tableApi.getDetailElement(order)?.querySelector("textarea");
+     *
+     * @since 1.1.97
+     */
+    getDetailElement(rowOrIndex: number | object): HTMLDivElement | undefined;
     /**
      * Starts a batch edit: from now on edited and filled values are **collected** – shown in the cells (class
      * `ge-table-cell-pending`), but not written into your rows – until {@link commitBatchEdit} or

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

@@ -36,6 +36,7 @@ import { ResizeHandler } from './resize-handler.js';
 import { ExcelServiceIf } from './service/excel-service.if.js';
 import { ColumnDefIf } from './data/tablemodel/column/column-def.if.js';
 import { LiveAnnouncer } from './aria/live-announcer.js';
+import { GeDetailEventSource } from './data/common/event/ge-detail-event.js';
 import { FillHandleOptionsIf } from './fill/fill-handle-options.if.js';
 import { CellChangeIf, CellChangeSource } from './batch-edit/cell-change.if.js';
 import { CellValueChangeIf } from './batch-edit/cell-value-change.if.js';
@@ -124,6 +125,11 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     /** Last comparator passed to `sort()`; re-applied after filtering. Cleared by a header sort. */
     private lastSortCompareFn?;
     constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, domService: DomServiceIf, tableOptions: TableOptionsIf, eventListener: EventListenerIf, copyService?: CopyServiceIf, excelService?: ExcelServiceIf);
+    /**
+     * The options of a nested table (master/detail `ctx.createTable()`): as given; without an own `direction` in a
+     * right-to-left table an object that reads everything else from the given options (prototype) and adds `"rtl"`.
+     */
+    private nestedTableOptions;
     /** Time of the last Tab key press on the page (the host is focused right after it). */
     private lastTabKeyTime;
     /**
@@ -377,6 +383,69 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * new TableScope(hostDiv, newTableModel, new SimpleDomService(), new TableOptions(), new EventAdapter()).firstInit();
      */
     destroy(): void;
+    /**
+     * True if a DOM event comes from a detail row (master/detail) – e.g. from a nested table. The mouse, keyboard and
+     * pointer handlers of this table ignore such events.
+     *
+     * @param {Event} evt - an event while it is dispatched
+     * @returns {boolean} whether it comes from the detail layer
+     * @since 1.1.97
+     */
+    isEventInDetail(evt: Event): boolean;
+    /**
+     * Expands or collapses the detail row of a master row (see {@link TableApi.setDetailExpanded}).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @param {boolean} expanded - the new state
+     * @param {GeDetailEventSource} [source] - what changed it
+     * @returns {boolean} false if nothing changed
+     * @since 1.1.97
+     */
+    setDetailExpanded(rowOrIndex: unknown, expanded: boolean, source?: GeDetailEventSource): boolean;
+    /**
+     * Toggles the detail row of a master row (see {@link TableApi.toggleDetail}).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @param {GeDetailEventSource} [source] - what changed it
+     * @returns {boolean} false if it is no master row
+     * @since 1.1.97
+     */
+    toggleDetail(rowOrIndex: unknown, source?: GeDetailEventSource): boolean;
+    /**
+     * Called by {@link MasterDetailService} after detail rows were expanded or collapsed: new row positions and scroll
+     * height, repaint, event, announcement, table state.
+     *
+     * @param {unknown} row - the master row (`undefined` for several rows)
+     * @param {number} rowIndex - its display index (-1 for several rows or a row that is not shown)
+     * @param {boolean} expanded - the new state
+     * @param {GeDetailEventSource} source - what changed it
+     * @param {boolean} [emit] - false: no event (several rows at once)
+     * @param {boolean} [layoutUpdated] - true: the row layout was already updated for this one row
+     * @since 1.1.97
+     */
+    onDetailToggled(row: unknown, rowIndex: number, expanded: boolean, source: GeDetailEventSource, emit?: boolean, layoutUpdated?: boolean): void;
+    /**
+     * Called by {@link MasterDetailService} after a detail row with `detailHeight: "auto"` got a new height: new scroll
+     * height and repaint (the rows below move).
+     *
+     * @since 1.1.97
+     */
+    onDetailHeightChanged(): void;
+    /**
+     * The focus came back from a detail row (Shift+Tab): its master row gets the focus (same column).
+     *
+     * @param {number} rowIndex - display index of the master row
+     * @since 1.1.97
+     */
+    /**
+     * A detail row that holds the keyboard focus goes away (collapsed, destroyed, scrolled out of view): the host takes
+     * the focus and the master row becomes the focused row – without a repaint (the caller repaints).
+     *
+     * @param {number} rowIndex - display index of the master row (-1: only the host)
+     * @since 1.1.97
+     */
+    takeFocusFromDetail(rowIndex: number): void;
+    focusDetailMaster(rowIndex: number): void;
     /**
      * Returns `true` once {@link destroy} has been called.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.96",
+  "version": "1.1.98",
   "license": "MIT",
   "author": "Dr. Marc Kronberg <info@gui.expert> (https://gui.expert)",
   "repository": {