@guiexpert/table 1.1.105 → 1.1.106

package/lib/common/platform.d.ts

@@ -0,0 +1,10 @@
+/**
+ * macOS or not – the one place where the table asks for the platform (⌘ shortcuts, ⌥+letter types text,
+ * `aria-keyshortcuts`). Reads `navigator.platform` ("MacIntel", also iPadOS Safari with a keyboard); without a
+ * `navigator` (SSR, Node) `false`. Tests switch the platform here with `vi.spyOn(navigator, "platform", "get")`.
+ *
+ * `navigator.userAgentData.platform` is not used on purpose: only Chromium has it, and the result would be the same.
+ *
+ * @internal
+ */
+export declare function isMacPlatform(): boolean;

package/lib/table/data/tablemodel/areamodel/cover-grid-body-model.d.ts

@@ -7,7 +7,22 @@ import { SortItem } from '../../common/sort-item.js';
 import { AreaIdent } from '../area-ident.type.js';
 import { SorterService } from '../../../service/sorter.service.js';
 
-/** @category Area models */
+/**
+ * Body of a cover grid: `filteredItems[row * columns + column]` is the item of a tile (`getValueAt`), `columns` =
+ * `floor(width / coverWidth)`. `items` = all items, `filteredItems` = shown items (filter and `sort()` work on it).
+ * Change `coverWidth`/`coverHeight` or the items and call `tableApi.repaintHard()`.
+ *
+ * @example
+ * ```ts
+ * declare const grid: CoverGridTableModel<string>;
+ * const tiles = grid.bodyModel;
+ * tiles.items = ["new-1.jpg", "new-2.jpg"];
+ * tiles.filteredItems = tiles.items;   // or tableApi.externalFilterChanged() with a filter
+ * tableApi.repaintHard();
+ * ```
+ *
+ * @category Area models
+ */
 export declare class CoverGridBodyModel<T> implements AreaModelIf {
     items: T[];
     cellRenderer: CellRendererIf;

package/lib/table/data/tablemodel/cover-grid-table-model.d.ts

@@ -9,7 +9,20 @@ import { ColumnDefIf } from './column/column-def.if.js';
 import { Padding } from './padding.js';
 import { SelectionModelIf } from '../../selection/selection-model.if.js';
 
-/** @category Table model */
+/**
+ * Table model of a cover grid (created by {@link CoverGridFactory.createCoverGridModel}): items as tiles, the number of
+ * columns follows the width (`floor(width / coverWidth)`), header and footer are hidden. The data and the tile size
+ * live in {@link CoverGridBodyModel} (`tableModel.bodyModel`).
+ *
+ * @example
+ * ```ts
+ * declare const grid: CoverGridTableModel<{ title: string }>;
+ * const columns = grid.getColumnCount();
+ * tableApi.scrollToIndex(0, Math.floor(500 / columns));   // the row of item 500
+ * ```
+ *
+ * @category Table model
+ */
 export declare class CoverGridTableModel<T> implements TableModelIf {
     bodyModel: CoverGridBodyModel<T>;
     paddingTop: number;
@@ -39,6 +52,7 @@ export declare class CoverGridTableModel<T> implements TableModelIf {
     setColumnWidth(_columnIndex: number, width: number): void;
     recalcSize(_clientWidth: number): void;
     recalcPadding(): void;
+    /** No-op: the height follows from the item count, the column count and `coverHeight` – `repaintHard()` is enough. */
     recalcHeightAndPadding(): void;
     getPadding(): Padding;
     getContentHeightInPixel(): number;

package/lib/table/factory/cover-grid-factory.d.ts

@@ -2,8 +2,73 @@ import { CoverGridTableModel } from '../data/tablemodel/cover-grid-table-model.j
 import { CellRendererIf } from '../renderer/cell-render.if.js';
 import { TableOptionsIf } from '../data/options/table-options.if.js';
 
-/** @category Table model */
+/**
+ * Creates cover grids: a flat array of items shown as tiles (book covers, photos, products) – as many per row as fit
+ * into the width of the table (`floor(width / coverWidth)`), without header and footer. Only the visible rows are
+ * rendered, like in every GuiExpert Table; filter (`externalFilterFunction`), `sort()` and the scroll position work as
+ * usual. Guide: instructions.md 5.10, showcase https://gui.expert/showcase/covergrid/run.
+ *
+ * @example
+ * ```ts
+ * interface Book { title: string; }
+ * declare const books: Book[];
+ *
+ * const renderer: CellRendererIf = {
+ *   render(cellDiv: HTMLDivElement, _r: number, _c: number, _a: AreaIdent, _m: AreaModelIf, book: any) {
+ *     if (book) cellDiv.textContent = (book as Book).title;   // the item of this tile (undefined after the last one)
+ *     return undefined;
+ *   }
+ * };
+ * const gridModel = CoverGridFactory.createCoverGridModel(books, renderer, 160, 240);
+ * const gridOptions = CoverGridFactory.createCoverGrisDefaultOptions(240, () => "books");
+ * const gridApi = new TableScope(host, gridModel, new SimpleDomService(), gridOptions, new EventAdapter())
+ *   .firstInit()
+ *   .getApi();
+ * ```
+ *
+ * @category Table model
+ */
 export declare class CoverGridFactory {
+    /**
+     * Creates the model of a cover grid.
+     *
+     * @param items - the items, one per tile (the renderer gets the item as `cellValue`)
+     * @param cellRenderer - draws one tile into the cell `<div>`
+     * @param coverWidth - width of a tile in px (default 200) – change it later via `bodyModel.coverWidth` + `repaintHard()`
+     * @param coverHeight - height of a tile in px (default 300)
+     * @param width - initial width of the grid; the table sets the width of its host on start and after a resize
+     * @param firstRowPaddingTop - extra height of the first row in px (room above the first tiles, e.g. for a toolbar)
+     * @returns the table model; `tableModel.bodyModel` holds `items`, `filteredItems`, `coverWidth`, `coverHeight`
+     *
+     * @example
+     * ```ts
+     * declare const renderer: CellRendererIf;
+     * const gridModel = CoverGridFactory.createCoverGridModel(["a.jpg", "b.jpg", "c.jpg"], renderer, 120, 180);
+     * // bigger tiles – no new model:
+     * gridModel.bodyModel.coverWidth = 200;
+     * gridModel.bodyModel.coverHeight = 300;
+     * tableApi.repaintHard();
+     * ```
+     */
     static createCoverGridModel<T>(items: T[], cellRenderer: CellRendererIf, coverWidth?: number, coverHeight?: number, width?: number, firstRowPaddingTop?: number): CoverGridTableModel<T>;
+    /**
+     * Options for a cover grid: no borders and separators, no row or column hover, header and footer height 0, and the
+     * scroll position restored under the key of `getStorageKeyFn` (`localStorage`). (The name has a typo – kept for
+     * compatibility.)
+     *
+     * @param defaultRowHeight - the height of a tile (`coverHeight`)
+     * @param getStorageKeyFn - storage key of the scroll position (default `"CoverGrid"`)
+     * @returns new options – add your own fields with a spread
+     *
+     * @example
+     * ```ts
+     * let photoFilter = "";
+     * const gridOptions: TableOptionsIf = {
+     *   ...CoverGridFactory.createCoverGrisDefaultOptions(240, () => "photos"),
+     *   externalFilterFunction: (photo: { name: string }) => photo.name.includes(photoFilter),
+     *   shortcutActionsDisabled: true
+     * };
+     * ```
+     */
     static createCoverGrisDefaultOptions(defaultRowHeight: number, getStorageKeyFn?: () => string): TableOptionsIf;
 }

package/lib/table/mouse-handler.d.ts

@@ -27,6 +27,10 @@ export declare class MouseHandler {
     private mouseDown;
     private repaintAfterMouseUp;
     private dragging;
+    /** Counts the drags: a frame callback of a drag that is over (a new one started) does nothing. */
+    private dragGeneration;
+    /** The end of the last drag, until its frame ran – a new mousedown handles it at once (see {@link flushDraggingEnd}). */
+    private pendingDraggingEnd?;
     constructor(tableScope: TableScope);
     /**
      * Handles the "contextmenu" event.
@@ -76,7 +80,8 @@ export declare class MouseHandler {
     private onMouseMove;
     private onMouseUp;
     private mouseDraggingOnFrame;
-    private mouseDraggingEndOnFrame;
+    /** Handles the end of the last drag now (in its frame, or earlier when the next mousedown comes first). */
+    private flushDraggingEnd;
     private mouseMoveOnFrame;
     /** A mouse event on a blocking loading overlay ({@link TableOverlay.isEventBlocked}): the table ignores it. */
     private isBlocked;

package/lib/table/sheet-editing/editors/select-cell-editor.d.ts

@@ -17,6 +17,8 @@ import { ValueLabelIf } from '../../data/common/value-label.if.js';
 export declare class SelectCellEditor implements CellEditorIf {
     protected readonly options: ValueLabelIf[];
     private select?;
+    /** The text of the cell when the editor opened: "nothing chosen" counts as unchanged (since 1.1.106). */
+    private startText;
     private readonly abort;
     constructor(options: ValueLabelIf[]);
     /**
@@ -28,6 +30,12 @@ export declare class SelectCellEditor implements CellEditorIf {
     static create(values: string[]): SelectCellEditor;
     open(container: HTMLDivElement, ctx: CellEditorContextIf): void;
     getValue(): unknown;
+    /**
+     * The chosen value as text; with nothing chosen (the cell's value is not in the list) the start text, so that
+     * Enter without a choice writes nothing (before 1.1.106 it emptied the cell).
+     *
+     * @returns {string} the text
+     */
     getText(): string;
     focus(): void;
     getFocusElement(): HTMLElement | undefined;

package/package.json

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