@stigmer/react 3.11.1-dev.20260812192248 → 3.12.1

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

@@ -1,250 +0,0 @@
-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

@@ -1,85 +0,0 @@
-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

@@ -1,111 +0,0 @@
-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

@@ -1,154 +0,0 @@
-// 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.
- *
- * `readableFields` is the caller's column-level read access from
- * `describeDatastore` (the read verb's `readable_fields`; empty means
- * every field). When restricted, unreadable declared fields are not
- * offered — the server refuses conditions on them (the existence-oracle
- * guard), and the builder must stay structurally unable to express an
- * unservable filter (DD-008 invariant 2). System fields are always
- * readable and always offered.
- */
-export function filterableFields(
-  collection: CollectionDeclaration,
-  readableFields?: readonly string[],
-): FilterableField[] {
-  const readable =
-    readableFields !== undefined && readableFields.length > 0 ? new Set(readableFields) : null;
-  const declared: FilterableField[] = [];
-  for (const field of collection.fields) {
-    const operators = operatorsForField(field);
-    if (operators.length === 0) continue; // json — not filterable
-    if (readable !== null && !readable.has(field.name)) continue; // not readable under the grant
-    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);
-}