@stigmer/react 3.2.3 → 3.3.0

package/src/datastore/__tests__/useRecordCollection.test.tsx

@@ -0,0 +1,250 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  RecordConditionOp,
+  RecordEnvelopeSchema,
+  RecordFilterSchema,
+  RecordListSchema,
+  RecordSortDirection,
+  type FindRecordsRequest,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useRecordCollection, type RecordColumnDef } from "../useRecordCollection";
+
+function envelope(id: string, fields: Record<string, unknown> = {}) {
+  return create(RecordEnvelopeSchema, { id, fields: fields as never });
+}
+
+function recordList(records: ReturnType<typeof envelope>[], total: number) {
+  return create(RecordListSchema, { records, total, limit: 25, offset: 0 });
+}
+
+function createMockStigmer(findRecords: (req: FindRecordsRequest) => Promise<unknown>) {
+  return { datastore: { findRecords } } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+const COLUMNS: readonly RecordColumnDef[] = [
+  { id: "slot_date", header: "Date", cell: (r) => String(r.fields?.["slot_date"] ?? "") },
+  { id: "status", header: "Status", cell: (r) => String(r.fields?.["status"] ?? ""), sortable: true },
+];
+
+const SCOPE = { org: "acme", datastore: "clinic", collection: "bookings" } as const;
+
+describe("useRecordCollection", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("fetches records and reports totals", async () => {
+    const findRecords = vi
+      .fn()
+      .mockResolvedValue(recordList([envelope("dsr_1"), envelope("dsr_2")], 51));
+    const { result } = renderHook(
+      () => useRecordCollection({ ...SCOPE, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.records).toHaveLength(2);
+    expect(result.current.total).toBe(51);
+    expect(result.current.totalPages).toBe(3); // 51 records at page size 25
+    expect(result.current.currentPage).toBe(1);
+  });
+
+  it("translates page/pageSize into RPC limit/offset", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([], 0));
+    renderHook(
+      () => useRecordCollection({ ...SCOPE, page: 3, pageSize: 10, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(findRecords).toHaveBeenCalled());
+    expect(findRecords).toHaveBeenCalledWith(
+      expect.objectContaining({ limit: 10, offset: 20 }),
+    );
+  });
+
+  it("caps the page size at the RPC max of 100 — one surface, one limit", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([], 0));
+    renderHook(
+      () => useRecordCollection({ ...SCOPE, pageSize: 500, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(findRecords).toHaveBeenCalled());
+    expect(findRecords).toHaveBeenCalledWith(expect.objectContaining({ limit: 100 }));
+  });
+
+  it("threads the partition into every fetch (DD-010)", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([], 0));
+    renderHook(
+      () => useRecordCollection({ ...SCOPE, partition: "dr-alt", columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(findRecords).toHaveBeenCalled());
+    expect(findRecords).toHaveBeenCalledWith(
+      expect.objectContaining({ partition: "dr-alt" }),
+    );
+  });
+
+  it("passes the typed proto filter through without adding grammar", async () => {
+    const filter = create(RecordFilterSchema, {
+      conditions: [
+        { field: "status", op: RecordConditionOp.eq, value: { kind: { case: "stringValue", value: "confirmed" } } },
+      ],
+    });
+    const findRecords = vi.fn().mockResolvedValue(recordList([], 0));
+    renderHook(
+      () => useRecordCollection({ ...SCOPE, filter, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(findRecords).toHaveBeenCalled());
+    const request = findRecords.mock.calls[0][0] as FindRecordsRequest;
+    expect(request.filter?.conditions).toHaveLength(1);
+    expect(request.filter?.conditions[0].field).toBe("status");
+  });
+
+  it("builds RecordOrderBy from the controlled sort", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([], 0));
+    renderHook(
+      () =>
+        useRecordCollection({
+          ...SCOPE,
+          sort: { id: "slot_date", direction: "desc" },
+          columns: COLUMNS,
+        }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(findRecords).toHaveBeenCalled());
+    const request = findRecords.mock.calls[0][0] as FindRecordsRequest;
+    expect(request.orderBy?.field).toBe("slot_date");
+    expect(request.orderBy?.direction).toBe(RecordSortDirection.desc);
+  });
+
+  it("reports header sort clicks through onSortChange", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([envelope("dsr_1")], 1));
+    const onSortChange = vi.fn();
+    const { result } = renderHook(
+      () => useRecordCollection({ ...SCOPE, sort: null, onSortChange, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const statusColumn = result.current.table!
+      .getHeaderGroups()[0]
+      .headers.find((h) => h.id === "status")!;
+    act(() => statusColumn.column.toggleSorting(false));
+
+    expect(onSortChange).toHaveBeenCalledWith({ id: "status", direction: "asc" });
+  });
+
+  it("produces a table keyed by envelope id", async () => {
+    const findRecords = vi
+      .fn()
+      .mockResolvedValue(recordList([envelope("dsr_a"), envelope("dsr_b")], 2));
+    const { result } = renderHook(
+      () => useRecordCollection({ ...SCOPE, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.table!.getRowModel().rows.map((r) => r.id)).toEqual([
+      "dsr_a",
+      "dsr_b",
+    ]);
+  });
+
+  it("returns a null table when no columns are provided", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([], 0));
+    const { result } = renderHook(() => useRecordCollection({ ...SCOPE }), {
+      wrapper: wrapper(createMockStigmer(findRecords)),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.table).toBeNull();
+  });
+
+  it("skips fetching when the scope is incomplete", () => {
+    const findRecords = vi.fn();
+    const { result } = renderHook(
+      () =>
+        useRecordCollection({
+          org: "acme",
+          datastore: "clinic",
+          collection: null,
+          columns: COLUMNS,
+        }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    expect(result.current.isLoading).toBe(false);
+    expect(findRecords).not.toHaveBeenCalled();
+  });
+
+  it("surfaces the record-layer denial verbatim — never a silently empty grid", async () => {
+    const denial = new Error("you are not allowed to read records in bookings");
+    const findRecords = vi.fn().mockRejectedValue(denial);
+    const { result } = renderHook(
+      () => useRecordCollection({ ...SCOPE, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error?.message).toBe(
+      "you are not allowed to read records in bookings",
+    );
+  });
+
+  it("refetch re-runs the current query", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([envelope("dsr_1")], 1));
+    const { result } = renderHook(
+      () => useRecordCollection({ ...SCOPE, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(findRecords).toHaveBeenCalledTimes(1);
+
+    act(() => result.current.refetch());
+    await waitFor(() => expect(findRecords).toHaveBeenCalledTimes(2));
+  });
+
+  it("re-fetches when the filter changes", async () => {
+    const findRecords = vi.fn().mockResolvedValue(recordList([], 0));
+    const { rerender } = renderHook(
+      ({ filter }: { filter?: ReturnType<typeof create<typeof RecordFilterSchema>> }) =>
+        useRecordCollection({ ...SCOPE, filter, columns: COLUMNS }),
+      { wrapper: wrapper(createMockStigmer(findRecords)), initialProps: {} },
+    );
+
+    await waitFor(() => expect(findRecords).toHaveBeenCalledTimes(1));
+
+    rerender({
+      filter: create(RecordFilterSchema, {
+        conditions: [{ field: "status", op: RecordConditionOp.is_null }],
+      }),
+    });
+
+    await waitFor(() => expect(findRecords).toHaveBeenCalledTimes(2));
+  });
+});

package/src/datastore/__tests__/useRecordList.test.tsx

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  RecordEnvelopeSchema,
+  RecordListSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useRecordList } from "../useRecordList";
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+const SCOPE = { org: "acme", datastore: "clinic", collection: "bookings" } as const;
+
+describe("useRecordList", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("fetches a page of records", async () => {
+    const list = create(RecordListSchema, {
+      records: [create(RecordEnvelopeSchema, { id: "dsr_1" })],
+      total: 1,
+    });
+    const findRecords = vi.fn().mockResolvedValue(list);
+    const client = { datastore: { findRecords } } as never;
+
+    const { result } = renderHook(() => useRecordList({ ...SCOPE }), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.records).toHaveLength(1);
+    expect(result.current.total).toBe(1);
+    expect(findRecords).toHaveBeenCalledWith(
+      expect.objectContaining({
+        org: "acme",
+        datastore: "clinic",
+        collection: "bookings",
+        partition: "",
+        limit: 0, // unset — the server applies its default of 25
+        offset: 0,
+      }),
+    );
+  });
+
+  it("skips fetching when params is null", () => {
+    const findRecords = vi.fn();
+    const client = { datastore: { findRecords } } as never;
+
+    const { result } = renderHook(() => useRecordList(null), {
+      wrapper: wrapper(client),
+    });
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.records).toEqual([]);
+    expect(findRecords).not.toHaveBeenCalled();
+  });
+
+  it("surfaces the record-layer denial verbatim", async () => {
+    const denial = new Error("you are not allowed to read records in bookings");
+    const client = {
+      datastore: { findRecords: vi.fn().mockRejectedValue(denial) },
+    } as never;
+
+    const { result } = renderHook(() => useRecordList({ ...SCOPE }), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error?.message).toBe(
+      "you are not allowed to read records in bookings",
+    );
+  });
+});

package/src/datastore/index.ts

@@ -0,0 +1,111 @@
+export { useDatastore } from "./useDatastore.js";
+export type { UseDatastoreReturn } from "./useDatastore.js";
+
+export { useDatastoreList } from "./useDatastoreList.js";
+export type {
+  UseDatastoreListOptions,
+  UseDatastoreListReturn,
+} from "./useDatastoreList.js";
+
+export { useDatastoreCount } from "./useDatastoreCount.js";
+export type {
+  UseDatastoreCountOptions,
+  UseDatastoreCountReturn,
+} from "./useDatastoreCount.js";
+
+export { useDatastoreSearch } from "./useDatastoreSearch.js";
+export type {
+  UseDatastoreSearchOptions,
+  UseDatastoreSearchReturn,
+} from "./useDatastoreSearch.js";
+
+export { useDatastoreDescription, DEFAULT_PARTITION } from "./useDatastoreDescription.js";
+export type { UseDatastoreDescriptionReturn } from "./useDatastoreDescription.js";
+
+export { useRecordList } from "./useRecordList.js";
+export type {
+  RecordScope,
+  UseRecordListParams,
+  UseRecordListReturn,
+} from "./useRecordList.js";
+
+export { useInsertRecord } from "./useInsertRecord.js";
+export type {
+  InsertRecordArgs,
+  UseInsertRecordReturn,
+} from "./useInsertRecord.js";
+
+export { useUpdateRecord } from "./useUpdateRecord.js";
+export type {
+  UpdateRecordArgs,
+  UseUpdateRecordReturn,
+} from "./useUpdateRecord.js";
+
+export { useDeleteRecord } from "./useDeleteRecord.js";
+export type {
+  DeleteRecordArgs,
+  UseDeleteRecordReturn,
+} from "./useDeleteRecord.js";
+
+export { useRecordCollection } from "./useRecordCollection.js";
+export type {
+  RecordColumnDef,
+  UseRecordCollectionOptions,
+  UseRecordCollectionReturn,
+} from "./useRecordCollection.js";
+
+export { useDeleteDatastore } from "./useDeleteDatastore.js";
+export type {
+  DeleteDatastoreArgs,
+  UseDeleteDatastoreReturn,
+} from "./useDeleteDatastore.js";
+
+export {
+  buildUpdateFields,
+  coerceFieldValue,
+  formatFieldValue,
+  formatSystemTimestamp,
+  isListOperator,
+  isSortableField,
+  isValuelessOperator,
+  operatorsForField,
+  OPERATOR_LABELS,
+  RESERVED_FIELD_NAMES,
+  SYSTEM_FIELD_OPERATORS,
+} from "./recordValues.js";
+export type { CoerceResult } from "./recordValues.js";
+
+export {
+  buildRecordFilter,
+  filterableFields,
+  formatConditionChip,
+  isConditionComplete,
+} from "./recordFilter.js";
+export type { FilterableField, RecordConditionDraft } from "./recordFilter.js";
+
+export { FieldValueControl, FIELD_INPUT_CLASSES } from "./FieldValueControl.js";
+export type { FieldValueControlProps } from "./FieldValueControl.js";
+
+export { CollectionSchemaView, formatSubject } from "./CollectionSchemaView.js";
+export type { CollectionSchemaViewProps } from "./CollectionSchemaView.js";
+
+export { DatastoreSyncReport } from "./DatastoreSyncReport.js";
+export type { DatastoreSyncReportProps } from "./DatastoreSyncReport.js";
+
+export { RecordFilterBuilder } from "./RecordFilterBuilder.js";
+export type { RecordFilterBuilderProps } from "./RecordFilterBuilder.js";
+
+export { RecordFormPanel } from "./RecordFormPanel.js";
+export type { RecordFormPanelProps } from "./RecordFormPanel.js";
+
+export { CollectionRecordsBrowser } from "./CollectionRecordsBrowser.js";
+export type { CollectionRecordsBrowserProps } from "./CollectionRecordsBrowser.js";
+
+export { DeleteDatastoreDialog } from "./DeleteDatastoreDialog.js";
+export type { DeleteDatastoreDialogProps } from "./DeleteDatastoreDialog.js";
+
+export { DatastoreDetailView, DatastoreIcon } from "./DatastoreDetailView.js";
+export type {
+  DatastoreDetailTab,
+  DatastoreDetailViewProps,
+} from "./DatastoreDetailView.js";

package/src/datastore/recordFilter.ts

@@ -0,0 +1,140 @@
+// The records-specific filter model (DD-008 SD-3) — typed 1:1 against
+// `RecordConditionOp`.
+//
+// Deliberately NOT the workbench `FilterDef`/`FilterValue` model: its
+// `string | string[]` value shape cannot carry typed values or
+// value-less null operators, and its operator set includes `contains`,
+// which `findRecords` cannot serve. Welding a server-grammar contract
+// onto a client-filter model would couple two contracts that evolve
+// independently — so this model mirrors the RPC grammar exactly and can
+// express nothing the RPC cannot serve (DD-008 invariant 2).
+
+import { create, fromJson, type JsonValue } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import {
+  RecordConditionOp,
+  RecordConditionSchema,
+  RecordFilterSchema,
+  type RecordFilter,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import {
+  FieldType,
+  type CollectionDeclaration,
+  type FieldDeclaration,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/spec_pb";
+import {
+  isListOperator,
+  isValuelessOperator,
+  OPERATOR_LABELS,
+  SYSTEM_FIELD_OPERATORS,
+  operatorsForField,
+} from "./recordValues.js";
+
+/**
+ * One draft condition in the filter builder — the client-side twin of
+ * the proto `RecordCondition`, with plain JSON values (converted to
+ * `google.protobuf.Value` only at request-build time).
+ */
+export interface RecordConditionDraft {
+  /** Declared field name, or a filterable system field (`id`, `created_at`, `updated_at`). */
+  readonly field: string;
+  /** Comparison operator — must be admitted by the field's operator set. */
+  readonly op: RecordConditionOp;
+  /** Scalar comparison value. Absent for `is_null`/`not_null` and list operators. */
+  readonly value?: JsonValue;
+  /** Comparison values for `is_in`/`not_in`. */
+  readonly values?: readonly JsonValue[];
+}
+
+/**
+ * A field the builder can offer: a declared filterable field or a
+ * filterable system field, with the exact operator set the server
+ * admits for it.
+ */
+export interface FilterableField {
+  readonly name: string;
+  /** The declaration, or `undefined` for system fields. */
+  readonly declaration?: FieldDeclaration;
+  /** The field type driving the value control (system fields use fixed types). */
+  readonly type: FieldType;
+  readonly operators: readonly RecordConditionOp[];
+}
+
+/**
+ * The fields a collection's filter builder offers: declared filterable
+ * fields (json is not filterable) followed by the filterable system
+ * fields. `id` conditions take string values; the audit timestamps take
+ * RFC 3339 timestamps — both ride the `timestamp`/`string` value
+ * controls.
+ */
+export function filterableFields(collection: CollectionDeclaration): FilterableField[] {
+  const declared: FilterableField[] = [];
+  for (const field of collection.fields) {
+    const operators = operatorsForField(field);
+    if (operators.length === 0) continue; // json — not filterable
+    declared.push({ name: field.name, declaration: field, type: field.type, operators });
+  }
+  return [
+    ...declared,
+    { name: "id", type: FieldType.string, operators: SYSTEM_FIELD_OPERATORS.get("id")! },
+    {
+      name: "created_at",
+      type: FieldType.timestamp,
+      operators: SYSTEM_FIELD_OPERATORS.get("created_at")!,
+    },
+    {
+      name: "updated_at",
+      type: FieldType.timestamp,
+      operators: SYSTEM_FIELD_OPERATORS.get("updated_at")!,
+    },
+  ];
+}
+
+/**
+ * Whether a draft is complete enough to serve: value-less operators
+ * need nothing, list operators need at least one value, scalar
+ * operators need a value.
+ */
+export function isConditionComplete(draft: RecordConditionDraft): boolean {
+  if (draft.op === RecordConditionOp.record_condition_op_unspecified) return false;
+  if (isValuelessOperator(draft.op)) return true;
+  if (isListOperator(draft.op)) return (draft.values?.length ?? 0) > 0;
+  return draft.value !== undefined;
+}
+
+/**
+ * Build the proto `RecordFilter` from complete drafts. Returns
+ * `undefined` for an empty set (an absent filter, not an empty one, is
+ * the RPC's "no filter").
+ */
+export function buildRecordFilter(
+  conditions: readonly RecordConditionDraft[],
+): RecordFilter | undefined {
+  const complete = conditions.filter(isConditionComplete);
+  if (complete.length === 0) return undefined;
+  return create(RecordFilterSchema, {
+    conditions: complete.map((draft) =>
+      create(RecordConditionSchema, {
+        field: draft.field,
+        op: draft.op,
+        value: draft.value !== undefined ? fromJson(ValueSchema, draft.value) : undefined,
+        values: (draft.values ?? []).map((v) => fromJson(ValueSchema, v)),
+      }),
+    ),
+  });
+}
+
+/** Chip text for an active condition, e.g. `status = confirmed` or `notes is empty`. */
+export function formatConditionChip(draft: RecordConditionDraft): string {
+  const op = OPERATOR_LABELS.get(draft.op) ?? "?";
+  if (isValuelessOperator(draft.op)) return `${draft.field} ${op}`;
+  if (isListOperator(draft.op)) {
+    return `${draft.field} ${op} [${(draft.values ?? []).map(formatChipValue).join(", ")}]`;
+  }
+  return `${draft.field} ${op} ${formatChipValue(draft.value)}`;
+}
+
+function formatChipValue(value: JsonValue | undefined): string {
+  if (value === undefined || value === null) return "";
+  return typeof value === "string" ? value : JSON.stringify(value);
+}