@stigmer/react 3.2.3 → 3.3.0

package/src/datastore/CollectionSchemaView.tsx

@@ -0,0 +1,247 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { toJson } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import {
+  FieldType,
+  type CollectionDeclaration,
+  type DatastoreAuthorization,
+  type DatastoreSpec,
+  type DatastoreSubject,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/spec_pb";
+import { Section } from "../resource-detail/Section.js";
+import { formatFieldValue } from "./recordValues.js";
+
+/** Props for {@link CollectionSchemaView}. */
+export interface CollectionSchemaViewProps {
+  /** The datastore spec — the authoritative source for structure (DD-008 SD-5). */
+  readonly spec: DatastoreSpec;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Structural view of a datastore's declared schema, rendered from the
+ * loaded resource spec: per-collection typed field tables, the declared
+ * constraints with their authored messages (the operator's own copy —
+ * the same bytes agents relay), and the authorization block summary
+ * (roles, bindings, `default_role` — operator-facing state the
+ * describe projection deliberately excludes).
+ *
+ * Read-only by design: schema changes go through YAML apply, the one
+ * write path for structure.
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * Zero Console dependencies — safe for platform builder embedding.
+ */
+export function CollectionSchemaView({ spec, className }: CollectionSchemaViewProps) {
+  return (
+    <div className={cn("flex flex-col gap-6", className)}>
+      <AuthorizationSummary authorization={spec.authorization} timezone={spec.timezone} />
+      {spec.collections.map((coll) => (
+        <CollectionSchema key={coll.name} collection={coll} />
+      ))}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Authorization block summary
+// ---------------------------------------------------------------------------
+
+function AuthorizationSummary({
+  authorization,
+  timezone,
+}: {
+  readonly authorization: DatastoreAuthorization | undefined;
+  readonly timezone: string;
+}) {
+  const roles = authorization?.roles ?? [];
+  const bindings = authorization?.bindings ?? [];
+  const defaultRole = authorization?.defaultRole ?? "";
+
+  return (
+    <Section title="Authorization">
+      <div className="flex flex-col gap-3 p-3 text-sm">
+        <div className="flex flex-wrap items-center gap-2">
+          <span className="text-xs font-medium text-muted-foreground">Roles</span>
+          {roles.length === 0 ? (
+            <span className="text-xs text-muted-foreground">none declared</span>
+          ) : (
+            roles.map((r) => (
+              <span
+                key={r.name}
+                className="rounded-full bg-muted px-2 py-0.5 text-xs font-medium text-foreground"
+              >
+                {r.name}
+              </span>
+            ))
+          )}
+        </div>
+        <div className="flex flex-wrap items-center gap-2">
+          <span className="text-xs font-medium text-muted-foreground">Default role</span>
+          {defaultRole ? (
+            <span className="rounded-full bg-muted px-2 py-0.5 text-xs font-medium text-foreground">
+              {defaultRole}
+            </span>
+          ) : (
+            <span className="text-xs text-muted-foreground">
+              none — unbound callers are denied
+            </span>
+          )}
+        </div>
+        {bindings.length > 0 && (
+          <div className="flex flex-col gap-1">
+            <span className="text-xs font-medium text-muted-foreground">
+              Bindings ({bindings.length})
+            </span>
+            <ul className="flex flex-col gap-0.5">
+              {bindings.map((b, i) => (
+                <li key={i} className="text-xs text-foreground">
+                  <code className="font-mono">{formatSubject(b.subject)}</code>
+                  <span className="text-muted-foreground"> → </span>
+                  {b.role}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+        {timezone && (
+          <div className="flex items-center gap-2">
+            <span className="text-xs font-medium text-muted-foreground">Timezone</span>
+            <span className="text-xs text-foreground">{timezone}</span>
+          </div>
+        )}
+      </div>
+    </Section>
+  );
+}
+
+/**
+ * Plain kind+value rendering of a datastore subject (DD-008 SD-3: the
+ * grant system is the privacy boundary; display is honest).
+ */
+export function formatSubject(subject: DatastoreSubject | undefined): string {
+  switch (subject?.kind.case) {
+    case "channelSender": {
+      const s = subject.kind.value;
+      return `${s.senderKind}:${s.value}`;
+    }
+    case "principal": {
+      const p = subject.kind.value;
+      return `${p.kind}/${p.id}`;
+    }
+    default:
+      return "unknown";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-collection schema
+// ---------------------------------------------------------------------------
+
+const CONSTRAINT_KIND_LABELS = {
+  uniques: "unique",
+  checks: "check",
+  exists: "exists",
+  notExists: "not exists",
+} as const;
+
+function CollectionSchema({ collection }: { readonly collection: CollectionDeclaration }) {
+  const constraints = [
+    ...collection.uniques.map((c) => ({
+      kind: CONSTRAINT_KIND_LABELS.uniques,
+      name: c.name,
+      fields: c.fields.join(", "),
+      message: c.message,
+    })),
+    ...collection.checks.map((c) => ({
+      kind: CONSTRAINT_KIND_LABELS.checks,
+      name: c.name,
+      fields: "",
+      message: c.message,
+    })),
+    ...collection.exists.map((c) => ({
+      kind: CONSTRAINT_KIND_LABELS.exists,
+      name: c.name,
+      fields: c.collection,
+      message: c.message,
+    })),
+    ...collection.notExists.map((c) => ({
+      kind: CONSTRAINT_KIND_LABELS.notExists,
+      name: c.name,
+      fields: c.collection,
+      message: c.message,
+    })),
+  ];
+
+  return (
+    <Section title={collection.name} count={collection.fields.length}>
+      <div className="flex flex-col">
+        {collection.description && (
+          <p className="border-b border-border px-3 py-2 text-xs text-muted-foreground">
+            {collection.description}
+          </p>
+        )}
+
+        <table className="w-full text-left text-xs">
+          <thead>
+            <tr className="border-b border-border text-muted-foreground">
+              <th scope="col" className="px-3 py-2 font-medium">Field</th>
+              <th scope="col" className="px-3 py-2 font-medium">Type</th>
+              <th scope="col" className="px-3 py-2 font-medium">Required</th>
+              <th scope="col" className="px-3 py-2 font-medium">Default</th>
+              <th scope="col" className="px-3 py-2 font-medium">Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            {collection.fields.map((f) => (
+              <tr key={f.name} className="border-b border-border last:border-b-0">
+                <td className="px-3 py-2 font-mono text-foreground">{f.name}</td>
+                <td className="px-3 py-2 text-foreground">
+                  {FieldType[f.type]}
+                  {f.enumValues.length > 0 && (
+                    <span className="text-muted-foreground">
+                      {" "}
+                      ({f.enumValues.join(" | ")})
+                    </span>
+                  )}
+                </td>
+                <td className="px-3 py-2 text-muted-foreground">{f.required ? "yes" : ""}</td>
+                <td className="px-3 py-2 font-mono text-muted-foreground">
+                  {f.default !== undefined
+                    ? formatFieldValue(f.type, toJson(ValueSchema, f.default))
+                    : ""}
+                </td>
+                <td className="px-3 py-2 text-muted-foreground">{f.description}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+
+        {constraints.length > 0 && (
+          <div className="border-t border-border">
+            <h4 className="px-3 pt-2 text-xs font-medium uppercase tracking-wider text-muted-foreground">
+              Constraints
+            </h4>
+            <ul className="flex flex-col gap-1 p-3">
+              {constraints.map((c) => (
+                <li key={`${c.kind}:${c.name}`} className="flex flex-wrap items-baseline gap-2 text-xs">
+                  <span className="rounded bg-muted px-1.5 py-0.5 font-medium text-muted-foreground">
+                    {c.kind}
+                  </span>
+                  <code className="font-mono text-foreground">{c.name}</code>
+                  {c.fields && <span className="text-muted-foreground">({c.fields})</span>}
+                  {c.message && (
+                    <span className="text-muted-foreground">— “{c.message}”</span>
+                  )}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+    </Section>
+  );
+}

package/src/datastore/DatastoreDetailView.tsx

@@ -0,0 +1,201 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { cn } from "@stigmer/theme";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import type { Datastore } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { ErrorMessage } from "../error/ErrorMessage.js";
+import { ResourceDetailShell } from "../resource-detail/ResourceDetailShell.js";
+import type { DetailAction, ResourceHeaderMeta } from "../resource-detail/types.js";
+import { CollectionRecordsBrowser } from "./CollectionRecordsBrowser.js";
+import { CollectionSchemaView } from "./CollectionSchemaView.js";
+import { DatastoreSyncReport } from "./DatastoreSyncReport.js";
+import { useDatastore } from "./useDatastore.js";
+
+/** The detail view's tabs. */
+export type DatastoreDetailTab = "overview" | "records";
+
+/** Props for {@link DatastoreDetailView}. */
+export interface DatastoreDetailViewProps {
+  /** Organization slug. */
+  readonly org: string;
+  /** Datastore slug. */
+  readonly slug: string;
+  /** Primary action rendered as a visible button. */
+  readonly primaryAction?: DetailAction;
+  /** Overflow actions (Edit YAML / Export / Delete — assembled at the page level). */
+  readonly actions?: readonly DetailAction[];
+  /** Called when the datastore loads or reloads (e.g. breadcrumb label sync). */
+  readonly onResourceLoad?: (datastore: Datastore) => void;
+  /** Initial tab for uncontrolled usage. @default "overview" */
+  readonly defaultTab?: DatastoreDetailTab;
+  /** Controlled active tab. Uncontrolled (internal state) when omitted. */
+  readonly activeTab?: DatastoreDetailTab;
+  /** Tab-change callback for controlled usage. */
+  readonly onTabChange?: (tab: DatastoreDetailTab) => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Self-contained detail view for a Datastore — the Library-resource
+ * home (DD-008 SD-1): an **Overview** tab (schema, authorization
+ * summary, and the sync-report health strip — all from the loaded
+ * resource, the authoritative source for structure and health) and a
+ * **Records** tab (the browser, whose caller-effective verbs come from
+ * `describeDatastore`). No version-history affordance —
+ * `is_versioned: false` (DD-003).
+ *
+ * Handles loading, error, and not-found states automatically.
+ * Zero Console dependencies — safe for platform builder embedding.
+ * All visual properties flow through `--stgm-*` design tokens.
+ */
+export function DatastoreDetailView({
+  org,
+  slug,
+  primaryAction,
+  actions,
+  onResourceLoad,
+  defaultTab = "overview",
+  activeTab,
+  onTabChange,
+  className,
+}: DatastoreDetailViewProps) {
+  const { datastore, isLoading, error, refetch } = useDatastore(org, slug);
+
+  const [internalTab, setInternalTab] = useState<DatastoreDetailTab>(defaultTab);
+  const tab = activeTab ?? internalTab;
+  const setTab = onTabChange ?? setInternalTab;
+
+  useEffect(() => {
+    if (datastore) onResourceLoad?.(datastore);
+  }, [datastore, onResourceLoad]);
+
+  if (isLoading) return <LoadingSkeleton className={className} />;
+  if (error)
+    return <ErrorMessage error={error} retry={refetch} className={className} />;
+  if (!datastore) return <NotFoundState className={className} />;
+
+  const meta = datastore.metadata;
+  const spec = datastore.spec;
+  const status = datastore.status;
+  const specAudit = status?.audit?.specAudit;
+
+  const headerMeta: ResourceHeaderMeta = {
+    name: meta?.name || meta?.slug || "Untitled",
+    id: meta?.id || "",
+    org: meta?.org,
+    slug: meta?.slug,
+    description: spec?.description,
+    icon: <DatastoreIcon className="size-6 text-muted-foreground" />,
+    createdAt: specAudit?.createdAt ? timestampDate(specAudit.createdAt) : null,
+    updatedAt: specAudit?.updatedAt ? timestampDate(specAudit.updatedAt) : null,
+  };
+
+  return (
+    <ResourceDetailShell
+      header={headerMeta}
+      primaryAction={primaryAction}
+      actions={actions}
+      tabs={[
+        { id: "overview", label: "Overview" },
+        { id: "records", label: "Records" },
+      ]}
+      activeTab={tab}
+      onTabChange={(id) => setTab(id as DatastoreDetailTab)}
+      tabsAriaLabel="Datastore sections"
+      className={className}
+    >
+      {tab === "overview" ? (
+        <div className="flex flex-col gap-6">
+          {status && <DatastoreSyncReport status={status} />}
+          {spec && <CollectionSchemaView spec={spec} />}
+        </div>
+      ) : (
+        spec &&
+        meta && (
+          <CollectionRecordsBrowser
+            org={meta.org}
+            datastoreSlug={meta.slug}
+            spec={spec}
+          />
+        )
+      )}
+    </ResourceDetailShell>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Non-happy states
+// ---------------------------------------------------------------------------
+
+function LoadingSkeleton({ className }: { readonly className?: string }) {
+  return (
+    <div
+      className={cn("flex flex-col gap-6", className)}
+      aria-busy="true"
+      aria-label="Loading datastore details"
+    >
+      <div className="flex items-start gap-3">
+        <div className="mt-1 size-6 shrink-0 animate-pulse rounded bg-muted" />
+        <div className="flex-1 space-y-2">
+          <div className="h-5 w-48 animate-pulse rounded bg-muted" />
+          <div className="h-3 w-64 animate-pulse rounded bg-muted" />
+        </div>
+      </div>
+      <div className="space-y-2">
+        <div className="h-3 w-28 animate-pulse rounded bg-muted" />
+        <div
+          className="animate-pulse rounded-lg border border-border bg-muted-faint"
+          style={{ height: "160px" }}
+        />
+      </div>
+      <div className="space-y-2">
+        <div className="h-3 w-20 animate-pulse rounded bg-muted" />
+        <div
+          className="animate-pulse rounded-lg border border-border bg-muted-faint"
+          style={{ height: "240px" }}
+        />
+      </div>
+    </div>
+  );
+}
+
+function NotFoundState({ className }: { readonly className?: string }) {
+  return (
+    <div
+      role="status"
+      className={cn("flex flex-col items-center gap-2 py-12 text-center", className)}
+    >
+      <DatastoreIcon className="size-10 text-muted-foreground-faint" />
+      <p className="text-sm font-medium text-muted-foreground">Datastore not found</p>
+      <p className="text-xs text-muted-foreground-subtle">
+        This datastore doesn&apos;t exist or you don&apos;t have access to it.
+      </p>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icon (inline SVG — no icon-library dependency)
+// ---------------------------------------------------------------------------
+
+/** Database-cylinder icon shared by the detail view's states. */
+export function DatastoreIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <ellipse cx="12" cy="5" rx="8" ry="3" />
+      <path d="M4 5v6c0 1.66 3.58 3 8 3s8-1.34 8-3V5" />
+      <path d="M4 11v6c0 1.66 3.58 3 8 3s8-1.34 8-3v-6" />
+    </svg>
+  );
+}

package/src/datastore/DatastoreSyncReport.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import {
+  CollectionMaterializationState,
+  DatastoreSyncOutcome,
+  type DatastoreStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/status_pb";
+import { Section } from "../resource-detail/Section.js";
+import { StatusBadge } from "../resource-workbench/components/StatusBadge.js";
+
+/** Props for {@link DatastoreSyncReport}. */
+export interface DatastoreSyncReportProps {
+  /** The datastore status — the authoritative source for health (DD-008 SD-5). */
+  readonly status: DatastoreStatus;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * The Overview health strip: projects `DatastoreStatus` — last apply
+ * outcome, per-collection materialization state, and record counts —
+ * so the operator can confirm an apply landed without leaving the
+ * console (the cutover choreography's verification surface, DD-009).
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * Zero Console dependencies — safe for platform builder embedding.
+ */
+export function DatastoreSyncReport({ status, className }: DatastoreSyncReportProps) {
+  const syncedAt = status.lastSyncedAt
+    ? timestampDate(status.lastSyncedAt).toLocaleString()
+    : null;
+
+  return (
+    <Section title="Sync report" className={className}>
+      <div className="flex flex-col">
+        <div className="flex flex-wrap items-center gap-2 border-b border-border px-3 py-2">
+          <SyncOutcomeBadge outcome={status.lastSyncOutcome} />
+          {syncedAt && (
+            <span className="text-xs text-muted-foreground">last synced {syncedAt}</span>
+          )}
+        </div>
+        {status.collections.length === 0 ? (
+          <p className="px-3 py-2 text-xs text-muted-foreground">
+            No collections have been synced yet.
+          </p>
+        ) : (
+          <table className="w-full text-left text-xs">
+            <thead>
+              <tr className="border-b border-border text-muted-foreground">
+                <th scope="col" className="px-3 py-2 font-medium">Collection</th>
+                <th scope="col" className="px-3 py-2 font-medium">State</th>
+                <th scope="col" className="px-3 py-2 text-right font-medium">Records</th>
+              </tr>
+            </thead>
+            <tbody>
+              {status.collections.map((coll) => (
+                <tr key={coll.name} className="border-b border-border last:border-b-0">
+                  <td className="px-3 py-2 font-mono text-foreground">{coll.name}</td>
+                  <td className="px-3 py-2">
+                    <MaterializationBadge state={coll.state} />
+                  </td>
+                  <td className="px-3 py-2 text-right tabular-nums text-foreground">
+                    {String(coll.recordCount)}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </div>
+    </Section>
+  );
+}
+
+function SyncOutcomeBadge({ outcome }: { readonly outcome: DatastoreSyncOutcome }) {
+  switch (outcome) {
+    case DatastoreSyncOutcome.synced:
+      return <StatusBadge phase="ready" label="synced" />;
+    case DatastoreSyncOutcome.rejected:
+      return <StatusBadge phase="failed" label="rejected" />;
+    default:
+      return <StatusBadge phase="draft" label="never synced" />;
+  }
+}
+
+function MaterializationBadge({ state }: { readonly state: CollectionMaterializationState }) {
+  switch (state) {
+    case CollectionMaterializationState.active:
+      return <StatusBadge phase="ready" label="active" />;
+    case CollectionMaterializationState.pending:
+      return <StatusBadge phase="pending" label="pending" />;
+    case CollectionMaterializationState.removed:
+      // Removed from the spec; data retained until datastore delete.
+      return (
+        <StatusBadge
+          phase="disabled"
+          label="removed"
+          tooltip="Removed from the spec — records retained until the datastore is deleted"
+        />
+      );
+    default:
+      return <StatusBadge phase="draft" label="unknown" />;
+  }
+}