vastgrid 0.1.0 → 0.2.0

package/src/react/group-menu.tsx

@@ -0,0 +1,214 @@
+import { use, useState, useTransition } from "react";
+import { type Aggregate, type GridCommand, MEASURES, type MeasureName, measureTakes } from "vastgrid-spec";
+import { measureName, offers, rowColumns } from "../core/measures.js";
+import { LocaleContext } from "./context.js";
+import { useGridSelector, useGridStore } from "./hooks.js";
+
+/** The measures the menu offers; `quantile` needs a `p`, which it does not ask for. */
+const OFFERED = MEASURES.filter((fn) => fn !== "quantile");
+
+/**
+ * The content of the toolbar's group menu, loaded when it first opens (§6.2 of the specification): the columns that the rows are grouped by and the measures of
+ * each group (§4.5), each change dispatched as `group.set` with the whole aggregate, or `group.clear` when nothing is
+ * left. It is there when the engine groups rows.
+ */
+export default function GroupPanel() {
+  const store = useGridStore();
+  const { messages } = use(LocaleContext);
+  const table = useGridSelector((snapshot) => snapshot.table);
+  const plan = useGridSelector((snapshot) => snapshot.document.plan);
+  const [fn, setFn] = useState<MeasureName>("sum");
+  const [column, setColumn] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [pending, startDispatch] = useTransition();
+  if (!table || !offers(table.capabilities, "count")) return null;
+
+  const aggregate: Aggregate = plan?.aggregate ?? { keys: [], measures: [] };
+  const rows = rowColumns(plan, table);
+  const measures = OFFERED.filter((name) => offers(table.capabilities, name));
+  const columnsFor = (name: MeasureName) => rows.filter((item) => measureTakes(name, item));
+  const target = column === "" ? undefined : rows.find((item) => item.name === column);
+  const canAdd = target ? measureTakes(fn, target) : fn === "count";
+
+  const dispatch = (command: GridCommand) =>
+    startDispatch(async () => {
+      const outcome = await store.dispatch(command);
+      setError(outcome.ok ? null : outcome.error.message);
+    });
+  const set = (next: Aggregate) =>
+    dispatch(
+      next.keys.length === 0 && next.measures.length === 0
+        ? { command: "group.clear" }
+        : { command: "group.set", aggregate: next },
+    );
+  const pivots = table.capabilities.plan?.pivot !== false;
+  const pivot = aggregate.pivot?.columns ?? [];
+  // A pivot makes a column per value of its columns and measure (§4.6), so it needs a measure: rows are counted.
+  const setPivot = (columns: string[]) => {
+    const { pivot: _pivot, ...rest } = aggregate;
+    const measures =
+      columns.length > 0 && rest.measures.length === 0
+        ? [{ name: measureName("count", undefined, new Set(rest.keys)), fn: "count" as const }]
+        : rest.measures;
+    set(columns.length > 0 ? { ...rest, measures, pivot: { columns } } : rest);
+  };
+  const taken = () => new Set([...aggregate.keys, ...aggregate.measures.map((measure) => measure.name)]);
+  const addMeasure = () => {
+    if (!canAdd) return;
+    const name = measureName(fn, target?.name, taken());
+    set({ ...aggregate, measures: [...aggregate.measures, { name, fn, ...(target ? { column: target.name } : {}) }] });
+  };
+
+  return (
+    <>
+      <fieldset className="vg-groups__part" disabled={pending}>
+        <legend>{messages.groupKeys}</legend>
+        <ul className="vg-groups__list">
+          {aggregate.keys.map((key) => (
+            <li key={key}>
+              <span>{key}</span>
+              <button
+                type="button"
+                className="vg-button vg-button--small"
+                aria-label={messages.remove(key)}
+                onClick={() => set({ ...aggregate, keys: aggregate.keys.filter((other) => other !== key) })}
+              >
+                ×
+              </button>
+            </li>
+          ))}
+        </ul>
+        <select
+          className="vg-input"
+          aria-label={messages.addKey}
+          value=""
+          onChange={(event) => {
+            const key = event.target.value;
+            if (!key) return;
+            // Rows grouped for the first time are counted.
+            const measures = plan?.aggregate
+              ? aggregate.measures
+              : [{ name: measureName("count", undefined, new Set([key])), fn: "count" as const }];
+            set({ ...aggregate, keys: [...aggregate.keys, key], measures });
+          }}
+        >
+          <option value="">{messages.addKey}</option>
+          {rows
+            // Keys are the columns whose values order (§3.9), as `min` takes them.
+            .filter((item) => !aggregate.keys.includes(item.name) && measureTakes("min", item))
+            .map((item) => (
+              <option key={item.name} value={item.name}>
+                {item.name}
+              </option>
+            ))}
+        </select>
+      </fieldset>
+      {pivots && (
+        <fieldset className="vg-groups__part" disabled={pending}>
+          <legend>{messages.pivotBy}</legend>
+          <ul className="vg-groups__list">
+            {pivot.map((name) => (
+              <li key={name}>
+                <span>{name}</span>
+                <button
+                  type="button"
+                  className="vg-button vg-button--small"
+                  aria-label={messages.remove(name)}
+                  onClick={() => setPivot(pivot.filter((other) => other !== name))}
+                >
+                  ×
+                </button>
+              </li>
+            ))}
+          </ul>
+          <select
+            className="vg-input"
+            aria-label={messages.pivotBy}
+            value=""
+            onChange={(event) => {
+              if (event.target.value) setPivot([...pivot, event.target.value]);
+            }}
+          >
+            <option value="">{messages.addPivot}</option>
+            {rows
+              .filter(
+                (item) =>
+                  !aggregate.keys.includes(item.name) && !pivot.includes(item.name) && measureTakes("min", item),
+              )
+              .map((item) => (
+                <option key={item.name} value={item.name}>
+                  {item.name}
+                </option>
+              ))}
+          </select>
+        </fieldset>
+      )}
+      <fieldset className="vg-groups__part" disabled={pending}>
+        <legend>{messages.measures}</legend>
+        <ul className="vg-groups__list">
+          {aggregate.measures.map((measure) => (
+            <li key={measure.name}>
+              <span>{measure.name}</span>
+              <button
+                type="button"
+                className="vg-button vg-button--small"
+                aria-label={messages.remove(measure.name)}
+                onClick={() =>
+                  set({ ...aggregate, measures: aggregate.measures.filter((other) => other.name !== measure.name) })
+                }
+              >
+                ×
+              </button>
+            </li>
+          ))}
+        </ul>
+        <div className="vg-groups__add">
+          <select
+            className="vg-input"
+            aria-label={messages.measures}
+            value={fn}
+            onChange={(event) => setFn(event.target.value as MeasureName)}
+          >
+            {measures.map((name) => (
+              <option key={name} value={name}>
+                {messages.measureNames[name]}
+              </option>
+            ))}
+          </select>
+          <select
+            className="vg-input"
+            aria-label={messages.measureColumn}
+            value={column}
+            onChange={(event) => setColumn(event.target.value)}
+          >
+            {fn === "count" && <option value="">{messages.allRows}</option>}
+            {fn !== "count" && column === "" && <option value="">{messages.measureColumn}</option>}
+            {columnsFor(fn).map((item) => (
+              <option key={item.name} value={item.name}>
+                {item.name}
+              </option>
+            ))}
+          </select>
+          <button type="button" className="vg-button" disabled={!canAdd} onClick={addMeasure}>
+            {messages.addMeasure}
+          </button>
+        </div>
+      </fieldset>
+      {error !== null && (
+        <p role="alert" className="vg-filter__error">
+          {error}
+        </p>
+      )}
+      {plan?.aggregate && (
+        <button
+          type="button"
+          className="vg-menu__item"
+          disabled={pending}
+          onClick={() => dispatch({ command: "group.clear" })}
+        >
+          {messages.ungroup}
+        </button>
+      )}
+    </>
+  );
+}

package/src/react/hooks.ts

@@ -0,0 +1,104 @@
+import { use, useEffect, useState, useSyncExternalStore } from "react";
+import type { JsonValue } from "vastgrid-spec";
+import { createGridStore, type GridStore, type GridStoreOptions } from "../core/store.js";
+import type { GridSnapshot } from "../core/types.js";
+import { GridContext } from "./context.js";
+
+/** The store of the nearest `DataGrid` or `GridProvider`. */
+export function useGridStore(): GridStore {
+  const store = use(GridContext);
+  if (!store) throw new Error("useGridStore needs a DataGrid or a GridProvider around it.");
+  return store;
+}
+
+/** Whether two values are the same, or objects or arrays whose members are the same (`Object.is`). */
+export function shallowEqual<T>(a: T, b: T): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every(
+    (key) =>
+      Object.hasOwn(b, key) && Object.is((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),
+  );
+}
+
+/** The last value a selector gave, kept while the snapshot stays or the next value is equal. */
+class Selection<T> {
+  private snapshot: GridSnapshot | undefined;
+  private selector: ((snapshot: GridSnapshot) => T) | undefined;
+  private value: T | undefined;
+
+  read(snapshot: GridSnapshot, selector: (snapshot: GridSnapshot) => T, isEqual: (a: T, b: T) => boolean): T {
+    if (snapshot === this.snapshot && selector === this.selector) return this.value as T;
+    const next = selector(snapshot);
+    if (this.snapshot === undefined || !isEqual(this.value as T, next)) this.value = next;
+    this.snapshot = snapshot;
+    this.selector = selector;
+    return this.value as T;
+  }
+}
+
+/**
+ * A part of the store's snapshot (§5.3 of react.md). The component renders again only when the selected value
+ * changes by `isEqual` (`Object.is` by default). Selectors run on every change of the store: they are cheap and
+ * make no new objects unless `isEqual` compares them (`shallowEqual`).
+ */
+export function useGridSelector<T>(
+  selector: (snapshot: GridSnapshot) => T,
+  isEqual: (a: T, b: T) => boolean = Object.is,
+): T {
+  const store = useGridStore();
+  const [selection] = useState(() => new Selection<T>());
+  const read = () => selection.read(store.getSnapshot(), selector, isEqual);
+  return useSyncExternalStore(store.subscribe, read, read);
+}
+
+/** The store's `dispatch`: the same function on every render. */
+export function useGridDispatch(): GridStore["dispatch"] {
+  return useGridStore().dispatch;
+}
+
+/** A store for the life of the component: made once from the first options, connected while it is mounted. */
+export function useCreateGridStore(options: GridStoreOptions): GridStore {
+  const [store] = useState(() => createGridStore(options));
+  useEffect(() => store.connect(), [store]);
+  return store;
+}
+
+/**
+ * Values of rows `[start, end)` of the view on screen, for cells that React renders (a detail panel, an overlay):
+ * one array per row, with undefined for values not read yet. Reads them when they are missing, and renders again
+ * when rows arrive.
+ */
+export function useGridRows(range: {
+  start: number;
+  end: number;
+  columns: readonly string[];
+}): (JsonValue | undefined)[][] {
+  const store = useGridStore();
+  const version = useSyncExternalStore(store.subscribeRows, store.getRowsVersion, store.getRowsVersion);
+  const { start, end, columns } = range;
+  const names = columns.join("\u0000");
+  useEffect(() => {
+    store.ensure(start, end, names === "" ? [] : names.split("\u0000"));
+  }, [store, start, end, names]);
+  return readRows(store, version, start, end, columns);
+}
+
+/**
+ * Reads rows of the store's cache. The cache changes inside the store, so the version of its rows is an argument:
+ * memoization (React Compiler's included) reads them again when it changes.
+ */
+export function readRows(
+  store: GridStore,
+  _version: number,
+  start: number,
+  end: number,
+  columns: readonly string[],
+): (JsonValue | undefined)[][] {
+  const rows: (JsonValue | undefined)[][] = [];
+  for (let row = start; row < end; row++) rows.push(columns.map((column) => store.cell(row, column)));
+  return rows;
+}