@agent-native/core 0.123.2 → 0.124.1

package/corpus/templates/crm/app/components/crm/record/field-editors.tsx

@@ -9,10 +9,15 @@
  */
 
 import { useT } from "@agent-native/core/client/i18n";
-import { IconAlertTriangle } from "@tabler/icons-react";
+import { IconAlertTriangle, IconPlus, IconX } from "@tabler/icons-react";
 import { useEffect, useRef, useState } from "react";
 
 import { Input } from "@/components/ui/input";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
 import {
   Select,
   SelectContent,
@@ -29,13 +34,20 @@ import type {
 import {
   activeOptions,
   editorDraftFor,
+  editorInputType,
+  referenceMembers,
+  referenceSearchKind,
+  toggleReferenceValue,
   valueSpecFor,
 } from "../shared/attribute-value";
 import {
   AttributeOptionChip,
   AttributeRating,
 } from "../shared/AttributeValueParts";
+import { RecordReferencePicker } from "../shared/RecordReferencePicker";
+import { overlayProps } from "../shared/ui-tokens";
 import {
+  fieldEditability,
   fieldInputValue,
   formatFieldValue,
   parseFieldInput,
@@ -48,6 +60,7 @@ const CLEAR_OPTION = "__crm_clear__";
 type EditableAttribute = Pick<
   CrmAttributeDefinition,
   | "apiSlug"
+  | "label"
   | "attributeType"
   | "multi"
   | "options"
@@ -134,6 +147,9 @@ export function FieldEditor({
   const [state, setState] = useState(() => editorDraftFor(undefined, seed));
   const [error, setError] = useState<string | null>(null);
   const inputRef = useRef<HTMLInputElement>(null);
+  // Set the moment the input takes focus, cleared by the click that follows.
+  // See `selectOnFocus` below.
+  const selectedOnFocus = useRef(false);
 
   // Re-seeded during render, not from an effect: an effect re-seed lands after
   // the browser has already applied the keystroke it is about to overwrite.
@@ -146,12 +162,64 @@ export function FieldEditor({
     const input = inputRef.current;
     if (!input) return;
     input.focus();
-    // Select, not just focus — the grid does the same. A bare focus leaves the
-    // caret inside the existing text, so the first thing typed is inserted into
-    // the old value rather than replacing it.
+    // Select here as well as in `onFocus`, not instead of it. A programmatic
+    // `focus()` fires no focus event while the document itself is unfocused
+    // (a background tab, a devtools-driven run), so an `onFocus`-only select
+    // silently leaves the caret at the end of the old value and the first
+    // thing typed is appended to it.
     input.select();
   }, [autoFocus]);
 
+  /**
+   * Select the whole value whenever the field takes focus, so the next thing
+   * typed *replaces* it.
+   *
+   * This hangs off focus rather than off `autoFocus` alone because
+   * `FieldEditor` is also rendered as an always-live input (list entry rows),
+   * where nothing ever mounts it focused: a caller that does not pass
+   * `autoFocus` would otherwise get an editor that appends to the old value.
+   * Selecting is the editor's own property, not something each caller has to
+   * remember — that is how the same append bug came back twice.
+   *
+   * The `mouseUp` half matters: when focus came from a click, the browser
+   * places the caret on mouse-up and would drop the selection made here.
+   */
+  const selectOnFocus = {
+    onFocus: (event: React.FocusEvent<HTMLInputElement>) => {
+      selectedOnFocus.current = true;
+      event.currentTarget.select();
+    },
+    onMouseUp: (event: React.MouseEvent<HTMLInputElement>) => {
+      if (!selectedOnFocus.current) return;
+      selectedOnFocus.current = false;
+      event.preventDefault();
+    },
+  };
+
+  const input = editorInputType(attribute);
+
+  /**
+   * Commit what the control actually holds, and refuse when it cannot say.
+   *
+   * `validity.badInput` is the browser reporting "the user typed something I
+   * cannot express" — a half-written date, a stray `e` in a number. In that
+   * state `value` is the empty string, which `parse` reads as *cleared* and
+   * would store as null. Committing it turns a typo into silent data loss, so
+   * the editor says so and keeps the value the record already has.
+   */
+  function commitFromInput(node: HTMLInputElement) {
+    selectedOnFocus.current = false;
+    if (node.validity.badInput) {
+      setError(
+        input.type === "date" || input.type === "datetime-local"
+          ? t("record.invalidDate")
+          : t("record.invalidNumber"),
+      );
+      return;
+    }
+    commit(node.value);
+  }
+
   function commit(raw: string | boolean) {
     const parsed = parseFieldInput(attribute, raw);
     if (!parsed.ok) {
@@ -171,6 +239,21 @@ export function FieldEditor({
     onDone?.();
   }
 
+  /**
+   * Commit a typed value the picker produced directly. It skips text parsing —
+   * a reference display name may contain the comma a multi value splits on —
+   * but not the editability gate, which is what keeps a doomed write off the
+   * wire.
+   */
+  function commitValue(next: CrmValue) {
+    if (!fieldEditability(attribute).editable) {
+      setError(t("record.notEditable"));
+      return;
+    }
+    setError(null);
+    onCommit(next);
+  }
+
   const spec = valueSpecFor(attribute);
 
   if (spec.control === "checkbox") {
@@ -209,27 +292,41 @@ export function FieldEditor({
     );
   }
 
-  // A multi value is a comma-separated list, which no typed input accepts.
-  const inputType = attribute.multi ? "text" : spec.inputType;
+  if (spec.control === "reference") {
+    return (
+      <div className="grid gap-1">
+        <ReferenceField
+          attribute={attribute}
+          value={value}
+          autoFocus={autoFocus}
+          onCommit={commitValue}
+          onDone={onDone}
+        />
+        {error ? <p className="text-xs text-destructive">{error}</p> : null}
+      </div>
+    );
+  }
 
   return (
     <div className="grid gap-1">
       <Input
         ref={inputRef}
         className="h-8"
-        type={inputType}
+        type={input.type}
+        {...(input.inputMode ? { inputMode: input.inputMode } : {})}
         value={draft}
         aria-label={attribute.apiSlug}
         placeholder={attribute.multi ? t("record.multiValueHint") : undefined}
         maxLength={4_000}
+        {...selectOnFocus}
         onChange={(event) =>
           setState({ ...current, draft: event.target.value })
         }
-        onBlur={() => commit(draft)}
+        onBlur={(event) => commitFromInput(event.currentTarget)}
         onKeyDown={(event) => {
           if (event.key === "Enter") {
             event.preventDefault();
-            commit(draft);
+            commitFromInput(event.currentTarget);
           }
           if (event.key === "Escape") {
             event.preventDefault();
@@ -243,3 +340,98 @@ export function FieldEditor({
     </div>
   );
 }
+
+/**
+ * A link to another record: a searchable popover, and the committed value as
+ * chips. `multi` toggles membership instead of replacing, and a chip carries
+ * its own unlink control — the popover would otherwise be the only way to
+ * remove one, which needs the user to search for a record they can already see.
+ */
+function ReferenceField({
+  attribute,
+  value,
+  autoFocus,
+  onCommit,
+  onDone,
+}: {
+  attribute: EditableAttribute;
+  value: CrmValue | undefined;
+  /** The row was just activated, so open the search straight away rather than
+   *  making the user click the value twice to get to a picker. */
+  autoFocus: boolean;
+  onCommit: (next: CrmValue) => void;
+  onDone?: () => void;
+}) {
+  const t = useT();
+  const [open, setOpen] = useState(autoFocus);
+  const members = referenceMembers(value);
+
+  function pick(displayName: string) {
+    onCommit(toggleReferenceValue(value, displayName, attribute.multi));
+    if (!attribute.multi) {
+      setOpen(false);
+      onDone?.();
+    }
+  }
+
+  // `toggleReferenceValue` is a *pick*: on a single reference it replaces, so
+  // reusing it here would re-write the value the user is trying to remove.
+  function unlink(member: string) {
+    onCommit(
+      attribute.multi ? toggleReferenceValue(value, member, true) : null,
+    );
+  }
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) onDone?.();
+      }}
+    >
+      <div className="flex flex-wrap items-center gap-1">
+        {members.map((member) => (
+          <span key={member} className="inline-flex items-center gap-0.5">
+            <AttributeOptionChip token={{ label: member }} />
+            <button
+              type="button"
+              className="cursor-pointer text-content-ghost hover:text-foreground"
+              aria-label={t("record.clearValue")}
+              onClick={() => unlink(member)}
+            >
+              <IconX className="size-3.5" />
+            </button>
+          </span>
+        ))}
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            {...overlayProps({
+              className:
+                "cursor-pointer rounded-lg px-2 py-1 text-left text-sm",
+            })}
+            aria-label={attribute.apiSlug}
+          >
+            {members.length ? (
+              <IconPlus className="size-3.5" />
+            ) : (
+              <span className="text-muted-foreground">
+                {t("record.fieldEmpty")}
+              </span>
+            )}
+          </button>
+        </PopoverTrigger>
+      </div>
+      <PopoverContent align="start" className="p-0">
+        <RecordReferencePicker
+          label={attribute.label}
+          kind={referenceSearchKind(attribute)}
+          selected={members}
+          onPick={pick}
+          onCancel={() => setOpen(false)}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}

package/corpus/templates/crm/app/components/crm/record/panel-resize.ts

@@ -0,0 +1,61 @@
+/**
+ * Width of the record page's left pane.
+ *
+ * Stored as a percentage rather than pixels: a pixel width saved on a wide
+ * monitor reopens as a completely different layout on a laptop. The pane's
+ * floors are enforced in CSS (`min-width` / `max-width`) so a window resize
+ * cannot strand the main pane below its minimum; this clamp exists so the
+ * *stored* value stays sane too.
+ */
+
+import {
+  RECORD_MAIN_MIN_WIDTH,
+  RECORD_PANEL_MIN_WIDTH,
+} from "../shared/ui-tokens";
+
+export const DEFAULT_RECORD_PANEL_PERCENT = 32;
+
+/** Attio caps the pane at 60% of the record region however wide it gets. */
+const MAX_PANEL_PERCENT = 60;
+
+const STORAGE_KEY = "crm.record.panel-percent";
+
+export function clampPanelPercent(
+  percent: number,
+  containerWidth: number,
+): number {
+  if (!Number.isFinite(percent)) return DEFAULT_RECORD_PANEL_PERCENT;
+  if (!Number.isFinite(containerWidth) || containerWidth <= 0)
+    return DEFAULT_RECORD_PANEL_PERCENT;
+  const min = (RECORD_PANEL_MIN_WIDTH / containerWidth) * 100;
+  const max = Math.min(
+    MAX_PANEL_PERCENT,
+    ((containerWidth - RECORD_MAIN_MIN_WIDTH) / containerWidth) * 100,
+  );
+  // Too narrow to satisfy both floors: the main pane wins, because a record
+  // page whose content is 200px wide is useless in a way a thin panel is not.
+  if (max <= min) return Math.max(0, Math.min(100, max));
+  return Math.min(max, Math.max(min, percent));
+}
+
+export function readPanelPercent(): number {
+  if (typeof localStorage === "undefined") return DEFAULT_RECORD_PANEL_PERCENT;
+  try {
+    const stored = Number(localStorage.getItem(STORAGE_KEY));
+    return Number.isFinite(stored) && stored > 0
+      ? stored
+      : DEFAULT_RECORD_PANEL_PERCENT;
+  } catch {
+    return DEFAULT_RECORD_PANEL_PERCENT;
+  }
+}
+
+export function writePanelPercent(percent: number): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(STORAGE_KEY, String(percent));
+  } catch {
+    // A full or blocked localStorage costs the user a remembered width, which
+    // is not worth interrupting a drag over.
+  }
+}

package/corpus/templates/crm/app/components/crm/record/record-data.ts

@@ -96,10 +96,10 @@ export interface CrmRecordPage {
 // ---------------------------------------------------------------------------
 
 /**
- * Controls this panel implements. The registry says a `record-reference` is
- * edited with a record picker; a labelled panel row has no picker yet, so the
- * field is honestly locked here instead of offering a text input that would
- * store whatever display name the user typed.
+ * Controls this panel implements. A type whose control is missing here is
+ * locked with `unsupported-type` rather than offered a text input that would
+ * store whatever the user typed — so this set and the branches in
+ * `field-editors.tsx` have to move together.
  */
 const PANEL_CONTROLS: ReadonlySet<CrmAttributeControl> = new Set([
   "text",
@@ -109,6 +109,7 @@ const PANEL_CONTROLS: ReadonlySet<CrmAttributeControl> = new Set([
   "datetime",
   "options",
   "rating",
+  "reference",
 ]);
 
 export type FieldLockReason =

package/corpus/templates/crm/app/components/crm/shared/README-tokens.md

@@ -0,0 +1,103 @@
+# CRM surface tokens
+
+The grid, record page, and board all style from this layer. Declared in
+`app/global.css`; the JS-only half is `ui-tokens.ts` in this directory.
+
+**Never hardcode a hex, a shadow, or a duration in a component.** If something
+here has no token, add the token rather than the literal.
+
+## Cheat sheet
+
+| Need                     | Use                                                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| Row height (36px, fixed) | `h-9`, or `var(--crm-row-h)` / `ROW_HEIGHT` for virtualizer math                                      |
+| Header height (40px)     | `h-10`, or `var(--crm-header-h)` / `HEADER_HEIGHT`                                                    |
+| Header cell padding      | `px-3` (12px), border-top **and** border-bottom                                                       |
+| Body cell padding        | `px-3 pt-2` (`8px 12px 0`)                                                                            |
+| Divider (both axes)      | `border-hairline` — near-invisible by design, do not reach for `border-border`                        |
+| Hover overlay            | `overlayProps()` → `crm-overlay`                                                                      |
+| Selection overlay        | `overlayProps({ selected })`; cells pass `soft: true`                                                 |
+| Chip / record-ref        | `rounded-chip py-0.5 pr-1.5 pl-1 gap-1.5 self-start`                                                  |
+| Status / select pill     | `rounded-badge` (4px), tinted fill, **no border**                                                     |
+| Avatar                   | person `rounded-full`, company `rounded-avatar-company` (30%), both `ring-1 ring-inset ring-hairline` |
+| Elevation                | `shadow-e1` resting · `shadow-e2` menu/popover/dragging card · `shadow-e3` dialog                     |
+| Sticky-column shadow     | `var(--crm-shadow-sticky)`                                                                            |
+| Motion                   | see below                                                                                             |
+
+## Type
+
+`letter-spacing: -0.02em` is the app default, already applied at `html`. Body
+and caption sizes (`p`, `small`, `.text-sm`, `.text-xs`) relax to `-0.01em`
+automatically. Both rules use `:where()`, so `tracking-ui` / `tracking-body`
+override them wherever a surface needs to be explicit. **Do not add
+`tracking-*` to routine text** — the default is already correct.
+
+Weights are 400/500/600. `font-bold` is capped at 600 in the theme, so a stray
+one is harmless, but write `font-semibold`.
+
+Grid header labels are `text-sm font-medium text-content-secondary` — same size
+as body, not uppercase, not smaller.
+
+Numeric cells: `tabular-nums`.
+
+## Content colors
+
+Alpha over the surface, not solid greys, so they composite correctly on tinted
+cells and under hover overlays.
+
+- `text-foreground` — primary
+- `text-content-secondary` (63%) — header labels, metadata
+- `text-content-tertiary` (50%) — read-only cell values, placeholders
+- `text-content-ghost` (38%) — disabled, empty-value hints
+
+Prefer these over `text-muted-foreground` on grid/record/board surfaces.
+
+## Radii
+
+`rounded-badge` 4 · `rounded-lg` 8 (buttons, menu items) · `rounded-chip` 10 ·
+`rounded-row` 11 · `rounded-card` 12 · `rounded-column` 16 · `rounded-panel` 20.
+
+## Motion
+
+| Token                  | Class          | ms                                                          |
+| ---------------------- | -------------- | ----------------------------------------------------------- |
+| `--motion-fast`        | `duration-80`  | 80 — popovers/dialogs, with `scale .97→1`                   |
+| `--motion-comfortable` | `duration-140` | 140 — **the default; bare `transition-*` is already 140ms** |
+| `--motion-breezy`      | `duration-200` | 200 — chip hover, sticky-shadow fade                        |
+| `--motion-sluggish`    | `duration-300` | 300                                                         |
+| `--motion-sloth`       | `duration-400` | 400                                                         |
+
+Use `duration-[var(--motion-breezy)]` when the value must follow the token
+(e.g. inline styles or JS-driven timing); `MOTION.breezy` for `setTimeout`.
+
+Rules: animate only color, opacity, box-shadow and transform — **never
+layout**. Never `transition-all`; list the properties. Nothing on an
+interaction exceeds 200ms. `ease-drop` is the drop-confirm curve.
+`prefers-reduced-motion` zeroes all of it globally — do not re-handle it.
+
+## The overlay primitive
+
+Hover and selection animate the **opacity of an overlay layer**. They are not
+background-color swaps: a swap cannot composite over a tinted status cell and
+cannot cross-fade.
+
+```tsx
+import { overlayProps } from "@/components/crm/shared/ui-tokens";
+
+<div
+  {...overlayProps({
+    selected: isSelected,
+    className: "flex h-9 items-stretch",
+  })}
+/>;
+```
+
+Content at 4% for hover, accent at 10% for selection; cells pass `soft: true`
+for the 8% content variant. Nesting is intended — a hovered cell inside a
+hovered row stacks to ~8%, which is the behavior we want.
+
+`data-hovered="true"` forces the hover state for keyboard focus or drag-over.
+
+Selection tint derives from `--crm-accent`, which currently points at
+`--primary` because our skin has no brand hue. Repoint that one var if it gains
+one; nothing else should reference an accent directly.

package/corpus/templates/crm/app/components/crm/shared/RecordReferencePicker.tsx

@@ -0,0 +1,117 @@
+/**
+ * The record search behind every `record-reference` / `actor-reference` editor.
+ *
+ * It lives here rather than in either surface because a grid cell and a panel
+ * row must resolve a link the same way: same action, same scope, same "no
+ * matches" wording. Only the wrapper differs — the grid opens it from a cell
+ * popover, the panel from a labelled row.
+ */
+
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import { IconCheck } from "@tabler/icons-react";
+import { useEffect, useRef, useState } from "react";
+
+interface CrmReferenceMatch {
+  id: string;
+  displayName: string;
+  subtitle?: string;
+}
+
+/** Two characters, so a picker never asks the server for "every record". */
+const MIN_QUERY_LENGTH = 2;
+
+export function RecordReferencePicker({
+  label,
+  kind,
+  selected = [],
+  onPick,
+  onCancel,
+}: {
+  /** The attribute's label; shown in the footer hint. */
+  label: string;
+  /** Narrow the search to one record kind, or `null` to search all kinds. */
+  kind: string | null;
+  /** Values already linked, so a multi reference can show and toggle them. */
+  selected?: string[];
+  onPick: (displayName: string) => void;
+  onCancel: () => void;
+}) {
+  const t = useT();
+  const [search, setSearch] = useState("");
+  const inputRef = useRef<HTMLInputElement>(null);
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  const trimmed = search.trim();
+  const results = useActionQuery<{ records?: CrmReferenceMatch[] }>(
+    "list-crm-records" as never,
+    {
+      ...(trimmed ? { query: trimmed } : {}),
+      ...(kind ? { kind } : {}),
+      limit: 8,
+    } as never,
+    { enabled: trimmed.length >= MIN_QUERY_LENGTH } as never,
+  );
+  const records = results.data?.records ?? [];
+  const chosen = new Set(selected);
+
+  return (
+    <div className="w-64">
+      <input
+        ref={inputRef}
+        value={search}
+        onChange={(event) => setSearch(event.target.value)}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") onCancel();
+        }}
+        placeholder={t("grid.searchRecords")}
+        className="w-full border-b border-border/70 bg-transparent px-3 py-2 text-sm outline-none"
+      />
+      <div className="max-h-56 overflow-y-auto py-1">
+        {trimmed.length < MIN_QUERY_LENGTH ? (
+          <p className="px-3 py-2 text-xs text-muted-foreground">
+            {t("grid.searchToLink")}
+          </p>
+        ) : results.isError ? (
+          // A failed search is said out loud: "no matches" would claim the
+          // record does not exist.
+          <p className="px-3 py-2 text-xs text-destructive">
+            {t("grid.searchFailed")}
+          </p>
+        ) : records.length === 0 ? (
+          <p className="px-3 py-2 text-xs text-muted-foreground">
+            {results.isLoading ? t("grid.searching") : t("grid.noMatches")}
+          </p>
+        ) : (
+          records.map((record) => (
+            <button
+              key={record.id}
+              type="button"
+              className="flex w-full cursor-pointer items-center gap-2 px-3 py-1.5 text-left text-sm hover:bg-muted"
+              onClick={() => onPick(record.displayName)}
+            >
+              <span className="min-w-0 flex-1">
+                <span className="block truncate font-medium">
+                  {record.displayName}
+                </span>
+                {record.subtitle ? (
+                  <span className="block truncate text-xs text-muted-foreground">
+                    {record.subtitle}
+                  </span>
+                ) : null}
+              </span>
+              {chosen.has(record.displayName) ? (
+                <IconCheck className="size-3.5 shrink-0" />
+              ) : null}
+            </button>
+          ))
+        )}
+      </div>
+      <p className="border-t border-border/60 px-3 py-1.5 text-[11px] text-muted-foreground">
+        {t("grid.referenceHint", { attribute: label })}
+      </p>
+    </div>
+  );
+}