@agent-native/core 0.123.0 → 0.123.1

package/corpus/templates/crm/app/components/crm/grid/query.ts

@@ -0,0 +1,214 @@
+/**
+ * Grid state → server request, and the optimistic cache patch that goes with a
+ * cell write. Kept pure: the grid must never narrow a page it already has, and
+ * that is only provable if the request builder is testable on its own.
+ */
+
+import type { CrmCellValue, CrmGridAttribute } from "./model";
+
+export interface CrmGridSortEntry {
+  attributeId?: string;
+  field?: string;
+  direction: "asc" | "desc";
+}
+
+export interface CrmGridFilterLeaf {
+  attributeId?: string;
+  field?: string;
+  condition: string;
+  value?: string | number | boolean | null | Array<string | number | boolean>;
+}
+
+export interface CrmGridFilter {
+  op: "and" | "or";
+  conditions: CrmGridFilterLeaf[];
+}
+
+export interface CrmGridQueryState {
+  kind?: "account" | "person" | "opportunity";
+  connectionId?: string;
+  viewId?: string;
+  /** Display-name search. Sent to the server; never applied to a loaded page. */
+  search?: string;
+  filter?: CrmGridFilter;
+  sort?: CrmGridSortEntry[];
+  pageSize?: number;
+}
+
+export const CRM_GRID_PAGE_SIZE = 50;
+
+/**
+ * Parameters for `list-crm-records`. Every narrowing input is on the wire —
+ * the grid has no local filter path to fall back to, by construction.
+ */
+export function listRecordsParams(
+  state: CrmGridQueryState,
+  cursor?: string,
+): Record<string, unknown> {
+  const search = state.search?.trim();
+  return {
+    ...(state.kind ? { kind: state.kind } : {}),
+    ...(state.connectionId ? { connectionId: state.connectionId } : {}),
+    ...(state.viewId ? { viewId: state.viewId } : {}),
+    ...(search ? { query: search } : {}),
+    // A saved view owns its filter; sending both is a 422 at the action.
+    ...(state.filter && state.filter.conditions.length && !state.viewId
+      ? { filter: state.filter }
+      : {}),
+    ...(state.sort && state.sort.length ? { sort: state.sort } : {}),
+    limit: state.pageSize ?? CRM_GRID_PAGE_SIZE,
+    ...(cursor ? { cursor } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Column configuration — the saved view's `columns_json`
+// ---------------------------------------------------------------------------
+
+export interface CrmGridColumn {
+  attributeId: string;
+  width?: number;
+  hidden?: boolean;
+}
+
+const MIN_COLUMN_WIDTH = 80;
+const MAX_COLUMN_WIDTH = 720;
+
+/** Accepts both the legacy `string[]` and the typed `columns_json` shape. */
+export function normalizeGridColumns(raw: unknown): CrmGridColumn[] {
+  if (!Array.isArray(raw)) return [];
+  const columns: CrmGridColumn[] = [];
+  for (const entry of raw) {
+    if (typeof entry === "string" && entry) {
+      columns.push({ attributeId: entry });
+      continue;
+    }
+    if (!entry || typeof entry !== "object") continue;
+    const record = entry as Record<string, unknown>;
+    const attributeId =
+      typeof record.attributeId === "string" ? record.attributeId : null;
+    if (!attributeId) continue;
+    const width =
+      typeof record.width === "number" && Number.isFinite(record.width)
+        ? Math.min(Math.max(record.width, MIN_COLUMN_WIDTH), MAX_COLUMN_WIDTH)
+        : undefined;
+    columns.push({
+      attributeId,
+      ...(width === undefined ? {} : { width }),
+      ...(record.hidden === true ? { hidden: true } : {}),
+    });
+  }
+  return columns;
+}
+
+/**
+ * The grid's column order: saved columns first, in their saved order, then any
+ * attribute the saved view has never seen. A saved column whose attribute no
+ * longer exists is dropped rather than rendered as a blank column.
+ */
+export function resolveGridColumns(
+  saved: CrmGridColumn[],
+  attributes: CrmGridAttribute[],
+): CrmGridColumn[] {
+  const known = new Map(
+    attributes.map((attribute) => [attribute.apiSlug, attribute]),
+  );
+  const seen = new Set<string>();
+  const ordered: CrmGridColumn[] = [];
+  for (const column of saved) {
+    if (!known.has(column.attributeId) || seen.has(column.attributeId))
+      continue;
+    seen.add(column.attributeId);
+    ordered.push(column);
+  }
+  for (const attribute of attributes) {
+    if (seen.has(attribute.apiSlug)) continue;
+    ordered.push({ attributeId: attribute.apiSlug });
+  }
+  return ordered;
+}
+
+export function setGridColumnWidth(
+  columns: CrmGridColumn[],
+  attributeId: string,
+  width: number,
+): CrmGridColumn[] {
+  const clamped = Math.min(
+    Math.max(Math.round(width), MIN_COLUMN_WIDTH),
+    MAX_COLUMN_WIDTH,
+  );
+  return columns.map((column) =>
+    column.attributeId === attributeId ? { ...column, width: clamped } : column,
+  );
+}
+
+export function setGridColumnHidden(
+  columns: CrmGridColumn[],
+  attributeId: string,
+  hidden: boolean,
+): CrmGridColumn[] {
+  return columns.map((column) =>
+    column.attributeId === attributeId
+      ? hidden
+        ? { ...column, hidden: true }
+        : {
+            attributeId: column.attributeId,
+            ...(column.width ? { width: column.width } : {}),
+          }
+      : column,
+  );
+}
+
+export function moveGridColumn(
+  columns: CrmGridColumn[],
+  attributeId: string,
+  toIndex: number,
+): CrmGridColumn[] {
+  const from = columns.findIndex(
+    (column) => column.attributeId === attributeId,
+  );
+  if (from < 0) return columns;
+  const next = [...columns];
+  const [moved] = next.splice(from, 1);
+  if (!moved) return columns;
+  next.splice(Math.max(0, Math.min(toIndex, next.length)), 0, moved);
+  return next;
+}
+
+// ---------------------------------------------------------------------------
+// Optimistic cell writes
+// ---------------------------------------------------------------------------
+
+export interface CrmRecordValuesEntry {
+  recordId: string;
+  remoteRevision?: string | null;
+  values: Record<string, CrmCellValue>;
+  valuesSince?: Record<string, string>;
+}
+
+export interface CrmRecordValuesPayload {
+  records: CrmRecordValuesEntry[];
+}
+
+/**
+ * Immutably set one cell in a `list-crm-record-values` payload.
+ *
+ * Returns the SAME object when no record matched, so a caller can tell "wrote
+ * optimistically" from "the row is not in this cache" instead of assuming the
+ * patch landed. Rollback is restoring the previous payload.
+ */
+export function patchRecordValues(
+  payload: CrmRecordValuesPayload | undefined,
+  recordId: string,
+  attributeSlug: string,
+  value: CrmCellValue,
+): CrmRecordValuesPayload | undefined {
+  if (!payload) return payload;
+  let matched = false;
+  const records = payload.records.map((entry) => {
+    if (entry.recordId !== recordId) return entry;
+    matched = true;
+    return { ...entry, values: { ...entry.values, [attributeSlug]: value } };
+  });
+  return matched ? { ...payload, records } : payload;
+}

package/corpus/templates/crm/app/components/crm/record/AttributePanel.tsx

@@ -0,0 +1,192 @@
+/**
+ * The left pane: highlights, then the rest of the object's typed attributes,
+ * each inline-editable when `update-crm-record` would actually accept it.
+ */
+
+import { ExtensionSlot } from "@agent-native/core/client/extensions";
+import { useT } from "@agent-native/core/client/i18n";
+import { IconChevronRight } from "@tabler/icons-react";
+import { useState } from "react";
+
+import type {
+  CrmAttributeDefinition,
+  CrmValue,
+} from "../../../../shared/crm-contract";
+import { FieldEditor, FieldLockNote, FieldValueDisplay } from "./field-editors";
+import { FieldHistoryButton } from "./FieldHistory";
+import {
+  fieldEditability,
+  splitHighlights,
+  withoutSuppressedDuplicates,
+  type CrmRecordPage,
+  type CrmRecordPageValueMeta,
+} from "./record-data";
+
+export function AttributePanel({
+  page,
+  onCommit,
+}: {
+  page: CrmRecordPage;
+  onCommit: (attribute: CrmAttributeDefinition, value: CrmValue) => void;
+}) {
+  const t = useT();
+  const [editingSlug, setEditingSlug] = useState<string | null>(null);
+  const attributes = withoutSuppressedDuplicates(page.attributes, page.values);
+  const { highlights, rest } = splitHighlights(attributes, {
+    kind: page.record.kind,
+    values: page.values,
+  });
+
+  return (
+    <aside className="flex min-h-full w-full flex-col gap-6 border-border/70 p-5 lg:w-[22rem] lg:shrink-0 lg:border-r">
+      <section aria-labelledby="crm-record-highlights">
+        <h2
+          id="crm-record-highlights"
+          className="text-xs font-medium uppercase tracking-[0.12em] text-muted-foreground"
+        >
+          {t("record.highlights")}
+        </h2>
+        <div className="mt-3 grid gap-0.5">
+          {highlights.length ? (
+            highlights.map((attribute) => (
+              <AttributeRow
+                key={attribute.id}
+                recordId={page.record.id}
+                attribute={attribute}
+                value={page.values[attribute.apiSlug]}
+                meta={page.valueMeta[attribute.apiSlug]}
+                isEditing={editingSlug === attribute.apiSlug}
+                onStartEdit={() => setEditingSlug(attribute.apiSlug)}
+                onDone={() => setEditingSlug(null)}
+                onCommit={(value) => onCommit(attribute, value)}
+              />
+            ))
+          ) : (
+            <p className="py-3 text-sm text-muted-foreground">
+              {t("record.noAttributes")}
+            </p>
+          )}
+        </div>
+      </section>
+
+      {rest.length ? (
+        <details open className="group/details">
+          <summary className="flex cursor-pointer list-none items-center gap-1.5 text-xs font-medium uppercase tracking-[0.12em] text-muted-foreground">
+            <IconChevronRight className="size-3.5 transition-transform group-open/details:rotate-90" />
+            {t("record.allAttributes")}
+          </summary>
+          <div className="mt-3 grid gap-0.5">
+            {rest.map((attribute) => (
+              <AttributeRow
+                key={attribute.id}
+                recordId={page.record.id}
+                attribute={attribute}
+                value={page.values[attribute.apiSlug]}
+                meta={page.valueMeta[attribute.apiSlug]}
+                isEditing={editingSlug === attribute.apiSlug}
+                onStartEdit={() => setEditingSlug(attribute.apiSlug)}
+                onDone={() => setEditingSlug(null)}
+                onCommit={(value) => onCommit(attribute, value)}
+              />
+            ))}
+          </div>
+        </details>
+      ) : null}
+
+      {/* Stable extension contract: changing this slot id or context is a migration. */}
+      <ExtensionSlot
+        id="crm.record-sidebar.bottom"
+        context={{
+          recordId: page.record.id,
+          objectType: page.record.objectType,
+          kind: page.record.kind,
+          displayName: page.record.displayName,
+          provider: page.record.provider,
+          values: page.values,
+        }}
+      />
+    </aside>
+  );
+}
+
+function AttributeRow({
+  recordId,
+  attribute,
+  value,
+  meta,
+  isEditing,
+  onStartEdit,
+  onDone,
+  onCommit,
+}: {
+  recordId: string;
+  attribute: CrmAttributeDefinition;
+  value: CrmValue | undefined;
+  meta: CrmRecordPageValueMeta | undefined;
+  isEditing: boolean;
+  onStartEdit: () => void;
+  onDone: () => void;
+  onCommit: (value: CrmValue) => void;
+}) {
+  const t = useT();
+  const editability = fieldEditability(attribute);
+  // Options and checkboxes are always live controls; typing controls swap in
+  // only once the row is activated, so the panel stays readable at rest.
+  const alwaysLive =
+    editability.editable &&
+    (attribute.attributeType === "checkbox" ||
+      (!attribute.multi &&
+        (attribute.attributeType === "status" ||
+          attribute.attributeType === "select")));
+
+  return (
+    <div className="group grid grid-cols-[minmax(6.5rem,0.8fr)_minmax(0,1.2fr)] items-start gap-3 rounded-md px-2 py-1.5 hover:bg-muted/50">
+      <div className="flex min-w-0 items-start gap-1 pt-1">
+        {/* Wrapped, not truncated: a label column this narrow truncates long
+            attribute names (e.g. "Desired Cadence Days") past readability, and
+            a hover-only tooltip would hide the same text at rest. Wrapping
+            keeps the two-column grid and just grows the row. */}
+        <span
+          className="text-sm text-muted-foreground"
+          title={attribute.description ?? attribute.label}
+        >
+          {attribute.label}
+        </span>
+        {attribute.historyTracked ? (
+          <FieldHistoryButton recordId={recordId} attribute={attribute} />
+        ) : null}
+      </div>
+      <div className="min-w-0 text-sm">
+        {alwaysLive || isEditing ? (
+          <FieldEditor
+            attribute={attribute}
+            value={value}
+            autoFocus={isEditing}
+            onCommit={onCommit}
+            onDone={onDone}
+          />
+        ) : editability.editable ? (
+          <button
+            type="button"
+            className="w-full cursor-pointer rounded px-1 py-1 text-left hover:bg-background"
+            onClick={onStartEdit}
+          >
+            <FieldValueDisplay attribute={attribute} value={value} />
+          </button>
+        ) : (
+          <div className="grid gap-1 px-1 py-1">
+            <FieldValueDisplay attribute={attribute} value={value} />
+            <FieldLockNote reason={editability.reason} />
+          </div>
+        )}
+        {meta && !isEditing ? (
+          <p className="mt-0.5 px-1 text-[11px] text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100">
+            {t("record.lastSetBy", {
+              actor: meta.actorId ?? meta.actorType,
+            })}
+          </p>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/corpus/templates/crm/app/components/crm/record/FieldHistory.tsx

@@ -0,0 +1,179 @@
+/**
+ * The "changed from X to Y" affordance next to a history-tracked attribute.
+ *
+ * A dialog rather than a hover card: the template ships no popover primitive,
+ * and the house rule forbids hand-rolling one. History is fetched only when the
+ * dialog opens — the panel would otherwise issue one query per attribute.
+ */
+
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import { IconHistory } from "@tabler/icons-react";
+import { useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Skeleton } from "@/components/ui/skeleton";
+
+import type { CrmAttributeDefinition } from "../../../../shared/crm-contract";
+import { FieldValueDisplay } from "./field-editors";
+import { historyTransitions, type FieldHistoryResponse } from "./record-data";
+
+export function FieldHistoryButton({
+  recordId,
+  entryId,
+  attribute,
+}: {
+  recordId: string;
+  entryId?: string;
+  attribute: Pick<
+    CrmAttributeDefinition,
+    | "apiSlug"
+    | "label"
+    | "attributeType"
+    | "multi"
+    | "options"
+    | "config"
+    | "archived"
+    | "storagePolicy"
+    | "updateable"
+    | "required"
+  >;
+}) {
+  const t = useT();
+  const [open, setOpen] = useState(false);
+  const query = useActionQuery<FieldHistoryResponse>(
+    "list-crm-record-field-history" as never,
+    {
+      recordId,
+      apiSlug: attribute.apiSlug,
+      ...(entryId ? { entryId } : {}),
+    } as never,
+    { enabled: open },
+  );
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="size-6 shrink-0 cursor-pointer text-muted-foreground opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
+          aria-label={t("record.viewHistory", { field: attribute.label })}
+        >
+          <IconHistory className="size-3.5" />
+        </Button>
+      </DialogTrigger>
+      <DialogContent className="sm:max-w-lg">
+        <DialogHeader>
+          <DialogTitle>
+            {t("record.historyTitle", { field: attribute.label })}
+          </DialogTitle>
+          <DialogDescription>
+            {t("record.historyDescription")}
+          </DialogDescription>
+        </DialogHeader>
+        <FieldHistoryBody attribute={attribute} query={query} />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function FieldHistoryBody({
+  attribute,
+  query,
+}: {
+  attribute: React.ComponentProps<typeof FieldValueDisplay>["attribute"] & {
+    label: string;
+  };
+  query: {
+    data?: FieldHistoryResponse;
+    isLoading: boolean;
+    error: unknown;
+  };
+}) {
+  const t = useT();
+  if (query.isLoading) return <Skeleton className="h-24 w-full" />;
+  if (query.error)
+    return (
+      <p className="text-sm text-destructive">
+        {query.error instanceof Error
+          ? query.error.message
+          : t("record.historyLoadFailed")}
+      </p>
+    );
+  const data = query.data;
+  if (!data) return null;
+  // Not tracked and no changes are different answers: one says history is off
+  // for this attribute, the other says it is on and empty.
+  if (!data.historyTracked)
+    return (
+      <p className="text-sm text-muted-foreground">
+        {t("record.historyNotTracked")}
+      </p>
+    );
+  const transitions = historyTransitions(data.changes);
+  if (!transitions.length)
+    return (
+      <p className="text-sm text-muted-foreground">
+        {t("record.historyEmpty")}
+      </p>
+    );
+
+  return (
+    <ol className="divide-y divide-border/70 overflow-y-auto rounded-md border border-border/70">
+      {transitions.map((transition) => (
+        <li key={transition.id} className="grid gap-1 px-3 py-2.5 text-sm">
+          <div className="flex flex-wrap items-center gap-2">
+            {transition.from === undefined ? (
+              <span className="text-muted-foreground">
+                {t("record.historySet")}
+              </span>
+            ) : (
+              <>
+                <span className="text-muted-foreground">
+                  <FieldValueDisplay
+                    attribute={attribute}
+                    value={transition.from}
+                  />
+                </span>
+                <span aria-hidden className="text-muted-foreground">
+                  →
+                </span>
+              </>
+            )}
+            <span className="font-medium">
+              <FieldValueDisplay attribute={attribute} value={transition.to} />
+            </span>
+          </div>
+          <p className="text-xs text-muted-foreground">
+            {t("record.historyBy", {
+              actor: transition.actorId ?? transition.actorType,
+              when: formatWhen(transition.at),
+            })}
+          </p>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+function formatWhen(value: string): string {
+  const date = new Date(value);
+  return Number.isNaN(date.valueOf())
+    ? value
+    : date.toLocaleString(undefined, {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+      });
+}

package/corpus/templates/crm/app/components/crm/record/RecordHeader.tsx

@@ -0,0 +1,103 @@
+/**
+ * Record header: identity, provenance, the upstream deep link, quick actions.
+ */
+
+import { useT } from "@agent-native/core/client/i18n";
+import { IconExternalLink } from "@tabler/icons-react";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import type { CrmRecordDetail } from "@/lib/types";
+
+const PROVIDER_LABELS: Record<string, string> = {
+  hubspot: "HubSpot",
+  salesforce: "Salesforce",
+};
+
+export function RecordHeader({
+  record,
+  recordUrl,
+  recordUrlUnavailableReason,
+  actions,
+}: {
+  record: CrmRecordDetail;
+  recordUrl: string | null;
+  recordUrlUnavailableReason: string | null;
+  actions?: React.ReactNode;
+}) {
+  const t = useT();
+  const providerLabel = record.provider
+    ? PROVIDER_LABELS[record.provider]
+    : undefined;
+
+  return (
+    <header className="border-b border-border/70 px-5 py-4 sm:px-6">
+      <div className="flex flex-wrap items-start justify-between gap-4">
+        <div className="flex min-w-0 items-center gap-3">
+          <RecordAvatar name={record.displayName} kind={record.kind} />
+          <div className="min-w-0">
+            <h1 className="truncate text-xl font-semibold tracking-tight">
+              {record.displayName}
+            </h1>
+            <div className="mt-1 flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground">
+              <span className="capitalize">{record.kind}</span>
+              {record.stage ? (
+                <Badge variant="secondary" className="font-normal">
+                  {record.stage}
+                </Badge>
+              ) : null}
+              {providerLabel ? (
+                <Badge variant="outline" className="font-normal">
+                  {t("record.mirroredFrom", { provider: providerLabel })}
+                </Badge>
+              ) : null}
+              {record.owner ? (
+                <span>{t("record.ownedBy", { owner: record.owner })}</span>
+              ) : null}
+            </div>
+          </div>
+        </div>
+        <div className="flex flex-wrap items-center gap-2">
+          {/* A native record has no upstream record at all, so it shows no link
+              and no "unavailable" note — absent and unavailable are different. */}
+          {providerLabel && recordUrl ? (
+            <Button asChild variant="outline" size="sm" className="gap-1.5">
+              <a href={recordUrl} target="_blank" rel="noopener noreferrer">
+                {t("record.openUpstream", { provider: providerLabel })}
+                <IconExternalLink className="size-4" />
+              </a>
+            </Button>
+          ) : null}
+          {providerLabel && !recordUrl && recordUrlUnavailableReason ? (
+            <span className="text-xs text-muted-foreground">
+              {t("record.upstreamLinkUnavailable", {
+                provider: providerLabel,
+                reason: recordUrlUnavailableReason,
+              })}
+            </span>
+          ) : null}
+          {actions}
+        </div>
+      </div>
+    </header>
+  );
+}
+
+function RecordAvatar({ name, kind }: { name: string; kind: string }) {
+  const initials = name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? "")
+    .join("");
+  return (
+    <div
+      aria-hidden
+      className={`grid size-10 shrink-0 place-items-center text-sm font-semibold text-muted-foreground ${
+        kind === "person" ? "rounded-full" : "rounded-lg"
+      } bg-muted`}
+    >
+      {initials || "?"}
+    </div>
+  );
+}