vastgrid 0.1.1 → 0.2.0

package/src/react/status-bar.tsx

@@ -0,0 +1,175 @@
+import { use, useEffect, useState } from "react";
+import type { CellRange } from "vastgrid-spec";
+import { checkedCount } from "../core/checked.js";
+import type { GridStore } from "../core/store.js";
+import { LocaleContext, SaveContext } from "./context.js";
+import { useGridSelector, useGridStore } from "./hooks.js";
+
+interface Summary {
+  count: number;
+  numericCount: number;
+  sum: unknown;
+  average: unknown;
+}
+
+/** How long the selection must stay before it is summed. */
+const SUMMARY_DELAY = 150;
+
+/**
+ * The count and sum of a selection of one range of several cells (`summarize`, §8.2), read once the selection has
+ * stayed for a moment, so that holding a key or dragging never waits for it; null otherwise.
+ */
+function useSummary(store: GridStore, selection: readonly CellRange[] | undefined): Summary | null {
+  const [result, setResult] = useState<{ selection: readonly CellRange[]; summary: Summary } | null>(null);
+  const summarizes = useGridSelector((snapshot) => snapshot.table?.capabilities.summarize === true);
+  const range = selection?.length === 1 ? selection[0] : undefined;
+  const several =
+    range !== undefined &&
+    (range.rows === "all" || range.rows[1] - range.rows[0] > 1 || range.columns === "all" || range.columns.length > 1);
+  useEffect(() => {
+    if (!summarizes || !several || !selection || !range) return;
+    const abort = new AbortController();
+    const timer = setTimeout(() => {
+      const snapshot = store.getSnapshot();
+      const rowCount = snapshot.view?.rowCount ?? 0;
+      const rows: [number, number] = range.rows === "all" ? [0, rowCount] : [range.rows[0], range.rows[1]];
+      const columns = range.columns === "all" ? snapshot.displayed.map((item) => item.column.name) : range.columns;
+      store
+        .summarize([rows], columns, abort.signal)
+        .then((summary) => setResult({ selection, summary }))
+        .catch(() => {});
+    }, SUMMARY_DELAY);
+    return () => {
+      clearTimeout(timer);
+      abort.abort();
+    };
+  }, [store, summarizes, several, selection, range]);
+  return result && result.selection === selection ? result.summary : null;
+}
+
+function format(number: Intl.NumberFormat, value: unknown) {
+  if (typeof value === "number") return number.format(value);
+  return typeof value === "string" ? value : "";
+}
+
+interface StatusBarProps {
+  announce: (text: string) => void;
+  /** Gives the focus back to the grid, once a button that had it is gone. */
+  onDone: () => void;
+}
+
+/**
+ * The last write that failed (§6.6 of react.md): why, with Retry (Overwrite after a conflict) while the table
+ * has the revision its rows were read at, and Discard. Both give the focus back to the grid.
+ */
+function FailedWrite({ announce, onDone }: StatusBarProps) {
+  const store = useGridStore();
+  const { messages } = use(LocaleContext);
+  const failed = useGridSelector((snapshot) => snapshot.failedWrite);
+  const revision = useGridSelector((snapshot) => snapshot.table?.revision);
+  if (!failed) return null;
+  const retry = failed.revision === revision ? failed.retry : null;
+  const text =
+    failed.error.code === "revision_changed" || (failed.retry !== null && retry === null)
+      ? messages.writeRevisionChanged
+      : failed.error.code === "edit_conflict"
+        ? messages.writeConflict
+        : messages.writeFailed(failed.error.message);
+  const send = () => {
+    onDone();
+    void store.retryWrite().then((outcome) => {
+      if (!outcome.ok && !store.getSnapshot().failedWrite) announce(messages.writeFailed(outcome.error.message));
+    });
+  };
+  return (
+    <span className="vg-statusbar__failed" role="alert">
+      <span className="vg-statusbar__error">{text}</span>
+      {retry && (
+        <button type="button" className="vg-button vg-button--small" onClick={send}>
+          {retry === "overwrite" ? messages.overwrite : messages.retry}
+        </button>
+      )}
+      <button
+        type="button"
+        className="vg-button vg-button--small"
+        onClick={() => {
+          onDone();
+          store.discardWrite();
+        }}
+      >
+        {messages.discard}
+      </button>
+    </span>
+  );
+}
+
+/**
+ * The status bar: the active cell, the sum of the selection, what the grid is doing (saving and the outcome of the
+ * last save included) or that the file changed on disk, a write that failed, the cells not saved yet and the rows.
+ */
+export function StatusBar({ announce, onDone }: StatusBarProps) {
+  const store = useGridStore();
+  const { messages, number } = use(LocaleContext);
+  const saving = use(SaveContext);
+  const saves = useGridSelector((snapshot) => snapshot.table?.capabilities.save === true);
+  const edits = useGridSelector((snapshot) => snapshot.table?.edits);
+  const revision = useGridSelector((snapshot) => snapshot.table?.revision);
+  const fileChanged = useGridSelector((snapshot) => snapshot.table?.fileChanged === true);
+  const rowCount = useGridSelector((snapshot) => snapshot.view?.rowCount);
+  const building = useGridSelector((snapshot) => snapshot.view?.status === "building");
+  const pending = useGridSelector((snapshot) => snapshot.pending !== null);
+  const failedWrite = useGridSelector((snapshot) => snapshot.failedWrite !== null);
+  const error = useGridSelector((snapshot) => snapshot.error);
+  const active = useGridSelector((snapshot) => snapshot.session.active);
+  const selection = useGridSelector((snapshot) => snapshot.session.selection);
+  const summary = useSummary(store, selection);
+  const checked = useGridSelector((snapshot) =>
+    checkedCount(snapshot.session.checked, snapshot.document.plan, snapshot.view?.rowCount ?? 0),
+  );
+  const doing = error
+    ? messages.failed(error.message)
+    : rowCount === undefined
+      ? messages.loading
+      : saving?.pending
+        ? messages.saving
+        : saving?.outcome && edits && revision === saving.outcome.revision && edits.version <= saving.outcome.version
+          ? saving.outcome.text
+          : fileChanged
+            ? messages.changedOnDisk
+            : pending || building
+              ? messages.reading
+              : "";
+  return (
+    <div className="vg-statusbar">
+      <span className="vg-statusbar__cell">
+        {active && rowCount !== undefined && rowCount > 0
+          ? messages.cell(number.format(active.row + 1), active.column)
+          : ""}
+      </span>
+      <span className="vg-toolbar__spacer" />
+      {summary && (
+        <span className="vg-statusbar__summary">
+          <span>{messages.count(number.format(summary.count))}</span>
+          {summary.numericCount > 0 && <span>{messages.sum(format(number, summary.sum))}</span>}
+          {summary.numericCount > 0 && <span>{messages.average(format(number, summary.average))}</span>}
+        </span>
+      )}
+      {failedWrite ? (
+        <FailedWrite announce={announce} onDone={onDone} />
+      ) : (
+        <span className="vg-statusbar__muted" role="status">
+          {doing}
+        </span>
+      )}
+      {checked !== 0 && (
+        <span className="vg-statusbar__checked">
+          {checked === null ? messages.checkedUnknown : messages.checkedRows(number.format(checked))}
+        </span>
+      )}
+      {saves && edits && edits.cells > 0 && (
+        <span className="vg-statusbar__unsaved">{messages.unsaved(number.format(edits.cells))}</span>
+      )}
+      <span className="vg-toolbar__count">{rowCount === undefined ? "" : messages.rows(number.format(rowCount))}</span>
+    </div>
+  );
+}

package/src/react/toolbar-popover.tsx

@@ -0,0 +1,69 @@
+import { type ReactNode, Suspense, type ToggleEvent, use, useEffect, useId, useRef, useState } from "react";
+import { LocaleContext } from "./context.js";
+
+/**
+ * A button of the toolbar and its popover, whose content is rendered only while it is open, so that a content loaded
+ * with `lazy` is downloaded when it is first opened (§10 of react.md) and starts from the state as it is then. The
+ * popover opens under the button, its right edge at the button's, and follows its content's size.
+ */
+export function ToolbarPopover({
+  label,
+  title,
+  className,
+  pressed,
+  children,
+}: {
+  label: ReactNode;
+  title: string;
+  className: string;
+  pressed?: boolean;
+  children: (close: () => void) => ReactNode;
+}) {
+  const { messages } = use(LocaleContext);
+  const [open, setOpen] = useState(false);
+  const id = useId();
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const menu = menuRef.current;
+    if (!open || !menu) return;
+    const place = () => {
+      const button = buttonRef.current;
+      if (!button) return;
+      const rect = button.getBoundingClientRect();
+      menu.style.top = `${rect.bottom + 4}px`;
+      menu.style.left = `${Math.max(8, rect.right - menu.offsetWidth)}px`;
+    };
+    place();
+    // The content may arrive after the popover opened.
+    const observer = new ResizeObserver(place);
+    observer.observe(menu);
+    return () => observer.disconnect();
+  }, [open]);
+
+  const onToggle = (event: ToggleEvent<HTMLDivElement>) => setOpen(event.newState === "open");
+  // By id, not by the ref: the content gets it during render.
+  const close = () => document.getElementById(id)?.hidePopover();
+
+  return (
+    <>
+      <button ref={buttonRef} type="button" className="vg-button" popoverTarget={id} aria-pressed={pressed}>
+        {label}
+      </button>
+      <div
+        ref={menuRef}
+        id={id}
+        popover="auto"
+        role="dialog"
+        className={`vg-menu ${className}`}
+        aria-label={title}
+        onToggle={onToggle}
+      >
+        {open && (
+          <Suspense fallback={<p className="vg-filter__note">{messages.loading}</p>}>{children(close)}</Suspense>
+        )}
+      </div>
+    </>
+  );
+}

package/src/react/toolbar.tsx

@@ -0,0 +1,152 @@
+import { lazy, use, useDeferredValue, useEffect, useState, useTransition } from "react";
+import { type Expr, partsOf } from "vastgrid-spec";
+import { isApple } from "../canvas/keys.js";
+import { offers } from "../core/measures.js";
+import { LocaleContext, SaveContext } from "./context.js";
+import { ExportMenu } from "./export-menu.js";
+import { useGridSelector, useGridStore } from "./hooks.js";
+import { ToolbarPopover } from "./toolbar-popover.js";
+
+// The menus load when they first open (§10 of react.md).
+const ConditionsPanel = lazy(() => import("./conditions-menu.js"));
+const ColumnsPanel = lazy(() => import("./columns-menu.js"));
+const GroupPanel = lazy(() => import("./group-menu.js"));
+const FormulaPanel = lazy(() => import("./formula-menu.js"));
+
+/** How long typing must pause before the search is set. */
+const SEARCH_DELAY = 200;
+
+/** The text of the search part of a plan's `where` (§6.2.1). */
+function searchOf(where: Expr | undefined): string {
+  for (const part of partsOf(where)) if ("search" in part) return part.search;
+  return "";
+}
+
+/**
+ * The toolbar: a search box when the engine searches (§3.5), the conditions menu when it filters (§6.2.1), the
+ * columns menu (§6.3), the group menu when it groups rows (§4.5), the formula
+ * menu when it derives columns (§4.11), a
+ * button that saves the written cells when the engine saves (§7.5), and one that reads the file again when it
+ * changed on disk while cells were written (§7.6). The
+ * search's text is React state, which updates as the person types; `search.set` follows through
+ * `useDeferredValue` once typing pauses.
+ */
+export function Toolbar({ announce }: { announce: (text: string) => void }) {
+  const store = useGridStore();
+  const { messages } = use(LocaleContext);
+  const fileChanged = useGridSelector((snapshot) => snapshot.table?.fileChanged === true);
+  const [reloading, startReload] = useTransition();
+  const reload = () =>
+    startReload(async () => {
+      try {
+        await store.reload();
+      } catch (error) {
+        announce(messages.failed(error instanceof Error ? error.message : String(error)));
+      }
+    });
+  const searches = useGridSelector(
+    (snapshot) => snapshot.table !== null && snapshot.table.capabilities.plan?.search !== false,
+  );
+  const saving = use(SaveContext);
+  const saves = useGridSelector((snapshot) => snapshot.table?.capabilities.save === true);
+  const unsaved = useGridSelector((snapshot) => snapshot.table?.edits.cells ?? 0);
+  const current = useGridSelector((snapshot) => searchOf(snapshot.document.plan?.where));
+  const [text, setText] = useState(current);
+  const [shown, setShown] = useState(current);
+  // A search set elsewhere (an agent, a saved view) replaces the text.
+  if (shown !== current) {
+    setShown(current);
+    setText(current);
+  }
+  const deferred = useDeferredValue(text);
+  useEffect(() => {
+    if (deferred === current) return;
+    const timer = setTimeout(() => {
+      void store.dispatch({ command: "search.set", text: deferred });
+    }, SEARCH_DELAY);
+    return () => clearTimeout(timer);
+  }, [store, deferred, current]);
+  const showsSave = saves && saving !== null;
+  const exports = useGridSelector((snapshot) => (snapshot.table?.capabilities.export?.formats.length ?? 0) > 0);
+  const derives = useGridSelector(
+    (snapshot) => snapshot.table !== null && snapshot.table.capabilities.plan?.derive !== false,
+  );
+  const groups = useGridSelector((snapshot) => snapshot.table !== null && offers(snapshot.table.capabilities, "count"));
+  const grouped = useGridSelector((snapshot) => snapshot.document.plan?.aggregate !== undefined);
+  const filters = useGridSelector(
+    (snapshot) => snapshot.table !== null && snapshot.table.capabilities.plan?.where !== false,
+  );
+  const conditions = useGridSelector(
+    (snapshot) => partsOf(snapshot.document.plan?.where).filter((part) => !("search" in part)).length,
+  );
+  const opened = useGridSelector((snapshot) => snapshot.view !== null);
+  const detail = useGridSelector((snapshot) => snapshot.session.detail?.open === true);
+  if (!searches && !showsSave && !fileChanged && !exports && !derives && !groups && !opened) return null;
+  return (
+    <div className="vg-toolbar">
+      {searches && (
+        <input
+          type="search"
+          className="vg-input vg-toolbar__search"
+          aria-label={messages.search}
+          placeholder={messages.search}
+          value={text}
+          onChange={(event) => setText(event.target.value)}
+        />
+      )}
+      <span className="vg-toolbar__spacer" />
+      {fileChanged && (
+        <button type="button" className="vg-button" disabled={reloading} onClick={reload}>
+          {unsaved > 0 ? messages.discardAndReload : messages.reload}
+        </button>
+      )}
+      {opened && (
+        <button
+          type="button"
+          className="vg-button"
+          aria-pressed={detail}
+          onClick={() => void store.dispatch({ command: detail ? "detail.close" : "detail.open" })}
+        >
+          {messages.details}
+        </button>
+      )}
+      {filters && (
+        <ToolbarPopover
+          label={conditions > 0 ? messages.conditionsCount(String(conditions)) : messages.conditions}
+          title={messages.conditionsTitle}
+          className="vg-conditions"
+          pressed={conditions > 0}
+        >
+          {(close) => <ConditionsPanel close={close} />}
+        </ToolbarPopover>
+      )}
+      {opened && (
+        <ToolbarPopover label={messages.columns} title={messages.columns} className="vg-columns">
+          {() => <ColumnsPanel />}
+        </ToolbarPopover>
+      )}
+      {groups && (
+        <ToolbarPopover label={messages.groups} title={messages.groups} className="vg-groups" pressed={grouped}>
+          {() => <GroupPanel />}
+        </ToolbarPopover>
+      )}
+      {derives && (
+        <ToolbarPopover label={messages.formulas} title={messages.formulas} className="vg-formulas">
+          {() => <FormulaPanel />}
+        </ToolbarPopover>
+      )}
+      <ExportMenu announce={announce} />
+      {showsSave && (
+        <button
+          type="button"
+          className="vg-button"
+          aria-keyshortcuts={isApple() ? "Meta+S" : "Control+S"}
+          disabled={unsaved === 0 || saving.pending}
+          onClick={saving.save}
+        >
+          {messages.save}
+        </button>
+      )}
+    </div>
+  );
+}

package/src/server.ts

@@ -0,0 +1,58 @@
+/**
+ * What a Server Component or a server render calls (§7 of react.md). Imports no React.
+ */
+import {
+  checkPlan,
+  displayedColumns,
+  emptyDocument,
+  type GridDocument,
+  planOptions,
+  repairDocument,
+} from "vastgrid-spec";
+import { GridClient, type Transport } from "./core/client.js";
+import type { InitialView, OpenOptions, RowsResult, TableInfo } from "./core/types.js";
+
+export interface ReadInitialOptions {
+  /** The `ref` of the table to open (§8.2). */
+  table: string;
+  open?: OpenOptions;
+  /** The document the grid starts with; its plan is the view read. */
+  document?: GridDocument;
+  /** Rows to read from the start of the view; 100 by default. */
+  rows?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Reads the table, the view of a document and its first rows, for `initial` (§7 of react.md): give the result,
+ * or the promise of it, to `DataGrid`. Opens the table and closes it again.
+ */
+export async function readInitialView(transport: Transport, options: ReadInitialOptions): Promise<InitialView> {
+  const client = new GridClient(transport);
+  const info = await client.request<TableInfo>(
+    "open",
+    { ref: options.table, ...(options.open ? { read: options.open } : {}) },
+    options.signal,
+  );
+  try {
+    const document = repairDocument(
+      options.document ?? emptyDocument(),
+      info.columns,
+      planOptions(info.capabilities),
+    ).document;
+    const plan = document.plan ?? {};
+    const view = checkPlan(plan, info.columns, planOptions(info.capabilities));
+    const columns = displayedColumns(document, view.columns).map((item) => item.column.name);
+    if (document.rowKey !== undefined && !columns.includes(document.rowKey)) columns.push(document.rowKey);
+    const wanted = options.rows ?? 100;
+    const end = info.rowCount === null ? wanted : Math.min(wanted, info.rowCount);
+    const rows = await client.request<RowsResult>(
+      "rows",
+      { table: info.table, revision: info.revision, plan, start: 0, end: Math.max(end, 1), columns },
+      options.signal,
+    );
+    return { table: info, plan, rows };
+  } finally {
+    await client.request("close", { table: info.table }).catch(() => {});
+  }
+}