@multiplatform.one/frappe-ui 7.28.1 → 7.29.0

package/src/recordShape.spec.ts

@@ -0,0 +1,100 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fieldsFromRecord, recordFieldKeys, recordKeyLabel, useRecordShape } from "./recordShape";
+
+const record = {
+  name: "a1b2c3",
+  doctype: "Poke Move",
+  owner: "Administrator",
+  creation: "2026-09-29 09:00:00",
+  modified: "2026-09-29 10:00:00",
+  modified_by: "Administrator",
+  docstatus: 0,
+  idx: 0,
+  _user_tags: null,
+  _comments: null,
+  _assign: null,
+  _liked_by: null,
+  _seen: null,
+  $origin: "remote",
+  $key: "a1b2c3",
+  move_name: "tackle",
+  power: 40,
+  accuracy: 0.95,
+  damage_class: null,
+  effects: [{ name: "row-1" }],
+};
+
+describe("recordShape", () => {
+  it("keeps a record's own scalar keys in server order", () => {
+    expect(recordFieldKeys(record)).toEqual(["move_name", "power", "accuracy", "damage_class"]);
+  });
+
+  it("labels a key the way the desk labels a field", () => {
+    expect(recordKeyLabel("base_experience")).toBe("Base Experience");
+  });
+
+  it("types each field from its value and marks it read-only", () => {
+    expect(fieldsFromRecord(record)).toEqual([
+      { fieldname: "move_name", label: "Move Name", fieldtype: "Data", read_only: 1 },
+      { fieldname: "power", label: "Power", fieldtype: "Int", read_only: 1 },
+      { fieldname: "accuracy", label: "Accuracy", fieldtype: "Float", read_only: 1 },
+      { fieldname: "damage_class", label: "Damage Class", fieldtype: "Data", read_only: 1 },
+    ]);
+  });
+});
+
+describe("useRecordShape", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  function stub(answer: () => Response) {
+    const reads: string[] = [];
+    vi.stubGlobal("fetch", async (input: string | URL | Request) => {
+      reads.push(String(input instanceof Request ? input.url : input));
+      return answer();
+    });
+    return reads;
+  }
+
+  it("reads nothing until asked", () => {
+    const reads = stub(() => new Response("{}"));
+    const { result } = renderHook(() =>
+      useRecordShape({ baseURL: "http://shape.test" }, "Poke Move", false),
+    );
+    expect(result.current).toEqual({ fields: undefined, status: "idle" });
+    expect(reads).toEqual([]);
+  });
+
+  it("samples one record with every field", async () => {
+    const reads = stub(() => Response.json({ data: [record] }));
+    const { result } = renderHook(() =>
+      useRecordShape({ baseURL: "http://shape.test" }, "Poke Move", true),
+    );
+    expect(result.current.status).toBe("pending");
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+    expect(result.current.fields?.map((field) => field.fieldname)).toEqual([
+      "move_name",
+      "power",
+      "accuracy",
+      "damage_class",
+    ]);
+    const url = new URL(reads[0] ?? "");
+    expect(url.pathname).toBe("/api/resource/Poke%20Move");
+    expect(url.searchParams.get("fields")).toBe('["*"]');
+    expect(url.searchParams.get("limit_page_length")).toBe("1");
+  });
+
+  it("calls a refused or empty doctype unreadable", async () => {
+    stub(() => Response.json({ exc_type: "PermissionError" }, { status: 403 }));
+    const refused = renderHook(() =>
+      useRecordShape({ baseURL: "http://refused.test" }, "Poke Move", true),
+    );
+    await waitFor(() => expect(refused.result.current.status).toBe("unreadable"));
+
+    stub(() => Response.json({ data: [] }));
+    const empty = renderHook(() =>
+      useRecordShape({ baseURL: "http://empty.test" }, "Poke Move", true),
+    );
+    await waitFor(() => expect(empty.result.current.status).toBe("unreadable"));
+  });
+});

package/src/recordShape.ts

@@ -0,0 +1,133 @@
+/**
+ * A doctype as far as one of its records shows it.
+ *
+ * DocType meta is permission-gated (Guest gets 403 on getdoctype) while the
+ * records themselves are often readable. A data-aware view that cannot read
+ * meta still owes the reader the weakest honest rendering of what they may
+ * read (LC-96): the record's own fields, labelled from their keys, typed from
+ * their values and read-only. These helpers are that shape, shared by every
+ * view that falls back to it.
+ */
+import { HttpClient, type AuthConfig, type DocTypeField } from "@multiplatform.one/frappe";
+import { useEffect, useMemo, useState } from "react";
+
+/** Keys every Frappe record carries that are bookkeeping, not fields of its doctype. */
+export const recordBookkeepingKeys: ReadonlySet<string> = new Set([
+  "name",
+  "owner",
+  "creation",
+  "modified",
+  "modified_by",
+  "docstatus",
+  "idx",
+  "doctype",
+  "_user_tags",
+  "_comments",
+  "_assign",
+  "_liked_by",
+  "_seen",
+]);
+
+function isFieldValue(value: unknown): value is string | number | null {
+  return value === null || typeof value === "string" || typeof value === "number";
+}
+
+/**
+ * A record's own field keys in the order the server sent them. Bookkeeping
+ * keys, the live collection's `$` props ($origin, $key, $collectionId) and
+ * non-scalar values (child rows, objects) are dropped.
+ */
+export function recordFieldKeys(record: Record<string, unknown>): string[] {
+  return Object.entries(record)
+    .filter(
+      ([key, value]) =>
+        !key.startsWith("$") && !recordBookkeepingKeys.has(key) && isFieldValue(value),
+    )
+    .map(([key]) => key);
+}
+
+/** "base_experience" → "Base Experience", for a key no meta names. */
+export function recordKeyLabel(key: string): string {
+  return key.replace(/_/g, " ").replace(/(^|\s)\S/g, (c) => c.toUpperCase());
+}
+
+/**
+ * The record's own fields as read-only doctype fields: Int or Float for a
+ * number, Data for anything else.
+ */
+export function fieldsFromRecord(record: Record<string, unknown>): DocTypeField[] {
+  return recordFieldKeys(record).map((key) => {
+    const value = record[key];
+    return {
+      fieldname: key,
+      label: recordKeyLabel(key),
+      fieldtype: typeof value === "number" ? (Number.isInteger(value) ? "Int" : "Float") : "Data",
+      read_only: 1,
+    };
+  });
+}
+
+export interface RecordShapeConnection {
+  baseURL?: string;
+  auth?: unknown;
+}
+
+export interface RecordShape {
+  /** The sampled record's fields, once it has been read. */
+  fields: DocTypeField[] | undefined;
+  /**
+   * `idle` when not asked, `pending` while the record is read, `ready` with
+   * fields, `unreadable` when the doctype has no record the reader may see.
+   */
+  status: "idle" | "pending" | "ready" | "unreadable";
+}
+
+/**
+ * Reads one record of `doctype` (`fields: ["*"]`, one row) and returns its
+ * fields. Only reads while `enabled`; a view turns it on when meta is refused.
+ */
+export function useRecordShape(
+  connection: RecordShapeConnection | undefined,
+  doctype: string,
+  enabled: boolean,
+): RecordShape {
+  const baseURL = connection?.baseURL;
+  const auth = connection?.auth;
+  const [sampled, setSampled] = useState<{
+    key: string;
+    fields: DocTypeField[] | undefined;
+  }>();
+  const key = `${baseURL ?? ""}\u0000${doctype}`;
+  const reads = enabled && Boolean(baseURL);
+
+  useEffect(() => {
+    if (!reads || !baseURL) return;
+    let cancelled = false;
+    const http = new HttpClient(baseURL, auth as AuthConfig | undefined);
+    void (async () => {
+      let fields: DocTypeField[] | undefined;
+      try {
+        const response = await http.get<{ data?: Record<string, unknown>[] }>(
+          `/api/resource/${encodeURIComponent(doctype)}`,
+          { fields: ["*"], limit_page_length: 1 },
+        );
+        const sample = response.payload?.data?.[0];
+        fields = sample ? fieldsFromRecord(sample) : undefined;
+      } catch {
+        fields = undefined;
+      }
+      if (!cancelled) setSampled({ key, fields });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [reads, baseURL, auth, doctype, key]);
+
+  return useMemo((): RecordShape => {
+    if (!reads) return { fields: undefined, status: "idle" };
+    if (sampled?.key !== key) return { fields: undefined, status: "pending" };
+    return sampled.fields && sampled.fields.length > 0
+      ? { fields: sampled.fields, status: "ready" }
+      : { fields: undefined, status: "unreadable" };
+  }, [reads, sampled, key]);
+}

package/src/report/ReportGrid.spec.tsx

@@ -0,0 +1,175 @@
+/**
+ * ReportGrid row keyboard contract (LC-49 ONE-TAB-STOP, LC-50
+ * KEY-ACTIVATION, DG-A11Y-06 names).
+ *
+ * The data row is ONE pressable unit: click anywhere activates, Enter AND
+ * Space activate from the keyboard, the data-row set exposes exactly one
+ * tab stop (roving tabindex, arrows/Home/End move it), rows are named by
+ * doc identity, presses on inner interactive content (Link cells) never
+ * reach the row handler, and there is no per-cell pressable chrome inside
+ * body cells. Group header rows are not pressable and hold no tab stop.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { ReportGrid, type ReportGridProps } from "./ReportGrid";
+import { buildGridRows, type ReportColumnDef, type ReportRow } from "./reportViewModel";
+
+const columns: ReportColumnDef[] = [
+  { fieldname: "name", label: "ID", fieldtype: "Data", kind: "text", width: 160, align: "left" },
+  {
+    fieldname: "status",
+    label: "Status",
+    fieldtype: "Select",
+    kind: "select",
+    options: "Open\nClosed",
+    width: 120,
+    align: "left",
+  },
+  {
+    fieldname: "assigned_by",
+    label: "Assigned By",
+    fieldtype: "Link",
+    kind: "link",
+    options: "User",
+    width: 160,
+    align: "left",
+  },
+];
+
+const dataRows: ReportRow[] = [
+  { name: "TD-0001", status: "Open", assigned_by: "alice@example.com" },
+  { name: "TD-0002", status: "Closed", assigned_by: "bob@example.com" },
+  { name: "TD-0003", status: "Open", assigned_by: "carol@example.com" },
+];
+
+function pressRows(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll('[data-report-row="true"]')) as HTMLElement[];
+}
+
+function renderGrid(overrides: Partial<ReportGridProps> = {}) {
+  const onOpenRow = vi.fn();
+  const onOpenLink = vi.fn();
+  const result = renderWithProviders(
+    <ReportGrid
+      columns={columns}
+      rows={buildGridRows(dataRows, 0, 20)}
+      sort={{ field: "modified", order: "desc" }}
+      onSortChange={vi.fn()}
+      columnFilters={{}}
+      onColumnFilterChange={vi.fn()}
+      onOpenRow={onOpenRow}
+      onOpenLink={onOpenLink}
+      totals={[]}
+      {...overrides}
+    />,
+  );
+  return { ...result, onOpenRow, onOpenLink };
+}
+
+describe("ReportGrid row activation (LC-50)", () => {
+  it("activates on a click anywhere in the row with the row's name", () => {
+    const { onOpenRow } = renderGrid();
+    fireEvent.click(screen.getByText("Closed"));
+    expect(onOpenRow).toHaveBeenCalledTimes(1);
+    expect(onOpenRow).toHaveBeenCalledWith("TD-0002");
+  });
+
+  it("activates on Enter AND Space, once per physical key press", () => {
+    const { container, onOpenRow } = renderGrid();
+    const rows = pressRows(container);
+    rows[0].focus();
+
+    fireEvent.keyDown(rows[0], { key: "Enter" });
+    expect(onOpenRow).toHaveBeenCalledTimes(1);
+    expect(onOpenRow).toHaveBeenLastCalledWith("TD-0001");
+
+    fireEvent.keyDown(rows[0], { key: " " });
+    expect(onOpenRow).toHaveBeenCalledTimes(2);
+
+    // Key auto-repeat never machine-guns activations.
+    fireEvent.keyDown(rows[0], { key: "Enter", repeat: true });
+    expect(onOpenRow).toHaveBeenCalledTimes(2);
+  });
+
+  it("names each pressable row by doc identity (DG-A11Y-06)", () => {
+    const { container } = renderGrid();
+    expect(pressRows(container).map((row) => row.getAttribute("aria-label"))).toEqual([
+      "TD-0001",
+      "TD-0002",
+      "TD-0003",
+    ]);
+  });
+});
+
+describe("ReportGrid roving tab stop (LC-49)", () => {
+  it("exposes exactly one tab stop; arrows and Home/End rove it", async () => {
+    const { container } = renderGrid();
+    const rows = pressRows(container);
+    expect(rows).toHaveLength(3);
+    expect(rows.map((row) => row.getAttribute("tabindex"))).toEqual(["0", "-1", "-1"]);
+
+    rows[0].focus();
+    expect(document.activeElement).toBe(rows[0]);
+
+    fireEvent.keyDown(rows[0], { key: "ArrowDown" });
+    expect(document.activeElement).toBe(rows[1]);
+    // The anchor follows focus: still exactly one tabindex=0.
+    await waitFor(() => {
+      const stops = pressRows(container).map((row) => row.getAttribute("tabindex"));
+      expect(stops).toEqual(["-1", "0", "-1"]);
+    });
+
+    fireEvent.keyDown(rows[1], { key: "End" });
+    expect(document.activeElement).toBe(rows[2]);
+    fireEvent.keyDown(rows[2], { key: "Home" });
+    expect(document.activeElement).toBe(rows[0]);
+    fireEvent.keyDown(rows[0], { key: "ArrowUp" });
+    // Clamped at the first row — no wrap.
+    expect(document.activeElement).toBe(rows[0]);
+  });
+
+  it("group header rows are not pressable and hold no tab stop", () => {
+    const { container } = renderGrid({
+      rows: buildGridRows(dataRows, 0, 20, "status"),
+      groupByColumn: columns[1],
+    });
+    // Three data rows stay pressable; the injected group headers are not.
+    expect(pressRows(container)).toHaveLength(3);
+    const groupHeaderCells = Array.from(container.querySelectorAll('[role="rowheader"]'));
+    expect(groupHeaderCells.length).toBeGreaterThan(0);
+    for (const cell of groupHeaderCells) {
+      const groupRow = cell.closest('[role="row"]') as HTMLElement;
+      expect(groupRow.getAttribute("data-report-row")).toBeNull();
+      expect(groupRow.getAttribute("tabindex")).toBeNull();
+    }
+  });
+});
+
+describe("ReportGrid inner interactive content wins", () => {
+  it("a Link cell press opens the linked doc, never the row", () => {
+    const { onOpenRow, onOpenLink } = renderGrid();
+    fireEvent.click(screen.getByText("alice@example.com"));
+    expect(onOpenLink).toHaveBeenCalledTimes(1);
+    expect(onOpenLink).toHaveBeenCalledWith("User", "alice@example.com");
+    expect(onOpenRow).not.toHaveBeenCalled();
+  });
+
+  it("keys on focused inner content belong to that content, not the row", () => {
+    const { onOpenRow } = renderGrid();
+    // Keydown dispatched from the link bubbles to the row, where the
+    // target !== currentTarget guard hands it back to the inner control.
+    fireEvent.keyDown(screen.getByText("alice@example.com"), { key: "Enter" });
+    expect(onOpenRow).not.toHaveBeenCalled();
+  });
+
+  it("renders no per-cell pressable chrome inside body cells", () => {
+    const { container } = renderGrid();
+    const body = container.querySelector("tbody");
+    expect(body).not.toBeNull();
+    // Link cells are the only sanctioned inner interactive content; no
+    // per-cell buttons wrap plain values.
+    expect(body!.querySelectorAll('[role="button"], button')).toHaveLength(0);
+  });
+});