vastgrid 0.1.0 → 0.2.0

package/src/canvas/hooks.ts

@@ -0,0 +1,61 @@
+/**
+ * What a host adds to the drawing of the grid through props (§5.1 of the specification: functions are not state, and
+ * they win over the document's formats and styles), and the column groups of the header.
+ */
+import type { Column, JsonValue } from "vastgrid-spec";
+import type { GridTheme } from "./theme.js";
+
+/** A cell of the view that the grid shows. */
+export interface GridCell {
+  /** The view position of its row. */
+  row: number;
+  column: Column;
+  value: JsonValue;
+  /** The text the grid shows: by the column's format, or the text form (§2.4). */
+  text: string;
+}
+
+/** The colors of a cell, and what they mean for screen readers. */
+export interface CellStyle {
+  color?: string;
+  background?: string;
+  description?: string;
+}
+
+/** What a cell does when it is clicked or Space is pressed on it: a link goes somewhere, a button acts in place. */
+export interface CellAction {
+  kind: "link" | "button";
+  /** The name for screen readers, instead of the cell's text. */
+  label?: string;
+  /** The CSS cursor over the cell; `pointer` by default. */
+  cursor?: string;
+}
+
+/** The cell, its box and the canvas, for `drawCell`. */
+export interface DrawCellArgs extends GridCell {
+  /** The canvas in CSS pixels, with the cell font, `textBaseline = "middle"` and the column's alignment. */
+  ctx: CanvasRenderingContext2D;
+  rect: { x: number; y: number; width: number; height: number };
+  style: CellStyle | null;
+  theme: GridTheme;
+  /** Draws the cell as the grid does. */
+  drawDefault(): void;
+}
+
+export interface CellHooks {
+  /** The text of a cell instead of the grid's; null or undefined keeps the grid's. */
+  cellText?: (cell: GridCell) => string | null | undefined;
+  /** The colors of a cell instead of the column's style rules; null or undefined keeps them. */
+  cellStyle?: (cell: GridCell) => CellStyle | null | undefined;
+  /** Draws a cell on the canvas; the canvas's state is restored afterwards. */
+  drawCell?: (args: DrawCellArgs) => void;
+  /** Makes cells links or buttons; null or undefined for plain cells. */
+  cellAction?: (cell: GridCell) => CellAction | null | undefined;
+}
+
+/** A group of columns named in a header row above the column names; nested groups add rows. */
+export interface ColumnGroup {
+  name: string;
+  /** Column names of the view, and groups. */
+  children: (string | ColumnGroup)[];
+}

package/src/canvas/keys.ts

@@ -0,0 +1,96 @@
+import type { GridCommand } from "vastgrid-spec";
+
+/** The members of a keyboard event that the grid reads. */
+export interface KeyInput {
+  key: string;
+  shiftKey: boolean;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+}
+
+/** Whether the platform's primary modifier is ⌘ (Apple platforms) rather than Ctrl. */
+export function isApple(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const platform = (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform;
+  return /mac|iphone|ipad|ipod/i.test(platform ?? navigator.platform ?? "");
+}
+
+const ARROWS: Record<string, "up" | "down" | "left" | "right"> = {
+  ArrowUp: "up",
+  ArrowDown: "down",
+  ArrowLeft: "left",
+  ArrowRight: "right",
+};
+
+/**
+ * The command of a key on the grid (§6.4 of the specification, the grid pattern of the ARIA Authoring
+ * Practices): arrows move, with Shift extend and with the primary modifier jump to the end; Page Up and Page
+ * Down move by a page; Home and End go to the first and last column (with the modifier, also row); Tab and
+ * Enter walk through the selection; the modifier and A selects everything. Delete and Backspace clear the selected
+ * cells, F2 edits the active cell, the modifier and Z undoes (with Shift, or Ctrl+Y off Apple platforms,
+ * redoes), the modifier and D or R fills down or right, and the modifier and S saves. Null for other keys: a key that types text starts editing (`typesText`).
+ */
+export function keyCommand(event: KeyInput, apple: boolean): GridCommand | null {
+  const primary = apple ? event.metaKey : event.ctrlKey;
+  if (event.altKey) return null;
+  const flags = (extend: boolean, jump: boolean) => ({
+    ...(extend ? { extend: true } : {}),
+    ...(jump ? { jump: true } : {}),
+  });
+  const direction = ARROWS[event.key];
+  if (direction) return { command: "move", direction, ...flags(event.shiftKey, primary) };
+  switch (event.key) {
+    case "PageUp":
+    case "PageDown":
+      return {
+        command: "move",
+        direction: event.key === "PageUp" ? "up" : "down",
+        page: true,
+        ...flags(event.shiftKey, false),
+      };
+    case "Home":
+      return { command: "move.home", ...flags(event.shiftKey, primary) };
+    case "End":
+      return { command: "move.end", ...flags(event.shiftKey, primary) };
+    case "Tab":
+      return primary ? null : { command: "advance", axis: "column", ...(event.shiftKey ? { back: true } : {}) };
+    case "Enter":
+      return primary ? null : { command: "advance", axis: "row", ...(event.shiftKey ? { back: true } : {}) };
+    case "a":
+    case "A":
+      return primary && !event.shiftKey ? { command: "select.all" } : null;
+    case "Delete":
+    case "Backspace":
+      return primary ? null : { command: "edit.clear" };
+    case "F2":
+      return { command: "edit.begin" };
+    case "z":
+    case "Z":
+      if (!primary) return null;
+      return event.shiftKey ? { command: "history.redo" } : { command: "history.undo" };
+    case "y":
+    case "Y":
+      return primary && !apple ? { command: "history.redo" } : null;
+    case "s":
+    case "S":
+      return primary && !event.shiftKey ? { command: "save" } : null;
+    // Fill down and right from the first row or column of the selection (§6.5).
+    case "d":
+    case "D":
+      return primary && !event.shiftKey ? { command: "edit.fill", direction: "down" } : null;
+    case "r":
+    case "R":
+      return primary && !event.shiftKey ? { command: "edit.fill", direction: "right" } : null;
+    default:
+      return null;
+  }
+}
+
+/** Whether a key types text, a character or the start of an IME composition, which starts editing the cell. */
+export function typesText(event: KeyInput & { keyCode?: number; isComposing?: boolean }): boolean {
+  if (event.key === "Process" || event.keyCode === 229 || event.isComposing === true) return true;
+  // AltGr gives Ctrl+Alt on Windows; Option gives characters on Apple platforms.
+  const shortcut = event.metaKey || (event.ctrlKey && !event.altKey);
+  return [...event.key].length === 1 && event.key !== " " && !shortcut;
+}

package/src/canvas/layout.ts

@@ -0,0 +1,77 @@
+/** Positions of columns laid out side by side. Lookups are O(1) by index and O(log n) by x. */
+export class ColumnLayout {
+  /** `offsets[i]` is the left edge of column `i`; `offsets[count]` is the total width. */
+  readonly offsets: Float64Array;
+
+  constructor(widths: ArrayLike<number>) {
+    this.offsets = new Float64Array(widths.length + 1);
+    for (let index = 0; index < widths.length; index++) {
+      this.offsets[index + 1] = this.offsets[index] + Math.max(0, widths[index]);
+    }
+  }
+
+  get count() {
+    return this.offsets.length - 1;
+  }
+
+  get total() {
+    return this.offsets[this.count];
+  }
+
+  left(index: number) {
+    return this.offsets[index];
+  }
+
+  right(index: number) {
+    return this.offsets[index + 1];
+  }
+
+  width(index: number) {
+    return this.offsets[index + 1] - this.offsets[index];
+  }
+
+  /** The column containing `x`, clamped to the existing columns. Returns -1 when there are none. */
+  indexAt(x: number): number {
+    const count = this.count;
+    if (count === 0) return -1;
+    if (x <= 0) return 0;
+    if (x >= this.total) return count - 1;
+    let low = 0;
+    let high = count - 1;
+    while (low < high) {
+      const middle = (low + high + 1) >> 1;
+      if (this.offsets[middle] <= x) low = middle;
+      else high = middle - 1;
+    }
+    return low;
+  }
+}
+
+/** Where a column is frozen: at the left, at the right, or not (`null`, it scrolls). */
+export type ColumnPin = "left" | "right" | null;
+
+/**
+ * Share of the body's width (without the row header) that frozen columns may take together. Columns
+ * frozen beyond it scroll with the others until the grid is wide enough again, so that the scrolling
+ * columns always keep some room.
+ */
+const MAX_FROZEN_SHARE = 0.75;
+
+/**
+ * The columns drawn frozen at each side: the first `left` and the last `right` columns of `layout`, fewer
+ * when together they are wider than `MAX_FROZEN_SHARE` of `available` (the body's width). Columns frozen
+ * at the right give way first, then those at the left, each from the scrolling side. With an unknown
+ * width (`available` 0 or less) every frozen column stays frozen.
+ */
+export function fitFrozen(layout: ColumnLayout, left: number, right: number, available: number) {
+  const count = layout.count;
+  let fittedLeft = Math.max(0, Math.min(Math.floor(left), count));
+  let fittedRight = Math.max(0, Math.min(Math.floor(right), count - fittedLeft));
+  if (available > 0) {
+    const limit = available * MAX_FROZEN_SHARE;
+    const width = () => layout.left(fittedLeft) + layout.total - layout.left(count - fittedRight);
+    while (fittedRight > 0 && width() > limit) fittedRight--;
+    while (fittedLeft > 0 && width() > limit) fittedLeft--;
+  }
+  return { left: fittedLeft, right: fittedRight };
+}

package/src/canvas/scroll.ts

@@ -0,0 +1,120 @@
+/**
+ * Browsers cap the size of an element (about 16.7M px in Chromium, 17.9M px in Firefox, 33.5M px
+ * in Safari). With 24 px rows that is well under a million rows, so a native scrollbar cannot
+ * cover the content of a large table. `ScrollAxis` maps a native scroll position, kept below
+ * `maxNative`, onto a much larger virtual position:
+ *
+ * - Small movements (wheel, trackpad, arrow keys) move the virtual position by the same amount, so
+ *   scrolling feels exactly like a normal page at any depth.
+ * - Large jumps (dragging the thumb, clicking the track) and the two ends map proportionally, so the
+ *   scrollbar still tells where you are and reaches the first and the last row.
+ *
+ * Content smaller than `maxNative` is never scaled.
+ */
+const MAX_NATIVE_SCROLL = 8_000_000;
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max);
+}
+
+export class ScrollAxis {
+  private contentSize = 0;
+  private viewportSize = 0;
+  private nativeSize = 0;
+  private virtual = 0;
+  private lastNative = 0;
+  private expectedNative: number | null = null;
+  private expectedVirtual = 0;
+
+  constructor(private readonly maxNative = MAX_NATIVE_SCROLL) {}
+
+  /** Updates the sizes and returns the size to give the native scroll content. */
+  resize(contentSize: number, viewportSize: number): number {
+    this.contentSize = Math.max(0, contentSize);
+    this.viewportSize = Math.max(0, viewportSize);
+    this.nativeSize = Math.min(this.contentSize, this.maxNative);
+    this.virtual = clamp(this.virtual, 0, this.virtualRange);
+    return this.nativeSize;
+  }
+
+  /** Whether the native position is mapped (the content is larger than `maxNative`). */
+  get scaled() {
+    return this.contentSize > this.maxNative;
+  }
+
+  get virtualRange() {
+    return Math.max(0, this.contentSize - this.viewportSize);
+  }
+
+  get nativeRange() {
+    return Math.max(0, this.nativeSize - this.viewportSize);
+  }
+
+  /** The current virtual position. */
+  get position() {
+    return this.virtual;
+  }
+
+  /** The native position that corresponds to the current state. */
+  get native() {
+    return this.lastNative;
+  }
+
+  private jumpThreshold() {
+    return Math.max(this.viewportSize * 2, 1000);
+  }
+
+  /** Handles a native scroll event and returns the new virtual position. */
+  onNativeScroll(nativePosition: number): number {
+    const nativeRange = this.nativeRange;
+    const native = clamp(nativePosition, 0, nativeRange);
+    if (this.expectedNative !== null && Math.abs(native - this.expectedNative) <= 1) {
+      // The event caused by `scrollTo`. Browsers may round the position, so keep the requested one.
+      this.expectedNative = null;
+      this.lastNative = native;
+      this.virtual = this.expectedVirtual;
+      return this.virtual;
+    }
+    this.expectedNative = null;
+    if (!this.scaled) {
+      this.lastNative = native;
+      this.virtual = native;
+      return native;
+    }
+    const delta = native - this.lastNative;
+    this.lastNative = native;
+    const virtualRange = this.virtualRange;
+    if (native <= 0) this.virtual = 0;
+    else if (native >= nativeRange) this.virtual = virtualRange;
+    else if (Math.abs(delta) > this.jumpThreshold()) this.virtual = (native / nativeRange) * virtualRange;
+    else this.virtual = clamp(this.virtual + delta, 0, virtualRange);
+    return this.virtual;
+  }
+
+  /**
+   * Moves to a virtual position and returns the native position to assign to the scroll element.
+   * Nearby targets move the native position by the same amount, so a following wheel scroll
+   * continues smoothly; distant targets map proportionally.
+   */
+  scrollTo(target: number): number {
+    const virtualRange = this.virtualRange;
+    const virtual = clamp(target, 0, virtualRange);
+    let native: number;
+    if (!this.scaled) {
+      native = virtual;
+    } else {
+      const nativeRange = this.nativeRange;
+      const delta = virtual - this.virtual;
+      const local = this.lastNative + delta;
+      if (virtual === 0) native = 0;
+      else if (virtual === virtualRange) native = nativeRange;
+      else if (Math.abs(delta) <= this.jumpThreshold() && local > 0 && local < nativeRange) native = local;
+      else native = virtualRange === 0 ? 0 : (virtual / virtualRange) * nativeRange;
+    }
+    this.virtual = virtual;
+    this.expectedVirtual = virtual;
+    this.expectedNative = native;
+    this.lastNative = native;
+    return native;
+  }
+}

package/src/canvas/text.ts

@@ -0,0 +1,155 @@
+const ELLIPSIS = "…";
+const MAX_ENTRIES = 20_000;
+/** Characters that do not start a line (closing brackets, Japanese punctuation and small kana). */
+const NO_START = new Set(
+  ")]}>,.!?:;%、。，．・：；？！‼⁇⁈⁉ー〜～）」』】〕〉》｝〙〗〟’”ゝゞヽヾ々〻ぁぃぅぇぉっゃゅょゎゕゖァィゥェォッャュョヮヵヶㇰㇱㇲㇳㇴㇵㇶㇷㇸㇹㇺㇻㇼㇽㇾㇿ",
+);
+/** Characters that do not end a line (opening brackets). */
+const NO_END = new Set("([{<（「『【〔〈《｛〘〖〝‘“");
+
+/** Whether a UTF-16 code unit belongs to a script written without spaces (CJK, kana, Hangul, full width). */
+function isWide(code: number) {
+  return (
+    (code >= 0x1100 && code <= 0x11ff) ||
+    (code >= 0x2e80 && code <= 0x9fff) ||
+    (code >= 0xa960 && code <= 0xa97f) ||
+    (code >= 0xac00 && code <= 0xd7ff) ||
+    // Surrogates of the CJK extensions (U+20000–U+3FFFF).
+    (code >= 0xd840 && code <= 0xd8bf) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xfe30 && code <= 0xfe4f) ||
+    (code >= 0xff00 && code <= 0xffef)
+  );
+}
+
+function isHighSurrogate(code: number) {
+  return code >= 0xd800 && code <= 0xdbff;
+}
+
+/** Whether a line may break between `text[index - 1]` and `text[index]`. */
+function canBreak(text: string, index: number) {
+  const before = text[index - 1];
+  const after = text[index];
+  if (before === " " || after === " ") return true;
+  if (NO_START.has(after) || NO_END.has(before)) return false;
+  const code = text.charCodeAt(index - 1);
+  if (isHighSurrogate(code)) return false;
+  return isWide(code) || isWide(text.charCodeAt(index));
+}
+
+/** Measures and shortens text for one font, caching results because the same strings repeat a lot. */
+export class TextFitter {
+  private readonly widths = new Map<string, number>();
+  private readonly fits = new Map<string, string>();
+  private readonly wrapped = new Map<string, readonly string[]>();
+  private ellipsisWidth = -1;
+
+  constructor(
+    private readonly context: CanvasRenderingContext2D,
+    readonly font: string,
+  ) {}
+
+  /** Width of `text`. The caller must have set `context.font` to this fitter's font. */
+  width(text: string): number {
+    let width = this.widths.get(text);
+    if (width === undefined) {
+      width = this.context.measureText(text).width;
+      if (this.widths.size > MAX_ENTRIES) this.widths.clear();
+      this.widths.set(text, width);
+    }
+    return width;
+  }
+
+  /** `text`, shortened with "…" to fit in `maxWidth`. */
+  fit(text: string, maxWidth: number): string {
+    if (maxWidth <= 0 || text === "") return "";
+    // Cells never show more than a few hundred characters; skip measuring the rest.
+    const source = text.length > 400 ? text.slice(0, 400) : text;
+    if (source === text && this.width(text) <= maxWidth) return text;
+    const key = `${Math.floor(maxWidth)}\u0001${source}`;
+    const cached = this.fits.get(key);
+    if (cached !== undefined) return cached;
+    if (this.ellipsisWidth < 0) this.ellipsisWidth = this.context.measureText(ELLIPSIS).width;
+    let result = "";
+    if (this.ellipsisWidth <= maxWidth) {
+      const full = this.context.measureText(source).width;
+      let low = 0;
+      let high = Math.min(source.length, Math.ceil((source.length * maxWidth) / Math.max(1, full)) + 4);
+      while (low < high) {
+        const middle = (low + high + 1) >> 1;
+        if (this.context.measureText(source.slice(0, middle)).width + this.ellipsisWidth <= maxWidth) low = middle;
+        else high = middle - 1;
+      }
+      // Do not split a surrogate pair.
+      const code = source.charCodeAt(low - 1);
+      if (low > 0 && code >= 0xd800 && code <= 0xdbff) low--;
+      result = `${source.slice(0, low)}${ELLIPSIS}`;
+    }
+    if (this.fits.size > MAX_ENTRIES) this.fits.clear();
+    this.fits.set(key, result);
+    return result;
+  }
+
+  /**
+   * `text` wrapped onto at most `maxLines` lines of `maxWidth`: lines break at spaces and between CJK
+   * characters (not before closing punctuation or after opening brackets), words longer than a line
+   * are cut, and "\n" starts a new line. When the text needs more lines, the last one ends with "…".
+   */
+  lines(text: string, maxWidth: number, maxLines: number): readonly string[] {
+    if (maxWidth <= 0 || maxLines < 1) return [];
+    const source = text.replace(/\n+$/, "");
+    if (source === "") return [];
+    const key = `${Math.floor(maxWidth)}\u0001${maxLines}\u0001${source}`;
+    const cached = this.wrapped.get(key);
+    if (cached !== undefined) return cached;
+    const result: string[] = [];
+    const paragraphs = source.split("\n");
+    // The text the last line was taken from, and whether more text follows it.
+    let last = "";
+    let cut = false;
+    let more = false;
+    for (const paragraph of paragraphs) {
+      if (result.length === maxLines) {
+        more = true;
+        break;
+      }
+      let rest = paragraph;
+      do {
+        if (result.length === maxLines) {
+          more = cut = true;
+          break;
+        }
+        last = rest;
+        const end = this.breakAt(rest, maxWidth);
+        result.push(rest.slice(0, end).replace(/ +$/, ""));
+        rest = rest.slice(end).replace(/^ +/, "");
+      } while (rest !== "");
+      if (more) break;
+    }
+    if (more) {
+      const index = result.length - 1;
+      result[index] = this.fit(cut ? last : `${result[index]}${ELLIPSIS}`, maxWidth);
+    }
+    if (this.wrapped.size > MAX_ENTRIES) this.wrapped.clear();
+    this.wrapped.set(key, result);
+    return result;
+  }
+
+  /** Length of the first line of `text` (one paragraph) in `maxWidth`, at a place where it may break. */
+  private breakAt(text: string, maxWidth: number) {
+    if (text === "" || this.width(text) <= maxWidth) return text.length;
+    // A character is at least a pixel wide, so a line has at most `maxWidth` characters.
+    let low = 0;
+    let high = Math.min(text.length, Math.ceil(maxWidth));
+    while (low < high) {
+      const middle = (low + high + 1) >> 1;
+      if (this.context.measureText(text.slice(0, middle)).width <= maxWidth) low = middle;
+      else high = middle - 1;
+    }
+    for (let index = low; index > 0; index--) if (canBreak(text, index)) return index;
+    // No place to break: cut the word, keeping surrogate pairs, and place at least one character.
+    let end = Math.max(1, low);
+    if (end < text.length && isHighSurrogate(text.charCodeAt(end - 1))) end = end > 1 ? end - 1 : end + 1;
+    return end;
+  }
+}

package/src/{theme.ts → canvas/theme.ts}

@@ -5,6 +5,8 @@ export interface GridTheme {
   smallFont: string;
   fontSize: number;
   fontFamily: string;
+  /** Height of each further line of wrapped cell text, in pixels. */
+  lineHeight: number;
   background: string;
   text: string;
   muted: string;
@@ -20,14 +22,20 @@ export interface GridTheme {
   selectionBorder: string;
   activeBorder: string;
   accent: string;
+  /** Text and marks drawn on `accent`, such as the check of a checkbox. */
+  accentText: string;
+  /** Background of checked rows. */
+  checkedRow: string;
   nullText: string;
   placeholder: string;
   match: string;
   error: string;
+  /** Text of cells whose `cellAction` is a link. */
+  link: string;
 }
 
 const colorTokens: Record<
-  keyof Omit<GridTheme, "font" | "headerFont" | "smallFont" | "fontSize" | "fontFamily">,
+  keyof Omit<GridTheme, "font" | "headerFont" | "smallFont" | "fontSize" | "fontFamily" | "lineHeight">,
   string
 > = {
   background: "--vg-bg",
@@ -45,10 +53,13 @@ const colorTokens: Record<
   selectionBorder: "--vg-selection-border",
   activeBorder: "--vg-active-border",
   accent: "--vg-accent",
+  accentText: "--vg-accent-fg",
+  checkedRow: "--vg-checked-row-bg",
   nullText: "--vg-null-fg",
   placeholder: "--vg-placeholder",
   match: "--vg-match-bg",
   error: "--vg-error-fg",
+  link: "--vg-link-fg",
 };
 
 /** Resolves the theme of `root`. Colors given as `light-dark()` or system colors resolve to concrete values. */
@@ -65,6 +76,7 @@ export function resolveTheme(root: HTMLElement): GridTheme {
     const fontFamily = style.getPropertyValue("--vg-font-family").trim() || style.fontFamily || "system-ui, sans-serif";
     const fontSize =
       Number.parseFloat(style.getPropertyValue("--vg-font-size")) || Number.parseFloat(style.fontSize) || 13;
+    const lineHeight = Number.parseFloat(style.getPropertyValue("--vg-line-height")) || Math.round(fontSize * 1.4);
     const colors = Object.fromEntries(Object.entries(colorTokens).map(([key, token]) => [key, color(token)])) as Pick<
       GridTheme,
       keyof typeof colorTokens
@@ -73,6 +85,7 @@ export function resolveTheme(root: HTMLElement): GridTheme {
       ...colors,
       fontFamily,
       fontSize,
+      lineHeight,
       font: `${fontSize}px ${fontFamily}`,
       headerFont: `600 ${fontSize}px ${fontFamily}`,
       smallFont: `${Math.max(9, fontSize - 2)}px ${fontFamily}`,