@carlonicora/nextjs-jsonapi 3.8.2 → 3.10.0

package/src/components/tables/ContentTableSearch.tsx

@@ -78,6 +78,7 @@ export function ContentTableSearch({ data }: ContentTableSearchProps) {
       ) : (
         <Button
           data-testid="content-table-search-trigger"
+          data-help="list.search"
           variant="ghost"
           size="icon-sm"
           className="text-muted-foreground hover:text-foreground absolute top-0 start-0"

package/src/components/viewers/BlockNoteViewer.tsx

@@ -8,6 +8,7 @@ import type { PartialBlock } from "@blocknote/core";
 import { BlockNoteView } from "@blocknote/shadcn";
 import "@blocknote/shadcn/style.css";
 import { useTheme } from "next-themes";
+import { cn } from "../../utils";
 
 function normalize(content: unknown): PartialBlock[] | undefined {
   if (Array.isArray(content) && content.length > 0) return content as PartialBlock[];
@@ -22,10 +23,20 @@ function normalize(content: unknown): PartialBlock[] | undefined {
   return undefined;
 }
 
-export function BlockNoteViewer({ content }: { content: unknown }) {
+export function BlockNoteViewer({ content, size }: { content: unknown; size?: "default" | "sm" }) {
   const editor = useCreateBlockNote({ initialContent: normalize(content) });
   // Outside a next-themes ThemeProvider (public pages) resolvedTheme is
   // undefined, so this falls back to "light".
   const { resolvedTheme } = useTheme();
-  return <BlockNoteView editor={editor} editable={false} theme={resolvedTheme === "dark" ? "dark" : "light"} />;
+  return (
+    <BlockNoteView
+      editor={editor}
+      editable={false}
+      theme={resolvedTheme === "dark" ? "dark" : "light"}
+      // Same two classes BlockNoteEditor applies for its `size` prop: the app
+      // stylesheet keys the compact recipe off `.BlockNoteView.small`, so a
+      // viewer that omits them can only ever render at reading-page size.
+      className={cn("BlockNoteView", size === "sm" && "small")}
+    />
+  );
 }

package/src/components/viewers/BlockNoteViewerContainer.tsx

@@ -5,6 +5,9 @@ import React from "react";
 
 const BlockNoteViewer = dynamic(() => import("./BlockNoteViewer").then((m) => m.BlockNoteViewer), { ssr: false });
 
-export const BlockNoteViewerContainer = React.memo(function ViewerContainer(props: { content: unknown }) {
+export const BlockNoteViewerContainer = React.memo(function ViewerContainer(props: {
+  content: unknown;
+  size?: "default" | "sm";
+}) {
   return <BlockNoteViewer {...props} />;
 });

package/src/contexts/ActionBarContext.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { createContext, ReactNode, useContext } from "react";
+
+/**
+ * True while rendering inside the page action bar (`title.actionBar`, drawn by
+ * RoundPageContainerTitle).
+ *
+ * The action bar is a full-width row of page-level commands, so its buttons
+ * carry a visible label — "Edit", "Delete" — instead of the bare glyph the same
+ * components use in a table row or a sheet header, where horizontal space is
+ * scarce. Commands read the flag through `useIsInActionBar()` rather than
+ * taking a prop, so an app only has to populate `title.actionBar`: everything
+ * it puts there labels itself, and nothing has to be threaded through the
+ * app's own wrapper components.
+ */
+const ActionBarContext = createContext<boolean>(false);
+
+export const ActionBarProvider = ({ value, children }: { value: boolean; children: ReactNode }) => (
+  <ActionBarContext.Provider value={value}>{children}</ActionBarContext.Provider>
+);
+
+export const useIsInActionBar = (): boolean => useContext(ActionBarContext);

package/src/contexts/index.ts

@@ -7,6 +7,7 @@ export * from "../features/user/contexts";
 export * from "../features/how-to/contexts/HowToContext";
 export * from "../features/rbac/contexts/RbacContext";
 export * from "../features/assistant/contexts/AssistantContext";
+export * from "./ActionBarContext";
 export * from "./CommonContext";
 export * from "./DirectionContext";
 export * from "./HeaderChildrenContext";

package/src/features/assistant/components/index.ts

@@ -1,3 +1,5 @@
 export * from "./containers/AssistantContainer";
 export * from "./containers/AssistantPageContainer";
 export * from "./parts/AssistantBlockNoteComposer";
+export * from "./parts/AssistantThread";
+export * from "./parts/AssistantComposer";

package/src/features/assistant/components/parts/AssistantComposer.tsx

@@ -47,7 +47,7 @@ export function AssistantComposer({ onSend, disabled, value: controlled, onValue
           className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
         />
         <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
-          <ArrowUp className="me-1 h-4 w-4" /> {t("ui.buttons.save")}
+          <ArrowUp className="me-1 h-4 w-4" /> {t("features.assistant.send")}
         </Button>
       </div>
       <div className="text-muted-foreground text-end text-xs">{t("features.assistant.keyboard_hint")}</div>

package/src/features/assistant/components/parts/__tests__/AssistantComposer.spec.tsx

@@ -25,8 +25,8 @@ describe("AssistantComposer", () => {
 
   it("Send is disabled on empty/whitespace", () => {
     render(<AssistantComposer onSend={vi.fn()} />);
-    // "save" appears inside the ui.buttons.save key → button text matches /save/i
-    const send = screen.getByRole("button", { name: /save/i });
+    // The send button renders the raw features.assistant.send key under the test intl stub.
+    const send = screen.getByRole("button", { name: /features\.assistant\.send/i });
     expect(send).toBeDisabled();
   });
 });

package/src/features/assistant-action/components/ApprovalActionCard.tsx

@@ -2,7 +2,7 @@
 
 import { ShieldAlert } from "lucide-react";
 import { useTranslations } from "next-intl";
-import { useEffect, useState } from "react";
+import { Fragment, useEffect, useMemo, useState } from "react";
 import { MicroLabel } from "../../../components/typography";
 import { Badge, Button } from "../../../shadcnui";
 import type { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
@@ -35,27 +35,278 @@ const STATUS_LABEL_KEY: Record<AssistantActionStatus, string> = {
   expired: "features.assistant.approval.status.expired",
 };
 
+/**
+ * One referenced record, already resolved to a display name by the API.
+ * `id` exists for React keys only — it is NEVER rendered.
+ */
+interface ProposalRef {
+  id: string;
+  type: string;
+  label: string;
+}
+
+/**
+ * The operator's presentation payload (`AssistantAction.proposal`). Every
+ * referenced record arrives resolved to a name, so the card never has to show
+ * an id — an unknown or out-of-scope record is resolved to "(not found)" by
+ * the API.
+ */
+interface OperatorActionProposal {
+  /** JSON:API type of the record being written. */
+  type: string;
+  /** update / delete / link / unlink: the target record. Absent on create. */
+  target?: ProposalRef;
+  /** create / update: the field values being written. */
+  attributes?: Record<string, unknown>;
+  /** create: related records, resolved. The run's scope relationship is stripped by the API. */
+  relationships?: Record<string, ProposalRef[]>;
+  /** link / unlink: the relationship name… */
+  relationship?: string;
+  /** …and the records being linked or unlinked. */
+  targets?: ProposalRef[];
+}
+
+/**
+ * A parsed `toolArgs` payload, used only as the legacy fallback for actions
+ * created before `proposal` existed.
+ *
+ * NOTE on the key name: `create_entity` / `update_entity` declare the field
+ * values under `fields` (see `agents/operator/tools/entity-write.tools.ts`),
+ * while other producers use the JSON:API-shaped `attributes`. Both are read so
+ * the card never silently degrades to the bare summary. Relationships are NOT
+ * read from here: `toolArgs` carries ids only, and no id is ever rendered.
+ */
+interface LegacyProposal {
+  type: string;
+  attributes: Record<string, unknown>;
+}
+
+interface ProposalRow {
+  key: string;
+  label: string;
+  value: string;
+}
+
+/**
+ * Entity label from a JSON:API type: drop a trailing "s", upper-case the first
+ * letter. Short types (three letters or fewer after singularising) are
+ * acronyms in this domain — "npcs" → "NPC", "pcs" → "PC" — so they are
+ * upper-cased whole.
+ */
+function humaniseType(type: string): string {
+  const singular = type.endsWith("s") ? type.slice(0, -1) : type;
+  if (singular.length <= 3) return singular.toUpperCase();
+  return singular.charAt(0).toUpperCase() + singular.slice(1);
+}
+
+/** `tldr` → `Tldr`, `publicDescription` → `Public description`. */
+function humaniseKey(key: string): string {
+  const words = key
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/**
+ * Plain text of a BlockNote document, without importing BlockNote: walk the
+ * blocks, concatenate the text runs of each block's `content`, recurse into
+ * `children`, and join the blocks with newlines.
+ */
+function blockNoteText(blocks: unknown[]): string {
+  const lines: string[] = [];
+  const walk = (nodes: unknown[]) => {
+    for (const node of nodes) {
+      if (!node || typeof node !== "object") continue;
+      const block = node as { content?: unknown; children?: unknown };
+      const runs = Array.isArray(block.content)
+        ? block.content
+            .map((run) =>
+              run && typeof run === "object" && typeof (run as { text?: unknown }).text === "string"
+                ? (run as { text: string }).text
+                : "",
+            )
+            .join("")
+        : "";
+      if (runs.trim()) lines.push(runs);
+      if (Array.isArray(block.children)) walk(block.children);
+    }
+  };
+  walk(blocks);
+  return lines.join("\n");
+}
+
+/** Returns the blocks when `value` parses as a BlockNote document (an array of `{ type }` blocks). */
+function asBlockNoteDocument(value: string): unknown[] | undefined {
+  if (!value.trimStart().startsWith("[")) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!Array.isArray(parsed) || parsed.length === 0) return undefined;
+    const everyBlock = parsed.every(
+      (block) => !!block && typeof block === "object" && typeof (block as { type?: unknown }).type === "string",
+    );
+    return everyBlock ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Renders one attribute value as text. `undefined` means "skip this row". */
+function formatAttribute(value: unknown, yes: string, no: string): string | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === "boolean") return value ? yes : no;
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : undefined;
+  if (Array.isArray(value)) {
+    const joined = value
+      .map((entry) =>
+        entry === null || entry === undefined ? "" : typeof entry === "object" ? JSON.stringify(entry) : String(entry),
+      )
+      .filter((entry) => entry !== "")
+      .join(", ");
+    return joined === "" ? undefined : joined;
+  }
+  if (typeof value === "string") {
+    if (value.trim() === "") return undefined;
+    const document = asBlockNoteDocument(value);
+    if (!document) return value;
+    const text = blockNoteText(document);
+    return text.trim() === "" ? undefined : text;
+  }
+  if (typeof value === "object") {
+    const serialised = JSON.stringify(value);
+    return serialised === "{}" ? undefined : serialised;
+  }
+  return undefined;
+}
+
+/** Joins the display names of resolved records. `undefined` means "skip this row". */
+function formatRefs(refs: ProposalRef[]): string | undefined {
+  const labels = refs.map((ref) => ref.label).filter((label) => label.trim() !== "");
+  return labels.length ? labels.join(", ") : undefined;
+}
+
+/** A `{ id, type, label }` record, or `undefined` when the entry is not one. */
+function asRef(value: unknown): ProposalRef | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const { id, type, label } = value as { id?: unknown; type?: unknown; label?: unknown };
+  if (typeof label !== "string") return undefined;
+  return {
+    id: typeof id === "string" ? id : "",
+    type: typeof type === "string" ? type : "",
+    label,
+  };
+}
+
+function asRefs(value: unknown): ProposalRef[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const ref = asRef(entry);
+    return ref ? [ref] : [];
+  });
+}
+
+/**
+ * Parses the action's `proposal` — the API's presentation payload, where every
+ * referenced record already carries its display name. Returns `undefined` when
+ * the payload is absent or unparseable, so the card can fall back to the
+ * legacy `toolArgs` attributes.
+ */
+function parseOperatorProposal(proposal: string | undefined): OperatorActionProposal | undefined {
+  if (!proposal) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(proposal);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+
+  const payload = parsed as Record<string, unknown>;
+  const attributes =
+    payload.attributes && typeof payload.attributes === "object" && !Array.isArray(payload.attributes)
+      ? (payload.attributes as Record<string, unknown>)
+      : undefined;
+
+  const relationships: Record<string, ProposalRef[]> = {};
+  if (payload.relationships && typeof payload.relationships === "object" && !Array.isArray(payload.relationships)) {
+    for (const [key, value] of Object.entries(payload.relationships as Record<string, unknown>)) {
+      relationships[key] = asRefs(value);
+    }
+  }
+
+  return {
+    type: typeof payload.type === "string" ? payload.type : "",
+    target: asRef(payload.target),
+    attributes,
+    relationships,
+    relationship: typeof payload.relationship === "string" ? payload.relationship : undefined,
+    targets: asRefs(payload.targets),
+  };
+}
+
+/**
+ * Legacy fallback for actions created before `proposal` existed: parses the
+ * field values out of `toolArgs`. Returns `undefined` whenever the payload is
+ * absent, unparseable or carries no field values — the card then falls back to
+ * the summary alone, which must always still render with its buttons.
+ *
+ * Relationships are deliberately ignored here: `toolArgs` names them by id
+ * only, and an id must never reach the screen.
+ */
+function parseLegacyProposal(toolArgs: string | undefined): LegacyProposal | undefined {
+  if (!toolArgs) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(toolArgs);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+
+  const payload = parsed as Record<string, unknown>;
+  const attributes = payload.attributes ?? payload.fields;
+  if (!attributes || typeof attributes !== "object" || Array.isArray(attributes)) return undefined;
+
+  return {
+    type: typeof payload.type === "string" ? payload.type : "",
+    attributes: attributes as Record<string, unknown>,
+  };
+}
+
 interface Props {
   /** Id of the pending AssistantAction linked to the approval-request message. */
   actionId: string;
   /** Human-readable summary fallback (the approval-request message content). */
   summary?: string;
+  /**
+   * Relationship keys from the proposal that must not be rendered as rows.
+   *
+   * The write tools discard the model's scope relationship and force the run's
+   * own scope, so showing it is noise at best and wrong at worst (the proposal
+   * may name a different record than the one that will actually be written).
+   * The host app names the keys it forces — e.g. `["campaign"]`.
+   */
+  hiddenRelationshipKeys?: string[];
   /** Invoked with the resumed assistant message returned by approve/deny. */
   onResolved?: (message: AssistantMessageInterface) => void;
 }
 
 /**
  * Renders an `approval-request` assistant message as an action card:
- * the destructive-tool summary plus Approve / Deny buttons. Buttons are
- * only actionable while the underlying AssistantAction is `pending`.
+ * the destructive-tool summary, the proposed record (what the assistant wants
+ * to write), plus Approve / Deny buttons. Buttons are only actionable while the
+ * underlying AssistantAction is `pending`.
  *
  * NOTE: plain `<Button>` elements on purpose — never wrapped inside any
  * Base UI trigger component (no nested buttons, no `asChild`).
  */
-export function ApprovalActionCard({ actionId, summary, onResolved }: Props) {
+export function ApprovalActionCard({ actionId, summary, onResolved, hiddenRelationshipKeys }: Props) {
   const t = useTranslations();
   const [status, setStatus] = useState<AssistantActionStatus | undefined>(undefined);
   const [actionSummary, setActionSummary] = useState<string | undefined>(undefined);
+  const [toolName, setToolName] = useState<string | undefined>(undefined);
+  const [toolArgs, setToolArgs] = useState<string | undefined>(undefined);
+  const [actionProposal, setActionProposal] = useState<string | undefined>(undefined);
   const [busy, setBusy] = useState<boolean>(false);
   const [failed, setFailed] = useState<boolean>(false);
 
@@ -67,6 +318,9 @@ export function ApprovalActionCard({ actionId, summary, onResolved }: Props) {
         if (cancelled || !action) return;
         setStatus(action.status);
         setActionSummary(action.summary);
+        setToolName(action.toolName);
+        setToolArgs(action.toolArgs);
+        setActionProposal(action.proposal);
       } catch (error) {
         console.error(`ApprovalActionCard: failed to fetch assistant action ${actionId}`, error);
         if (!cancelled) setFailed(true);
@@ -77,6 +331,53 @@ export function ApprovalActionCard({ actionId, summary, onResolved }: Props) {
     };
   }, [actionId]);
 
+  // The API's resolved payload wins; `toolArgs` is only the legacy fallback
+  // (attributes alone — it names related records by id, which is never shown).
+  const presented = useMemo(() => parseOperatorProposal(actionProposal), [actionProposal]);
+  const legacy = useMemo(() => (presented ? undefined : parseLegacyProposal(toolArgs)), [presented, toolArgs]);
+  const isUpdate = toolName === "update_entity";
+  const entityLabel = humaniseType(presented?.type ?? legacy?.type ?? "");
+  const targetLabel = presented?.target?.label ?? "";
+
+  const rows = useMemo<ProposalRow[]>(() => {
+    const yes = t("features.assistant.approval.proposal.yes");
+    const no = t("features.assistant.approval.proposal.no");
+    const attributes = presented?.attributes ?? legacy?.attributes;
+    const attributeRows = Object.entries(attributes ?? {}).flatMap<ProposalRow>(([key, value]) => {
+      const text = formatAttribute(value, yes, no);
+      return text === undefined ? [] : [{ key: `attribute:${key}`, label: humaniseKey(key), value: text }];
+    });
+    if (!presented) return attributeRows;
+
+    const hidden = new Set(hiddenRelationshipKeys ?? []);
+    const relationshipRows = Object.entries(presented.relationships ?? {}).flatMap<ProposalRow>(([key, refs]) => {
+      if (hidden.has(key)) return [];
+      const text = formatRefs(refs);
+      return text === undefined ? [] : [{ key: `relationship:${key}`, label: humaniseKey(key), value: text }];
+    });
+
+    const linkRows: ProposalRow[] = [];
+    if (presented.relationship) {
+      linkRows.push({
+        key: "link:relationship",
+        label: t("features.assistant.approval.proposal.relationship"),
+        value: humaniseKey(presented.relationship),
+      });
+    }
+    const targetsText = formatRefs(presented.targets ?? []);
+    if (targetsText !== undefined) {
+      linkRows.push({
+        key: "link:records",
+        label: t("features.assistant.approval.proposal.records"),
+        value: targetsText,
+      });
+    }
+
+    return [...attributeRows, ...relationshipRows, ...linkRows];
+  }, [presented, legacy, t, hiddenRelationshipKeys]);
+
+  const hasProposal = rows.length > 0;
+
   const actionable = status === "pending" && !busy && !failed;
 
   const resolve = async (kind: "approve" | "deny") => {
@@ -109,6 +410,26 @@ export function ApprovalActionCard({ actionId, summary, onResolved }: Props) {
         )}
       </MicroLabel>
       <div className="text-foreground text-sm leading-relaxed">{actionSummary ?? summary}</div>
+      {hasProposal && (
+        <div className="border-border/60 flex flex-col gap-2 rounded-lg border border-dashed p-3">
+          <MicroLabel className="text-muted-foreground flex flex-wrap items-baseline gap-x-2">
+            <span>
+              {isUpdate
+                ? t("features.assistant.approval.proposal.updateHeading", { entity: entityLabel })
+                : t("features.assistant.approval.proposal.heading", { entity: entityLabel })}
+            </span>
+            {targetLabel !== "" && <span className="text-foreground tracking-normal normal-case">{targetLabel}</span>}
+          </MicroLabel>
+          <dl className="grid grid-cols-1 gap-x-4 gap-y-1.5 sm:grid-cols-[minmax(0,10rem)_minmax(0,1fr)]">
+            {rows.map((row) => (
+              <Fragment key={row.key}>
+                <dt className="text-muted-foreground text-xs leading-relaxed break-words sm:text-sm">{row.label}</dt>
+                <dd className="text-foreground text-sm leading-relaxed break-words whitespace-pre-wrap">{row.value}</dd>
+              </Fragment>
+            ))}
+          </dl>
+        </div>
+      )}
       {failed && (
         <div role="alert" className="text-destructive text-xs/relaxed">
           {t("features.assistant.approval.error")}