@anchrd/intel-ui 0.32.0 → 0.34.0

package/src/table-columns/table-columns.tsx

@@ -0,0 +1,379 @@
+import type { Node } from "@anchrd/intel-contract/node";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Plus, X } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { Modal } from "@/modal/modal.tsx";
+import { resourceErrorKey } from "@/resource-error.ts";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+/**
+ * Changing a table's header from the UI (#531).
+ *
+ * ⚠️ Adding and renaming are free; removing is confirmed. That asymmetry is the whole point of the
+ * dialog and not a courtesy: a rename keeps every cell, an added column starts empty and takes
+ * nothing away, and a removal is the one gesture whose cost is invisible in this dialog — the cells
+ * stand in the grid behind it, and after the write they are only in the version history.
+ *
+ * ⚠️ The confirmation is a SECOND STEP of this dialog, not `window.confirm` and not a modal over a
+ * modal. It has to name which columns go and how much content goes with them, and a browser prompt
+ * carries neither markup nor the reader's language.
+ */
+type Draft = { key: string; name: string; source: string | null };
+
+/**
+ * The mapping together with the state it was written against (#531, review finding).
+ *
+ * ⚠️ `versionId` is pinned HERE and not read from the query at save time, and that is the whole
+ * optimistic lock. The query behind it shares its key with the grid and refetches on window focus,
+ * so a mapping written against `version-3` would otherwise be sent with whatever version the table
+ * had grown to in the meantime — the server would accept it, and a column somebody else added in
+ * between falls with its cells, because no entry in this mapping names it. Measured in the review:
+ * a refetch between renaming and saving turned `version-3` into `version-9` and the guard never
+ * fired. `columns` and `rows` are pinned with it, so the warning counts the state the reader saw.
+ */
+type Snapshot = {
+  versionId: string | null;
+  columns: string[];
+  rows: string[][];
+  entries: Draft[];
+};
+
+// One entry per column the table will have afterwards, in order — the shape `RedefineTableInput`
+// takes. `source` is the CURRENT name of the column whose cells fill it, so renaming is keeping the
+// source and changing the name, and a current column no entry names is the one that falls.
+//
+// ⚠️ The key of an existing column is its source, not a fresh id. This runs on every render for as
+// long as nothing has been edited, and `crypto.randomUUID()` would hand React a new key each time —
+// every field remounts, and a refetch behind the open dialog takes the caret out of the one being
+// typed in. Sources are distinct on every path that writes a table, so they are already keys.
+function draftOf(columns: string[]): Draft[] {
+  return columns.map((column) => ({ key: `source:${column}`, name: column, source: column }));
+}
+
+// Which current columns no draft entry claims. Reading it off the draft rather than tracking a
+// second "removed" list is what makes taking a removal back the same gesture as adding: there is one
+// list, and it is the answer.
+function droppedFrom(columns: string[], draft: Draft[]): string[] {
+  const kept = new Set(draft.map((entry) => entry.source).filter((source) => source !== null));
+  return columns.filter((column) => !kept.has(column));
+}
+
+/**
+ * How many rows actually lose something.
+ *
+ * ⚠️ Not `rows.length`. Dropping a column nobody ever filled costs nothing, and telling the reader
+ * "42 rows lose cells" when none of them carried content there is a wrong sentence about the one
+ * thing they are being asked to confirm. Counted per row, because a row is what a person sees.
+ */
+function rowsWithContentIn(columns: string[], rows: string[][], dropped: string[]): number {
+  const indexes = dropped.map((column) => columns.indexOf(column)).filter((index) => index >= 0);
+  return rows.filter((row) => indexes.some((index) => (row[index] ?? "") !== "")).length;
+}
+
+export function TableColumnsDialog({ node, close }: { node: Node; close(): void }) {
+  const { data } = useIntelRouterContext();
+  const i18n = useI18n();
+  const queryClient = useQueryClient();
+  // The same key the grid reads under, so the dialog and the table behind it are one loaded state
+  // and never two that disagree about how many columns there are.
+  const table = useQuery({
+    queryKey: ["node-table", node.id],
+    queryFn: () => data.getNodeTable(node.id),
+  });
+  const [draft, setDraft] = useState<Snapshot | null>(null);
+  const [confirming, setConfirming] = useState(false);
+  // The focus on the way back out of the confirmation. A ref alone cannot do it: the button does
+  // not exist yet at the moment the step is left, so the wish is recorded and spent on the render
+  // that brings the form back.
+  const [refocusSave, setRefocusSave] = useState(false);
+  const saveButton = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    if (!refocusSave) return;
+    saveButton.current?.focus();
+    setRefocusSave(false);
+  }, [refocusSave]);
+
+  // ⚠️ Derived rather than seeded through an effect: the query answers after the first render, and
+  // an effect would leave one frame in which the dialog is a form over no rows. The FIRST edit
+  // freezes this into state, and from then on the pinned snapshot is what is read — including its
+  // `versionId`, which is what makes the server's refusal reachable at all.
+  const current: Snapshot = draft ?? {
+    versionId: table.data?.versionId ?? null,
+    columns: table.data?.columns ?? [],
+    rows: table.data?.rows ?? [],
+    entries: draftOf(table.data?.columns ?? []),
+  };
+  const entries = current.entries;
+  const dropped = droppedFrom(current.columns, entries);
+  const losing = rowsWithContentIn(current.columns, current.rows, dropped);
+
+  const names = entries.map((entry) => entry.name.trim());
+  const blank = names.some((name) => name === "");
+  const duplicate = new Set(names.map((name) => name.toLowerCase())).size !== names.length;
+  // ⚠️ The bounds of `TableColumn` and `RedefineTableInput`, mirrored rather than left to the
+  // provider's `parse`. A `ZodError` never reaches `resourceErrorKey` with a code, so it arrives as
+  // "reload the latest version and try again" — advice that cannot help somebody whose column name
+  // is simply too long.
+  //
+  // ⚠️ And it is not `maxLength`'s job: that attribute bounds what is TYPED or pasted, and it does
+  // not touch a value that is already in the field. The header this dialog starts from comes from
+  // the server, and `bundle.ts` checks an imported CSV header against neither bound — so a table
+  // that is already over one of them is where this check earns its place.
+  const tooLong = names.some((name) => name.length > 120);
+  const tooMany = entries.length > 64;
+  const empty = entries.length === 0;
+  const incomplete = empty || blank || duplicate || tooLong || tooMany;
+
+  const save = useMutation({
+    mutationFn: async () => {
+      const idempotencyKey = crypto.randomUUID();
+      // ⚠️ Two calls, because the server has two: `defineTable` refuses on a table that already has
+      // a header, and `redefineTable` refuses on one that has none (`table_undefined`). A table
+      // without a header is reachable through MCP and through the bundle import, so this dialog is
+      // the only place in the UI where such a table can be given one at all.
+      //
+      // ⚠️ `current.versionId`, never `table.data.versionId`: the mapping below was written against
+      // the pinned snapshot, and sending it under a version it was not written against is exactly
+      // the silent wrong-cells move `Snapshot` exists to prevent.
+      const base = current.versionId;
+      if (base === null) {
+        await data.defineTable({ nodeId: node.id, columns: names, idempotencyKey });
+        return;
+      }
+      await data.redefineTable({
+        nodeId: node.id,
+        baseVersionId: base,
+        columns: entries.map((entry, index) => ({
+          name: names[index] ?? "",
+          source: entry.source,
+        })),
+        idempotencyKey,
+      });
+    },
+    onSuccess: async () => {
+      // The grid, the count beside the title and the record itself: the header is drawn from the
+      // first, the summary from the first, and `updatedAt` — which every other change in the menu
+      // sends as `baseUpdatedAt` — from the last.
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: ["node-table", node.id] }),
+        queryClient.invalidateQueries({ queryKey: ["node", node.id] }),
+      ]);
+      close();
+    },
+  });
+
+  // Every edit writes the WHOLE snapshot back, which is what pins the version: the first CHANGE —
+  // a keystroke, a ✕, an added column — is the moment the reader started working against a
+  // particular state of the table.
+  //
+  // ⚠️ Between opening and that first change there is deliberately no guard. Nothing has been
+  // composed yet that points at a particular header, so a version arriving in between is simply the
+  // one the reader is now looking at. Saying otherwise would promise more than is here.
+  function edit(key: string, name: string): void {
+    setDraft({
+      ...current,
+      entries: entries.map((entry) => (entry.key === key ? { ...entry, name } : entry)),
+    });
+  }
+
+  function drop(key: string): void {
+    setDraft({ ...current, entries: entries.filter((entry) => entry.key !== key) });
+  }
+
+  function add(): void {
+    setDraft({
+      ...current,
+      // A fresh id, because an added column has no source to be named after — and no `source:`
+      // prefix, so it can never collide with the key of a column that has one.
+      entries: [...entries, { key: crypto.randomUUID(), name: "", source: null }],
+    });
+  }
+
+  function submit(): void {
+    // Removing is the only branch that asks. Everything else — a rename, an added column, both at
+    // once — goes straight through, because nothing stored is lost by either.
+    if (dropped.length > 0 && !confirming) {
+      setConfirming(true);
+      return;
+    }
+    save.mutate();
+  }
+
+  return (
+    <Modal title={i18n.t("node.table.columnsTitle", { title: node.title })} close={close}>
+      {table.isPending ? (
+        <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+      ) : table.isError ? (
+        <p role="alert" className="text-sm text-destructive">
+          {i18n.t("node.loadFailed")}
+        </p>
+      ) : confirming ? (
+        <div className="space-y-4">
+          {/* ⚠️ `alert`, not `status`: this is the one screen in the dialog that must be read before
+              the button under it is pressed, and it is the only place the cost is named at all. */}
+          <div role="alert" className="space-y-2 rounded-md border border-destructive/30 p-3">
+            {/* ⚠️ One sentence per number, the `.none`/`.one`/`.many` shape `archive.purge.links`
+                already uses for the same job. A single plural template reads as broken German the
+                moment the count is one — "Diese Spalten … : note", "1 Zeilen tragen dort Inhalt" —
+                and this is the screen a reader is asked to trust before losing cells. Found in the
+                browser, not in jsdom: the tests were written around the two-row case. */}
+            <p className="text-sm font-medium text-destructive">
+              {i18n.t(
+                dropped.length === 1
+                  ? "node.table.columnsDropWarning.one"
+                  : "node.table.columnsDropWarning.many",
+                { columns: dropped.join(", ") },
+              )}
+            </p>
+            {/* The honest number, and the honest sentence when it is zero. A column nobody ever
+                filled costs nothing, and saying "42 rows" about it would be the wrong sentence. */}
+            <p className="text-xs text-muted-foreground">
+              {losing === 0
+                ? i18n.t("node.table.columnsDropRows.none")
+                : losing === 1
+                  ? i18n.t("node.table.columnsDropRows.one")
+                  : i18n.t("node.table.columnsDropRows.many", { count: losing })}
+            </p>
+          </div>
+          {save.isError ? (
+            <p role="alert" className="text-sm text-destructive">
+              {i18n.t(resourceErrorKey(save.error))}
+            </p>
+          ) : null}
+          <div className="flex gap-2">
+            {/* The way back is first and it is a real button: somebody who reads the warning and
+                changes their mind must not have to find the × in the corner.
+
+                ⚠️ And it takes the focus, because this step REPLACES the form the focus was in —
+                without it the focus falls to `<body>` and a keyboard reader stands outside the
+                dialog at the one step that destroys something (review finding to #531). The safe
+                button, not the destructive one: focus is where Enter lands. */}
+            <button
+              type="button"
+              // biome-ignore lint/a11y/noAutofocus: the step replaces the focused form; see above
+              autoFocus
+              // ⚠️ And the way BACK carries the focus too. `autoFocus` only fires on the way in;
+              // returning to the form dropped it on `<body>` again — half a keyboard path is the
+              // same defect as none, one step further on (second review round of #531).
+              onClick={() => {
+                setConfirming(false);
+                setRefocusSave(true);
+              }}
+              className="flex-1 rounded-md border px-4 py-2 text-sm font-medium outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              {i18n.t("common.cancel")}
+            </button>
+            <button
+              type="button"
+              onClick={() => save.mutate()}
+              disabled={save.isPending}
+              className="flex-1 rounded-md bg-destructive px-4 py-2 text-sm font-medium text-destructive-foreground outline-none hover:bg-destructive/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+            >
+              {save.isPending ? i18n.t("common.saving") : i18n.t("node.table.columnsDropConfirm")}
+            </button>
+          </div>
+        </div>
+      ) : (
+        <form
+          className="space-y-4"
+          onSubmit={(event) => {
+            event.preventDefault();
+            if (!save.isPending && !incomplete) submit();
+          }}
+        >
+          {save.isError ? (
+            <p role="alert" className="text-sm text-destructive">
+              {i18n.t(resourceErrorKey(save.error))}
+            </p>
+          ) : null}
+          <ul className="max-h-72 space-y-2 overflow-y-auto">
+            {entries.map((entry) => (
+              <li key={entry.key} className="flex items-center gap-2">
+                <label className="min-w-0 flex-1 text-sm">
+                  {/* ⚠️ The name is the accessible name of the field, and it is the CURRENT column's
+                      name rather than a bare "Column": with five fields on screen, five labels
+                      reading the same word leave a screen reader with no way to say which one is
+                      being edited. An added column has no current name and says so. */}
+                  <span className="sr-only">
+                    {entry.source === null
+                      ? i18n.t("node.table.columnNewName")
+                      : i18n.t("node.table.columnName", { column: entry.source })}
+                  </span>
+                  <input
+                    value={entry.name}
+                    // The bound `TableColumn` carries, for what is typed or pasted here. What
+                    // arrives from the server already over it is caught by `tooLong` above.
+                    maxLength={120}
+                    onChange={(event) => edit(entry.key, event.target.value)}
+                    className="w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  />
+                </label>
+                <button
+                  type="button"
+                  onClick={() => drop(entry.key)}
+                  // ⚠️ A column with no name yet has its own label. The fallback used to fill the
+                  // template with an empty string, and the button then announced itself as
+                  // `Die Spalte „" entfernen` — seen in the browser right after adding one.
+                  aria-label={
+                    entry.name.trim() === "" && entry.source === null
+                      ? i18n.t("node.table.columnDropNew")
+                      : i18n.t("node.table.columnDrop", {
+                          column: entry.name.trim() === "" ? (entry.source ?? "") : entry.name,
+                        })
+                  }
+                  className="shrink-0 rounded-md p-2 text-muted-foreground outline-none hover:bg-muted hover:text-destructive focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <X aria-hidden="true" className="size-4" />
+                </button>
+              </li>
+            ))}
+          </ul>
+          <button
+            type="button"
+            onClick={add}
+            disabled={entries.length >= 64}
+            className="flex w-full items-center justify-center gap-2 rounded-md border border-dashed px-4 py-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            <Plus aria-hidden="true" className="size-4" />
+            {i18n.t("node.table.columnAdd")}
+          </button>
+          {/* ⚠️ EVERY reason the button is grey is named while it holds, and there are five. The
+              first version of this listed two and left the empty header — the state a reader
+              reaches by removing the last column — with a dead button and no sentence at all
+              (review finding to #531). A submit that is grey for a reason nobody states is a dialog
+              that has stopped answering. Ordered so the one the reader just caused comes first. */}
+          {duplicate ? (
+            <p role="alert" className="text-sm text-destructive">
+              {i18n.t("node.table.columnsDistinct")}
+            </p>
+          ) : blank ? (
+            <p role="alert" className="text-sm text-destructive">
+              {i18n.t("node.table.columnsNamed")}
+            </p>
+          ) : tooLong ? (
+            <p role="alert" className="text-sm text-destructive">
+              {i18n.t("node.table.columnsTooLong")}
+            </p>
+          ) : tooMany ? (
+            <p role="alert" className="text-sm text-destructive">
+              {i18n.t("node.table.columnsTooMany")}
+            </p>
+          ) : empty ? (
+            <p role="alert" className="text-sm text-destructive">
+              {i18n.t("node.table.columnsAtLeastOne")}
+            </p>
+          ) : null}
+          <button
+            ref={saveButton}
+            type="submit"
+            disabled={save.isPending || incomplete}
+            className="w-full rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            {save.isPending ? i18n.t("common.saving") : i18n.t("common.save")}
+          </button>
+        </form>
+      )}
+    </Modal>
+  );
+}