vastgrid 0.1.0 → 0.2.0

package/src/react/data-grid.tsx

@@ -0,0 +1,286 @@
+import {
+  type ComponentType,
+  type CSSProperties,
+  lazy,
+  type ReactNode,
+  type Ref,
+  Suspense,
+  use,
+  useEffect,
+  useEffectEvent,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import type { GridDocument, GridSession } from "vastgrid-spec";
+import type { CellHooks, ColumnGroup } from "../canvas/hooks.js";
+import type { Transport } from "../core/client.js";
+import { createGridStore, type GridStore } from "../core/store.js";
+import type { GridError, InitialView, OpenOptions } from "../core/types.js";
+import { GridContext, LocaleContext, SaveContext } from "./context.js";
+import type { DetailPanelProps } from "./detail-panel.js";
+import { type CellActionEvent, GridBody } from "./grid-body.js";
+import { type GridMessages, messagesFor } from "./messages.js";
+import { useSaveAction } from "./save.js";
+import { StaticRows } from "./static-rows.js";
+import { StatusBar } from "./status-bar.js";
+import { Toolbar } from "./toolbar.js";
+
+// The find bar and the detail panel load when they first open (§10 of react.md).
+const FindBar = lazy(() => import("./find-bar.js").then((module) => ({ default: module.FindBar })));
+const DetailPanel = lazy(() => import("./detail-panel.js").then((module) => ({ default: module.DetailPanel })));
+
+/** What `ref` gives (§5.5 of react.md). */
+export interface DataGridHandle {
+  store: GridStore;
+  dispatch: GridStore["dispatch"];
+  /** Moves the focus to the grid. */
+  focus(): void;
+}
+
+export interface DataGridProps {
+  /** Where the rows come from, with `table`; a new transport or table makes a new store. */
+  transport?: Transport;
+  /** The `ref` of the table to open (§8.2). */
+  table?: string;
+  /** The `read` options of `open`. */
+  open?: OpenOptions;
+  /** A store made outside, instead of `transport` and `table`. */
+  store?: GridStore;
+  /** The view and its columns (§5.1), controlled. */
+  document?: GridDocument;
+  defaultDocument?: GridDocument;
+  onDocumentChange?: (document: GridDocument) => void;
+  /** Where the person is (§5.2), controlled. */
+  session?: GridSession;
+  defaultSession?: GridSession;
+  onSessionChange?: (session: GridSession) => void;
+  /** Rows read on a server, shown before the first read; a promise streams them (§7). */
+  initial?: InitialView | Promise<InitialView>;
+  toolbar?: boolean;
+  statusBar?: boolean;
+  /** A check box for each row in the gutter, and Space to check the active row (§5.2.1). */
+  checkboxes?: boolean;
+  /** Groups of columns named in header rows above the column names; nested groups add rows. */
+  columnGroups?: readonly ColumnGroup[];
+  /** The height of each row of groups, instead of `--vg-group-header-height`. */
+  groupHeaderHeight?: number;
+  /** How many lines rows have while a displayed column wraps its text (2 by default). */
+  wrapLines?: number;
+  /** The text of a cell instead of the grid's (§5.1: functions win over the document's formats). */
+  cellText?: CellHooks["cellText"];
+  /** The colors of a cell instead of the column's style rules. */
+  cellStyle?: CellHooks["cellStyle"];
+  /** Draws cells on the canvas, with the grid's drawing at hand (`drawDefault`). */
+  drawCell?: CellHooks["drawCell"];
+  /** Makes cells links or buttons; a click or Space on them calls `onCellAction`. */
+  cellAction?: CellHooks["cellAction"];
+  onCellAction?: (event: CellActionEvent) => void;
+  /** Shows the active row in the detail panel your own way, instead of a list of its columns. */
+  detailPanel?: ComponentType<DetailPanelProps>;
+  rowHeight?: number;
+  headerHeight?: number;
+  /** The language of the UI, a BCP 47 tag; the browser's by default. */
+  locale?: string;
+  messages?: Partial<GridMessages>;
+  /** Failures that belong to no command (§4.2). */
+  onError?: (error: GridError) => void;
+  ref?: Ref<DataGridHandle>;
+  className?: string;
+  style?: CSSProperties;
+  "aria-label"?: string;
+}
+
+const transportIds = new WeakMap<object, number>();
+let nextTransportId = 1;
+
+/** A number for each transport, for the key that makes a new store when the transport changes. */
+function transportId(transport: object) {
+  let id = transportIds.get(transport);
+  if (id === undefined) {
+    id = nextTransportId++;
+    transportIds.set(transport, id);
+  }
+  return id;
+}
+
+function isPromise<T>(value: T | Promise<T> | undefined): value is Promise<T> {
+  return typeof (value as { then?: unknown } | undefined)?.then === "function";
+}
+
+const noSubscription = () => () => {};
+const browserLocale = () => navigator.language;
+const serverLocale = () => undefined;
+
+/**
+ * A data grid for tables of any size (§5.1 of react.md): it draws on a canvas, reads rows through a
+ * transport as you scroll, and is driven by the commands of the specification.
+ */
+export function DataGrid(props: DataGridProps) {
+  if (props.store) return <Frame {...props} store={props.store} />;
+  const { transport, table } = props;
+  if (!transport || table === undefined) throw new Error("DataGrid needs a store, or a transport and a table.");
+  const key = `${transportId(transport)}\u0000${table}`;
+  if (isPromise(props.initial)) {
+    return (
+      <Suspense fallback={<div className="vg-root" aria-busy="true" />}>
+        <OwnStore key={key} {...props} transport={transport} table={table} />
+      </Suspense>
+    );
+  }
+  return <OwnStore key={key} {...props} transport={transport} table={table} />;
+}
+
+/** A grid with a store of its own, made once and connected while it is mounted. */
+function OwnStore(props: DataGridProps & { transport: Transport; table: string }) {
+  const initial = isPromise(props.initial) ? use(props.initial) : props.initial;
+  const [store] = useState(() =>
+    createGridStore({
+      transport: props.transport,
+      table: props.table,
+      ...(props.open ? { open: props.open } : {}),
+      ...((props.document ?? props.defaultDocument) ? { document: props.document ?? props.defaultDocument } : {}),
+      ...((props.session ?? props.defaultSession) ? { session: props.session ?? props.defaultSession } : {}),
+      ...(initial ? { initial } : {}),
+    }),
+  );
+  useEffect(() => store.connect(), [store]);
+  return <Frame {...props} store={store} />;
+}
+
+/** Makes a part of the state controlled by a prop (§5.2), and reports the changes that commands make. */
+function useControlled<T extends GridDocument | GridSession>(
+  store: GridStore,
+  part: "document" | "session",
+  value: T | undefined,
+  onChange: ((value: T) => void) | undefined,
+) {
+  const controlled = value !== undefined;
+  const report = useEffectEvent((next: T) => onChange?.(next));
+  useLayoutEffect(() => {
+    store.control(part, controlled);
+  }, [store, part, controlled]);
+  // In the commit that brings the prop, before the canvas draws.
+  useLayoutEffect(() => {
+    if (value === undefined) return;
+    if (part === "document") store.setDocument(value as GridDocument);
+    else store.setSession(value as GridSession);
+  }, [store, part, value]);
+  useEffect(() => store.on(part, (next) => report(next as T)), [store, part]);
+}
+
+function Frame({
+  store,
+  toolbar = true,
+  statusBar = true,
+  checkboxes = false,
+  columnGroups,
+  groupHeaderHeight,
+  wrapLines,
+  cellText,
+  cellStyle,
+  drawCell,
+  cellAction,
+  onCellAction,
+  detailPanel,
+  className,
+  style,
+  ref,
+  rowHeight,
+  headerHeight,
+  locale: given,
+  messages: replaced,
+  document,
+  onDocumentChange,
+  session,
+  onSessionChange,
+  onError,
+  "aria-label": ariaLabel,
+}: DataGridProps & { store: GridStore }) {
+  const detected = useSyncExternalStore(noSubscription, browserLocale, serverLocale);
+  const locale = given ?? detected;
+  const base = messagesFor(locale);
+  const messages = replaced ? { ...base, ...replaced } : base;
+  const language = { messages, locale, number: new Intl.NumberFormat(locale) };
+  const label = ariaLabel ?? messages.grid;
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const [notice, setNotice] = useState("");
+  const [finding, setFinding] = useState(false);
+  const detailOpen = useGridSelectorOf(store, (snapshot) => snapshot.session.detail?.open === true);
+  const saving = useSaveAction(store, language, setNotice);
+  const status = useGridSelectorOf(store, (snapshot) => snapshot.status);
+  useControlled(store, "document", document, onDocumentChange);
+  useControlled(store, "session", session, onSessionChange);
+  const reportError = useEffectEvent((error: GridError) => onError?.(error));
+  useEffect(() => store.on("error", (error) => reportError(error)), [store]);
+  useImperativeHandle(
+    ref,
+    () => ({
+      store,
+      dispatch: store.dispatch,
+      focus: () => scrollerRef.current?.focus(),
+    }),
+    [store],
+  );
+  return (
+    <GridContext value={store}>
+      <LocaleContext value={language}>
+        <SaveContext value={saving}>
+          <div className={className ? `vg-root ${className}` : "vg-root"} style={style} data-status={status}>
+            {toolbar && <Toolbar announce={setNotice} />}
+            {finding && (
+              <Suspense fallback={null}>
+                <FindBar onClose={() => setFinding(false)} scrollerRef={scrollerRef} />
+              </Suspense>
+            )}
+            <div className="vg-main">
+              <Suspense fallback={<StaticRows label={label} />}>
+                <GridBody
+                  rowHeight={rowHeight}
+                  headerHeight={headerHeight}
+                  checkboxes={checkboxes}
+                  columnGroups={columnGroups}
+                  groupHeaderHeight={groupHeaderHeight}
+                  wrapLines={wrapLines}
+                  hooks={{ cellText, cellStyle, drawCell, cellAction }}
+                  onCellAction={onCellAction}
+                  onFind={() => setFinding(true)}
+                  label={label}
+                  scrollerRef={scrollerRef}
+                  announce={setNotice}
+                />
+              </Suspense>
+              {detailOpen && (
+                <Suspense fallback={null}>
+                  <DetailPanel
+                    custom={detailPanel}
+                    onClosed={() => scrollerRef.current?.focus({ preventScroll: true })}
+                  />
+                </Suspense>
+              )}
+            </div>
+            {statusBar && (
+              <StatusBar announce={setNotice} onDone={() => scrollerRef.current?.focus({ preventScroll: true })} />
+            )}
+            <div className="vg-sr-only" aria-live="polite">
+              {notice}
+            </div>
+          </div>
+        </SaveContext>
+      </LocaleContext>
+    </GridContext>
+  );
+}
+
+/** `useGridSelector` for a store given directly, before the context holds it. */
+function useGridSelectorOf<T>(store: GridStore, selector: (snapshot: ReturnType<GridStore["getSnapshot"]>) => T): T {
+  const read = () => selector(store.getSnapshot());
+  return useSyncExternalStore(store.subscribe, read, read);
+}
+
+/** Gives a store to the hooks of the components inside (§5.4 of react.md). */
+export function GridProvider({ store, children }: { store: GridStore; children?: ReactNode }) {
+  return <GridContext value={store}>{children}</GridContext>;
+}

package/src/react/detail-panel.tsx

@@ -0,0 +1,92 @@
+import { type ComponentType, use } from "react";
+import { type Column, type JsonValue, type RowKey, textOf } from "vastgrid-spec";
+import { formatterFor } from "../core/format.js";
+import { LocaleContext } from "./context.js";
+import { useGridRows, useGridSelector, useGridStore } from "./hooks.js";
+
+/**
+ * The detail panel of the active row (§5.2 of the specification, `detail`): every column of the view, hidden ones
+ * included, with its label and its value in full, by the column's format. It follows the active cell, reads the
+ * row's values that the canvas did not (`useGridRows`), and is opened and closed by `detail.open` and
+ * `detail.close`; the focus stays in the grid, and goes back to it when the panel is closed from inside (× or Esc).
+ */
+export function DetailPanel({
+  custom,
+  onClosed,
+}: {
+  custom?: ComponentType<DetailPanelProps>;
+  /** Called when the panel is closed from inside it, to give the focus back to the grid. */
+  onClosed: () => void;
+}) {
+  const open = useGridSelector((snapshot) => snapshot.session.detail?.open === true);
+  // Closed, it follows no rows: scrolling commits nothing (§10 of react.md).
+  return open ? <OpenDetail Custom={custom} onClosed={onClosed} /> : null;
+}
+
+/** What a host's own detail panel (`detailPanel`) gets: the active row's position, the view's columns and values. */
+export interface DetailPanelProps {
+  row: number;
+  columns: readonly Column[];
+  values: readonly JsonValue[];
+  /** The row's key (§5.3), when it is read. */
+  rowKey: RowKey | undefined;
+}
+
+function OpenDetail({ Custom, onClosed }: { Custom?: ComponentType<DetailPanelProps>; onClosed: () => void }) {
+  const store = useGridStore();
+  const { messages, number, locale } = use(LocaleContext);
+  const row = useGridSelector((snapshot) => snapshot.session.active?.row ?? 0);
+  const rowCount = useGridSelector((snapshot) => snapshot.view?.rowCount ?? 0);
+  const columns = useGridSelector((snapshot) => snapshot.view?.columns);
+  const settings = useGridSelector((snapshot) => snapshot.document.columns);
+  const names = columns && rowCount > 0 ? columns.map((column) => column.name) : [];
+  const [values] = useGridRows({ start: row, end: names.length > 0 ? row + 1 : row, columns: names });
+  if (!columns) return null;
+  const byName = new Map((settings ?? []).map((setting) => [setting.name, setting]));
+  const text = (value: JsonValue | undefined, index: number) => {
+    if (value === undefined) return messages.loading;
+    if (value === null) return "";
+    const column = columns[index];
+    const format = byName.get(column.name)?.format;
+    return formatterFor(column, format, locale)?.(value) ?? textOf(value, column) ?? "";
+  };
+  const title = rowCount > 0 ? messages.detailOf(number.format(row + 1)) : messages.details;
+  const close = () => {
+    void store.dispatch({ command: "detail.close" });
+    onClosed();
+  };
+  return (
+    <aside
+      className="vg-detail"
+      aria-label={title}
+      onKeyDown={(event) => {
+        if (event.key !== "Escape" || event.nativeEvent.isComposing) return;
+        event.preventDefault();
+        close();
+      }}
+    >
+      <header className="vg-detail__header">
+        <h2 className="vg-detail__title">{title}</h2>
+        <button type="button" className="vg-button vg-button--small" aria-label={messages.closeDetails} onClick={close}>
+          ×
+        </button>
+      </header>
+      {rowCount > 0 && Custom && values?.every((value) => value !== undefined) ? (
+        <Custom row={row} columns={columns} values={values as JsonValue[]} rowKey={store.rowKey(row)} />
+      ) : rowCount > 0 && Custom ? (
+        <p className="vg-filter__note">{messages.loading}</p>
+      ) : (
+        rowCount > 0 && (
+          <dl className="vg-detail__list">
+            {columns.map((column, index) => (
+              <div key={column.name} className="vg-detail__item">
+                <dt>{byName.get(column.name)?.format?.label ?? column.name}</dt>
+                <dd>{text(values?.[index], index)}</dd>
+              </div>
+            ))}
+          </dl>
+        )
+      )}
+    </aside>
+  );
+}

package/src/react/export-menu.tsx

@@ -0,0 +1,112 @@
+import { type ToggleEvent, use, useId, useRef, useState, useTransition } from "react";
+import { CommandError } from "vastgrid-spec";
+import { LocaleContext } from "./context.js";
+import { useGridSelector, useGridStore } from "./hooks.js";
+
+/** The media types of the formats of §8.2, for files that an engine answers as data. */
+const MEDIA_TYPES: Record<string, string> = {
+  csv: "text/csv;charset=utf-8",
+  tsv: "text/tab-separated-values;charset=utf-8",
+  json: "application/json;charset=utf-8",
+  parquet: "application/vnd.apache.parquet",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+};
+
+/** Downloads a file at a URL, as a link with `download` does: under `name`, or the name the server gives. */
+function download(url: string, name = "") {
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = name;
+  link.rel = "noopener";
+  document.body.append(link);
+  link.click();
+  link.remove();
+}
+
+/**
+ * The toolbar's export menu (§6.6 of the specification): the rows of the view or the whole table, with the hidden
+ * columns or not, in one of the formats the engine exports. It runs as an Action: the button shows that it runs, and
+ * the outcome is announced. An export without a target is downloaded from where the transport gives it
+ * (`Transport.exportUrl`), or, from an engine that answers the file's bytes (`delivery` `data`), as a file made of
+ * them.
+ */
+export function ExportMenu({ announce }: { announce: (text: string) => void }) {
+  const store = useGridStore();
+  const { messages, number } = use(LocaleContext);
+  const formats = useGridSelector((snapshot) => snapshot.table?.capabilities.export?.formats);
+  const [rows, setRows] = useState<"view" | "table">("view");
+  const [allColumns, setAllColumns] = useState(false);
+  const [pending, startExport] = useTransition();
+  const id = useId();
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  if (!formats || formats.length === 0) return null;
+
+  // The menu opens under its button, its right edge at the button's (popovers open in the middle otherwise).
+  const place = (event: ToggleEvent<HTMLDivElement>) => {
+    const button = buttonRef.current;
+    if (event.newState !== "open" || !button) return;
+    const rect = button.getBoundingClientRect();
+    const menu = event.currentTarget;
+    menu.style.top = `${rect.bottom + 4}px`;
+    menu.style.left = `${Math.max(8, rect.right - menu.offsetWidth)}px`;
+  };
+
+  const run = (format: string) => {
+    document.getElementById(id)?.hidePopover?.();
+    startExport(async () => {
+      const outcome = await store.dispatch({
+        command: "export",
+        format,
+        rows,
+        columns: allColumns ? "all" : "displayed",
+      });
+      if (!outcome.ok) {
+        const reason = outcome.error instanceof CommandError ? outcome.error.reason : null;
+        announce(messages.failed(reason === "not_loaded" ? messages.loading : outcome.error.message));
+        return;
+      }
+      const result = outcome.output as { target: string | null; rows: number; data?: { bytes: Uint8Array } };
+      if (result.data) {
+        const url = URL.createObjectURL(
+          new Blob([result.data.bytes as Uint8Array<ArrayBuffer>], { type: MEDIA_TYPES[format] ?? "" }),
+        );
+        download(url, store.exportName(format));
+        // The link has started the download; the browser keeps the file's bytes until it is done.
+        setTimeout(() => URL.revokeObjectURL(url), 60_000);
+      } else {
+        const url = result.target === null ? null : store.exportUrl(result.target);
+        if (url) download(url);
+      }
+      announce(messages.exported(number.format(result.rows)));
+    });
+  };
+
+  return (
+    <>
+      <button ref={buttonRef} type="button" className="vg-button" popoverTarget={id} disabled={pending}>
+        {pending ? messages.exporting : messages.export}
+      </button>
+      <div id={id} popover="auto" role="dialog" className="vg-menu" aria-label={messages.export} onToggle={place}>
+        <fieldset className="vg-menu__group">
+          <label>
+            <input type="radio" name={`${id}-rows`} checked={rows === "view"} onChange={() => setRows("view")} />
+            {messages.exportView}
+          </label>
+          <label>
+            <input type="radio" name={`${id}-rows`} checked={rows === "table"} onChange={() => setRows("table")} />
+            {messages.exportTable}
+          </label>
+          <label>
+            <input type="checkbox" checked={allColumns} onChange={(event) => setAllColumns(event.target.checked)} />
+            {messages.exportAllColumns}
+          </label>
+        </fieldset>
+        {formats.map((format) => (
+          <button key={format} type="button" className="vg-menu__item" onClick={() => run(format)}>
+            {messages.exportFormats[format] ?? format}
+          </button>
+        ))}
+      </div>
+    </>
+  );
+}

package/src/react/find-bar.tsx

@@ -0,0 +1,112 @@
+import { type KeyboardEvent, type RefObject, use, useLayoutEffect, useRef, useState, useTransition } from "react";
+import { LocaleContext } from "./context.js";
+import { useGridSelector, useGridStore } from "./hooks.js";
+
+/**
+ * The find bar (⌘F or Ctrl+F on the grid): finds the next cell of the view whose text contains what is typed, from
+ * the active cell, in the displayed columns (`GridStore.find`, `find` of §8.2), and makes it the active cell. Enter
+ * finds the next one, Shift+Enter the one before, and Esc closes the bar and gives the focus back to the grid.
+ */
+export function FindBar({
+  onClose,
+  scrollerRef,
+}: {
+  onClose: () => void;
+  scrollerRef: RefObject<HTMLDivElement | null>;
+}) {
+  const store = useGridStore();
+  const { messages } = use(LocaleContext);
+  const finds = useGridSelector((snapshot) => snapshot.table?.capabilities.find === true);
+  const [text, setText] = useState("");
+  const [caseSensitive, setCaseSensitive] = useState(false);
+  const [status, setStatus] = useState("");
+  const [pending, startFind] = useTransition();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useLayoutEffect(() => {
+    inputRef.current?.focus();
+    inputRef.current?.select();
+  }, []);
+
+  const close = () => {
+    onClose();
+    scrollerRef.current?.focus({ preventScroll: true });
+  };
+
+  const find = (direction: 1 | -1) => {
+    if (text === "") return;
+    startFind(async () => {
+      const { session, displayed } = store.getSnapshot();
+      const from = session.active ?? { row: 0, column: displayed[0]?.column.name ?? "" };
+      try {
+        const found = await store.find(text, { from, direction, caseSensitive });
+        if (!found) {
+          setStatus(messages.noMatches);
+          return;
+        }
+        setStatus("");
+        await store.dispatch({ command: "select", row: found.row, column: found.column });
+      } catch (error) {
+        setStatus(messages.failed(error instanceof Error ? error.message : String(error)));
+      }
+    });
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    // Keys that end an IME's composition are the IME's.
+    if (event.nativeEvent.isComposing || event.keyCode === 229) return;
+    if (event.key === "Escape") {
+      event.preventDefault();
+      close();
+    } else if (event.key === "Enter" && event.target === inputRef.current) {
+      event.preventDefault();
+      find(event.shiftKey ? -1 : 1);
+    }
+  };
+
+  if (!finds) return null;
+  return (
+    <search className="vg-find" aria-label={messages.find} onKeyDown={onKeyDown}>
+      <input
+        ref={inputRef}
+        type="search"
+        className="vg-input vg-find__input"
+        aria-label={messages.find}
+        placeholder={messages.find}
+        value={text}
+        onChange={(event) => {
+          setText(event.target.value);
+          setStatus("");
+        }}
+      />
+      <label className="vg-filter__value">
+        <input type="checkbox" checked={caseSensitive} onChange={(event) => setCaseSensitive(event.target.checked)} />
+        <span>{messages.matchCase}</span>
+      </label>
+      <button
+        type="button"
+        className="vg-button vg-button--small"
+        aria-label={messages.findPrevious}
+        disabled={pending || text === ""}
+        onClick={() => find(-1)}
+      >
+        ↑
+      </button>
+      <button
+        type="button"
+        className="vg-button vg-button--small"
+        aria-label={messages.findNext}
+        disabled={pending || text === ""}
+        onClick={() => find(1)}
+      >
+        ↓
+      </button>
+      <span className="vg-find__status" role="status">
+        {status}
+      </span>
+      <button type="button" className="vg-button vg-button--small" aria-label={messages.closeFind} onClick={close}>
+        ×
+      </button>
+    </search>
+  );
+}