@adecore/database 0.0.1 → 0.16.0-beta.0

package/src/grid/focused-value.ts

@@ -0,0 +1,23 @@
+import { valueOfCell, type Cell, type Value } from '../protocol/index.ts';
+import type { Shown } from './display.ts';
+
+/* The whole value of a cell, or `undefined` when it is only a preview (or a pending DEFAULT, which holds no value). */
+export const wholeValueOf = (cell: Shown): Value | undefined =>
+    cell !== null && typeof cell === 'object' && cell.kind === 'default' ? undefined : valueOfCell(cell as Cell);
+
+/* What a cell holds as far as it goes: the whole value, or the preview of a long text or a binary value. */
+export const previewValueOf = (cell: Shown): Value => {
+    const whole = wholeValueOf(cell);
+    if (whole !== undefined) {
+        return whole;
+    }
+    if (cell !== null && typeof cell === 'object') {
+        if (cell.kind === 'longText') {
+            return cell.preview;
+        }
+        if (cell.kind === 'binary') {
+            return { kind: 'binary', hex: cell.hex };
+        }
+    }
+    return null;
+};

package/src/grid/layout.ts

@@ -0,0 +1,91 @@
+/* The measures of the grid, in whole pixels. Row and header heights are steps of the 4px spacing scale. */
+export const ROW_HEIGHT = 28;
+export const HEADER_HEIGHT = 32;
+export const MIN_COLUMN_WIDTH = 64;
+export const MAX_COLUMN_WIDTH = 320;
+/* How far a drag may widen a column; the estimate stops at `MAX_COLUMN_WIDTH`, a person may go further. */
+export const MAX_RESIZED_WIDTH = 1200;
+/* How wide fitting a column to its content may make it. */
+export const MAX_FIT_WIDTH = 640;
+export const OVERSCAN_ROWS = 6;
+/* Two presses on a resize handle this close are a double click. */
+export const DOUBLE_CLICK_MS = 350;
+/* What a viewport is taken to be until it is measured, so a first paint already holds rows. */
+export const FALLBACK_VIEWPORT_HEIGHT = 600;
+
+/* A glyph of the 13px mono face is 7.8px wide; a whole pixel on the safe side. */
+const CHARACTER_WIDTH = 8;
+const CELL_PADDING = 24;
+const KEY_ICON_ROOM = 18;
+const GUTTER_MIN_WIDTH = 40;
+const SAMPLE_ROWS = 50;
+/* The arrow and the position number a sorted header carries after its name. */
+const SORT_ROOM = 24;
+
+export interface VisibleRange {
+    /* Index of the first row to draw. */
+    readonly start: number;
+    /* One past the last row to draw. */
+    readonly end: number;
+}
+
+/* The rows that touch a viewport of `height` pixels starting `top` pixels into the rows, plus `overscan` rows on both sides. */
+export const visibleRange = (top: number, height: number, rowHeight: number, count: number, overscan: number): VisibleRange => {
+    if (count <= 0 || height <= 0) {
+        return { start: 0, end: 0 };
+    }
+    const first = Math.floor(Math.max(0, top) / rowHeight);
+    const last = Math.ceil(Math.max(0, top + height) / rowHeight);
+    return { start: Math.max(0, Math.min(first, count) - overscan), end: Math.min(count, last + overscan) };
+};
+
+/*
+ * Where to scroll so that an item at `start` that is `size` long is in view. `leading` is the part of
+ * the viewport a sticky header or gutter covers. Returns `scroll` itself when the item is already visible.
+ */
+export const scrollToReveal = (start: number, size: number, scroll: number, viewport: number, leading: number): number => {
+    if (start < scroll + leading) {
+        return Math.max(0, start - leading);
+    }
+    if (start + size > scroll + viewport) {
+        return Math.max(0, start + size - viewport);
+    }
+    return scroll;
+};
+
+/* The left edge of every column, counted from the first one. */
+export const columnOffsets = (widths: readonly number[]): number[] => {
+    let offset = 0;
+    return widths.map((width) => {
+        const left = offset;
+        offset += width;
+        return left;
+    });
+};
+
+/* Wide enough for the largest row number, never narrower than `GUTTER_MIN_WIDTH`. */
+export const gutterWidth = (rowCount: number): number => Math.max(GUTTER_MIN_WIDTH, String(Math.max(rowCount, 1)).length * CHARACTER_WIDTH + CELL_PADDING);
+
+export const clampColumnWidth = (width: number): number => Math.max(MIN_COLUMN_WIDTH, Math.min(Math.ceil(width), MAX_COLUMN_WIDTH));
+
+/* From the longest text among the header and the first rows. `keyed` makes room for the key icon in front of the name. */
+export const estimateColumnWidth = (header: string, samples: readonly string[], keyed: boolean): number => {
+    const body = samples.slice(0, SAMPLE_ROWS).reduce((longest, text) => Math.max(longest, text.length), 0);
+    const named = header.length * CHARACTER_WIDTH + (keyed ? KEY_ICON_ROOM : 0) + SORT_ROOM;
+    return clampColumnWidth(Math.max(body * CHARACTER_WIDTH, named) + CELL_PADDING);
+};
+
+/* Wide enough for the header and every text of the column, up to `MAX_FIT_WIDTH`. */
+export const fitColumnWidth = (header: string, texts: readonly string[], keyed: boolean): number => {
+    const body = texts.reduce((longest, text) => Math.max(longest, text.length), 0) * CHARACTER_WIDTH;
+    const named = header.length * CHARACTER_WIDTH + (keyed ? KEY_ICON_ROOM : 0) + SORT_ROOM;
+    return Math.max(MIN_COLUMN_WIDTH, Math.min(Math.ceil(Math.max(body, named) + CELL_PADDING), MAX_FIT_WIDTH));
+};
+
+export const isDoubleClick = (previous: number | null, now: number): boolean => previous !== null && now - previous <= DOUBLE_CLICK_MS;
+
+/*
+ * The estimated widths of a new page, never narrower than they were. A page with longer content widens
+ * a column; a page with shorter content leaves it, so a sort does not make columns jump.
+ */
+export const growWidths = (previous: readonly number[], next: readonly number[]): number[] => next.map((width, index) => Math.max(width, previous[index] ?? 0));

package/src/grid/navigation.ts

@@ -0,0 +1,74 @@
+export interface CellPosition {
+    readonly row: number;
+    readonly column: number;
+}
+
+export interface GridSize {
+    readonly rows: number;
+    readonly columns: number;
+    /* How many rows a PageUp or PageDown moves. */
+    readonly page: number;
+}
+
+export interface NavigationKey {
+    readonly key: string;
+    readonly shiftKey: boolean;
+    /* The platform's own modifier. */
+    readonly mod: boolean;
+}
+
+/* Keys that, with no cell focused yet, only put the focus on the first one. */
+const ENTERING_KEYS: ReadonlySet<string> = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'PageUp', 'PageDown', 'Tab']);
+
+const clamp = (value: number, max: number): number => Math.max(0, Math.min(value, max - 1));
+
+/*
+ * Where a navigation key takes the focus, or `null` when the key moves nothing and the browser should
+ * keep it: that is also how Tab leaves the grid at its first and last cell.
+ */
+export const moveFocus = (from: CellPosition | null, input: NavigationKey, size: GridSize): CellPosition | null => {
+    if (size.rows === 0 || size.columns === 0) {
+        return null;
+    }
+    if (from === null && ENTERING_KEYS.has(input.key)) {
+        return { row: 0, column: 0 };
+    }
+    const lastRow = size.rows - 1;
+    const lastColumn = size.columns - 1;
+    const start = from ?? { row: 0, column: 0 };
+    const row = clamp(start.row, size.rows);
+    const column = clamp(start.column, size.columns);
+
+    switch (input.key) {
+        case 'ArrowUp':
+            return { row: clamp(row - 1, size.rows), column };
+        case 'ArrowDown':
+            return { row: clamp(row + 1, size.rows), column };
+        case 'ArrowLeft':
+            return { row, column: clamp(column - 1, size.columns) };
+        case 'ArrowRight':
+            return { row, column: clamp(column + 1, size.columns) };
+        case 'PageUp':
+            return { row: clamp(row - size.page, size.rows), column };
+        case 'PageDown':
+            return { row: clamp(row + size.page, size.rows), column };
+        case 'Home':
+            return { row: input.mod ? 0 : row, column: 0 };
+        case 'End':
+            return { row: input.mod ? lastRow : row, column: lastColumn };
+        case 'Tab': {
+            if (input.shiftKey) {
+                if (column > 0) {
+                    return { row, column: column - 1 };
+                }
+                return row > 0 ? { row: row - 1, column: lastColumn } : null;
+            }
+            if (column < lastColumn) {
+                return { row, column: column + 1 };
+            }
+            return row < lastRow ? { row: row + 1, column: 0 } : null;
+        }
+        default:
+            return null;
+    }
+};

package/src/grid/row-selection.ts

@@ -0,0 +1,35 @@
+export interface RowSelection {
+    readonly selected: ReadonlySet<string>;
+    /* The row a Shift-click extends from. */
+    readonly anchor: number;
+}
+
+export interface RowClick {
+    readonly shiftKey: boolean;
+    readonly mod: boolean;
+}
+
+/*
+ * The selection after a click on the gutter of `index`: a plain click selects that row alone, Mod
+ * toggles it, and Shift selects everything from the anchor to it.
+ */
+export const selectRow = (keys: readonly string[], current: ReadonlySet<string>, anchor: number, index: number, click: RowClick): RowSelection => {
+    const key = keys[index];
+    if (key === undefined) {
+        return { selected: current, anchor };
+    }
+    if (click.shiftKey && anchor >= 0 && anchor < keys.length) {
+        const from = Math.min(anchor, index);
+        const to = Math.max(anchor, index);
+        const range = keys.slice(from, to + 1);
+        return { selected: new Set(click.mod ? [...current, ...range] : range), anchor };
+    }
+    if (click.mod) {
+        const next = new Set(current);
+        if (!next.delete(key)) {
+            next.add(key);
+        }
+        return { selected: next, anchor: index };
+    }
+    return { selected: new Set([key]), anchor: index };
+};

package/src/grid/sort.ts

@@ -0,0 +1,12 @@
+import type { ColumnSort, SortDirection } from '../sql.ts';
+
+export type GridSort = ColumnSort;
+
+/* The column as the only sort, in a direction a menu picked. */
+export const sortOnly = (column: string, direction: SortDirection): GridSort[] => [{ column, direction }];
+
+/* The sort of a column and its place among the sorts counted from one, or `null` when it is not sorted. */
+export const sortStateOf = (sorts: readonly GridSort[], column: string): { direction: SortDirection; position: number } | null => {
+    const index = sorts.findIndex((sort) => sort.column === column);
+    return index < 0 ? null : { direction: sorts[index]!.direction, position: index + 1 };
+};

package/src/grid/types.ts

@@ -0,0 +1,59 @@
+import type { ColumnInfo, ResultColumn } from '../protocol/index.ts';
+import type { Shown } from './display.ts';
+
+/* A column of a result, with what the grid draws from its table when it comes from one. */
+export interface GridColumn extends ResultColumn {
+    readonly primaryKey?: boolean;
+    /* `false` makes Set NULL unavailable; unknown (an expression) leaves it open. */
+    readonly nullable?: boolean;
+    /* A column no cell of which can be edited, such as a generated one. */
+    readonly readOnly?: boolean;
+    /* The default as an SQL expression, for the hint on the header. */
+    readonly defaultValue?: string | null;
+    /* A cloned row leaves this column to the server. */
+    readonly autoIncrement?: boolean;
+}
+
+export type GridRowState = 'inserted' | 'deleted';
+
+export interface GridRow {
+    /* Stable while the row is on the grid, since the selection and the edits are kept by it. */
+    readonly key: string;
+    /* The number in the gutter; `null` for a row that does not exist yet. */
+    readonly number: number | null;
+    readonly cells: readonly Shown[];
+    readonly state?: GridRowState;
+    /* Indexes of the cells with a pending edit. */
+    readonly edited?: ReadonlySet<number>;
+    /* A row that cannot be edited even though the grid can, such as one whose key is only a preview. */
+    readonly locked?: boolean;
+}
+
+/* Builds the column of a table from the result column and the structure's column of the same name. */
+export const gridColumnOf = (column: ResultColumn, info: ColumnInfo | undefined, primaryKey: readonly string[]): GridColumn => ({
+    ...column,
+    primaryKey: primaryKey.includes(column.name),
+    nullable: info?.nullable,
+    readOnly: info?.generated === true,
+    defaultValue: info?.defaultValue,
+    autoIncrement: info?.autoIncrement
+});
+
+/* The cell that holds the focus, named by its row's key and its column's index in the columns the grid was given. */
+export interface FocusedCell {
+    readonly rowKey: string;
+    readonly column: number;
+}
+
+/* What a menu item added to the grid's context menu acts on. */
+export interface GridMenuContext {
+    /* The selected rows when the row under the pointer is one of them, else that row alone. */
+    readonly rowKeys: readonly string[];
+    /* The cell under the pointer; `null` when the menu opened on a row number. */
+    readonly cell: FocusedCell | null;
+}
+
+/* A column to pick and bring into view, named by its index in the columns the grid was given. */
+export interface ColumnRequest {
+    readonly column: number;
+}

package/src/host/helper-path.ts

@@ -0,0 +1,41 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, sep } from 'node:path';
+
+/*
+ * Finds the prebuilt helper that npm installed for this machine, in the `@adecore/database-<platform>-<arch>`
+ * package, or null when there is none: an unsupported platform, or an install with optional dependencies off.
+ *
+ * A binary cannot run from inside an Electron archive. The path is mapped from `app.asar` to
+ * `app.asar.unpacked`, so the app must unpack the packages (electron-builder: `asarUnpack` with
+ * `node_modules/@adecore/database-*` followed by `/**`).
+ */
+export interface HelperPathOptions {
+    /* `process.platform` when left out. */
+    readonly platform?: string;
+    /* `process.arch` when left out. */
+    readonly arch?: string;
+    /* Resolves a package specifier to a file; the module resolution of this file when left out. */
+    readonly resolve?: (specifier: string) => string;
+    readonly exists?: (path: string) => boolean;
+}
+
+export const helperPath = ({
+    platform = process.platform,
+    arch = process.arch,
+    resolve = (specifier) => createRequire(import.meta.url).resolve(specifier),
+    exists = existsSync
+}: HelperPathOptions = {}): string | null => {
+    let manifest: string;
+
+    try {
+        manifest = resolve(`@adecore/database-${platform}-${arch}/package.json`);
+    } catch {
+        return null;
+    }
+
+    const binary = join(dirname(manifest), 'bin', platform === 'win32' ? 'adecore-database.exe' : 'adecore-database');
+    const unpacked = binary.replace(`.asar${sep}`, `.asar.unpacked${sep}`);
+
+    return exists(unpacked) ? unpacked : null;
+};