@cueplusplus/ui 0.20.1 → 0.22.0

package/manifest/components/approval-card.json

@@ -71,7 +71,7 @@
       "type": "(() => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when the user clicks Always allow.",
+      "description": "Called when the user clicks Always allow. The button is drawn only when this is\nset, so a card never offers a standing grant nothing can honour.",
       "control": {
         "kind": "callback",
         "fixture": "callback.log"
@@ -87,10 +87,46 @@
         "kind": "callback",
         "fixture": "callback.log"
       }
+    },
+    {
+      "name": "options",
+      "type": "readonly ApprovalOption[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "The decisions the agent offered, one button each and in this order. Replaces the\ndefault Deny, Always allow and Allow once.",
+      "control": {
+        "kind": "array"
+      }
+    },
+    {
+      "name": "onDecide",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with an option's `id` when the user picks it.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "delivery",
+      "type": "\"failed\" | \"sending\" | \"sent\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where the answer has got to: `sending`, `sent` or `failed`. While it is on its way\nand once it has arrived, the card offers nothing to press. `failed` offers the\ndecisions again. An outcome `state` wins over it.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "failed",
+          "sending",
+          "sent"
+        ]
+      }
     }
   ],
   "typeReferences": [
-    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"state\"\n  | \"command\"\n  | \"title\"\n  | \"subtitle\"\n  | \"onAllowOnce\"\n  | \"onAlwaysAllow\"\n  | \"onDeny\"\n> & {\n  /** Lifecycle of the card: request with actions, running spinner, done check, or denied. */\n  state: ApprovalState;\n  /** Command shown in the mono field the agent wants to run. */\n  command: string;\n  /** Headline naming the action that needs approval. */\n  title: string;\n  /** Supporting line under the title explaining the request. */\n  subtitle: string;\n  /** Called when the user clicks Allow once. */\n  onAllowOnce?: () => void;\n  /** Called when the user clicks Always allow. */\n  onAlwaysAllow?: () => void;\n  /** Called when the user clicks Deny. */\n  onDeny?: () => void;\n}"
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"state\"\n  | \"command\"\n  | \"title\"\n  | \"subtitle\"\n  | \"onAllowOnce\"\n  | \"onAlwaysAllow\"\n  | \"onDeny\"\n  | \"options\"\n  | \"onDecide\"\n  | \"delivery\"\n> & {\n  /** Lifecycle of the card: request with actions, running spinner, done check, or denied. */\n  state: ApprovalState;\n  /** Command shown in the mono field the agent wants to run. */\n  command: string;\n  /** Headline naming the action that needs approval. */\n  title: string;\n  /** Supporting line under the title explaining the request. */\n  subtitle: string;\n  /** Called when the user clicks Allow once. */\n  onAllowOnce?: () => void;\n  /**\n   * Called when the user clicks Always allow. The button is drawn only when this is\n   * set, so a card never offers a standing grant nothing can honour.\n   */\n  onAlwaysAllow?: () => void;\n  /** Called when the user clicks Deny. */\n  onDeny?: () => void;\n  /**\n   * The decisions the agent offered, one button each and in this order. Replaces the\n   * default Deny, Always allow and Allow once.\n   */\n  options?: readonly ApprovalOption[];\n  /** Called with an option's `id` when the user picks it. */\n  onDecide?: (id: string) => void;\n  /**\n   * Where the answer has got to: `sending`, `sent` or `failed`. While it is on its way\n   * and once it has arrived, the card offers nothing to press. `failed` offers the\n   * decisions again. An outcome `state` wins over it.\n   */\n  delivery?: RequestDelivery;\n}"
   ],
   "subcomponents": [],
   "parts": [],
@@ -122,14 +158,16 @@
   "jsonUrl": "/r/components/approval-card.json",
   "whenToUse": [
     "A command with side effects that must not run until someone says so.",
-    "Carrying that request through its whole lifecycle, since one card covers request, running, done and denied."
+    "Carrying that request through its whole lifecycle, since one card covers request, running, done and denied.",
+    "Drawing exactly the decisions the agent offered. Pass `options` with `onDecide`, and only those buttons appear."
   ],
   "whenNotToUse": [
     "A decision with no command behind it. `command` is required and is shown in a mono field.",
     "Reporting a command that failed. The four states are request, running, done and denied; a failure needs somewhere else to go."
   ],
   "commonMistakes": [
-    "Leaving `state=\"request\"` after the user has answered, so Allow and Deny stay pressable on a command that already ran.",
+    "Leaving `state=\"request\"` after the user has answered with no `delivery`, so Allow and Deny stay pressable. Set `delivery=\"sending\"` as the answer leaves.",
+    "Passing a no-op `onAlwaysAllow`. Always allow is drawn only when the handler is set, so set it only when a standing grant can be honoured.",
     "Folding the explanation into `title`. `title` names the action that needs approval; `subtitle` is the supporting line that explains it."
   ],
   "specimens": [
@@ -139,9 +177,9 @@
       "components": [
         "ApprovalCard"
       ],
-      "code": "<Specimens>\n  {APPROVALS.map((state) => (\n    <Specimen key={state} label={state} wide>\n      <ApprovalCard\n        state={approvals[state] ?? state}\n        command=\"cue unpatch --universe 4 --all\"\n        title=\"Unpatch universe 4\"\n        subtitle=\"48 channels stop responding until they are patched again.\"\n        onAllowOnce={settle(state, \"running\")}\n        onAlwaysAllow={settle(state, \"running\")}\n        onDeny={settle(state, \"denied\")}\n      />\n    </Specimen>\n  ))}\n</Specimens>",
-      "note": "Human in the loop for one action: the command in mono exactly as it will run, and three answers. The four specimens are the four states of the union, and the first one is live: answer it and it moves.",
-      "interaction": "Allow once and Always allow are separate answers, never one control with a modifier. Denying settles the card rather than hiding it."
+      "code": "<Specimens>\n  {APPROVALS.map((state) => (\n    <Specimen key={state} label={state} wide>\n      <ApprovalCard\n        state={approvals[state] ?? state}\n        command=\"cue unpatch --universe 4 --all\"\n        title=\"Unpatch universe 4\"\n        subtitle=\"48 channels stop responding until they are patched again.\"\n        onAllowOnce={settle(state, \"running\")}\n        onAlwaysAllow={settle(state, \"running\")}\n        onDeny={settle(state, \"denied\")}\n      />\n    </Specimen>\n  ))}\n  <Specimen label=\"the agent's own decisions\" wide>\n    <ApprovalCard\n      state=\"request\"\n      command=\"cue patch --universe 3 --fixtures 6\"\n      title=\"Patch universe 3\"\n      subtitle=\"The agent offered two answers, so the card draws two.\"\n      options={[\n        { id: \"reject\", label: \"Reject\" },\n        { id: \"approve\", label: \"Approve\", tone: \"primary\" },\n      ]}\n      onDecide={() => {}}\n    />\n  </Specimen>\n  <Specimen label=\"sending\" wide>\n    <ApprovalCard\n      state=\"request\"\n      delivery=\"sending\"\n      command=\"cue unpatch --universe 4 --all\"\n      title=\"Unpatch universe 4\"\n      subtitle=\"48 channels stop responding until they are patched again.\"\n    />\n  </Specimen>\n  <Specimen label=\"not sent\" wide>\n    <ApprovalCard\n      state=\"request\"\n      delivery=\"failed\"\n      command=\"cue unpatch --universe 4 --all\"\n      title=\"Unpatch universe 4\"\n      subtitle=\"48 channels stop responding until they are patched again.\"\n      onAllowOnce={() => {}}\n      onDeny={() => {}}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Human in the loop for one action: the command in mono exactly as it will run, and the answers the agent offered. The first four specimens are the four states of the union, and the first one is live: answer it and it moves. Then a card drawing the agent's own two decisions rather than the default three, and two deliveries: an answer on its way, which offers nothing to press, and one that did not arrive, which offers the answers again.",
+      "interaction": "Allow once and Always allow are separate answers, never one control with a modifier, and Always allow is drawn only when something can honour it. Denying settles the card rather than hiding it."
     }
   ]
 }

package/manifest/components/autocomplete.json

@@ -222,6 +222,7 @@
     "--cue-focus",
     "--cue-focus-ring",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-hair-strong",
     "--cue-icon-sm",
     "--cue-info",
@@ -275,6 +276,7 @@
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
     "--cue-style-display-variation",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/button.json

@@ -124,9 +124,6 @@
     "--cue-paint-glow-ink-hover",
     "--cue-paint-rest-shade",
     "--cue-paint-shadow-scale",
-    "--cue-paint-stroke-angle",
-    "--cue-paint-stroke-from",
-    "--cue-paint-stroke-to",
     "--cue-radius-control",
     "--cue-space-4",
     "--cue-space-5",

package/manifest/components/card.json

@@ -113,6 +113,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rest-shade",
     "--cue-paint-rim-ink",

package/manifest/components/channel-matrix.json

@@ -198,6 +198,7 @@
     "--cue-focus",
     "--cue-focus-ring",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
     "--cue-paint-scrim-filter",

package/manifest/components/chart-tooltip-content.json

@@ -100,6 +100,7 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
     "--cue-paint-scrim-filter",

package/manifest/components/checkbox-group.json

@@ -43,9 +43,6 @@
     "--cue-icon-sm",
     "--cue-paint-rest-shade",
     "--cue-paint-shadow-scale",
-    "--cue-paint-stroke-angle",
-    "--cue-paint-stroke-from",
-    "--cue-paint-stroke-to",
     "--cue-radius-control",
     "--cue-radius-scale",
     "--cue-space-2",

package/manifest/components/checkbox.json

@@ -68,9 +68,6 @@
     "--cue-icon-sm",
     "--cue-paint-rest-shade",
     "--cue-paint-shadow-scale",
-    "--cue-paint-stroke-angle",
-    "--cue-paint-stroke-from",
-    "--cue-paint-stroke-to",
     "--cue-radius-control",
     "--cue-radius-scale",
     "--cue-space-2",

package/manifest/components/color-field.json

@@ -89,6 +89,7 @@
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/color-picker.json

@@ -223,6 +223,7 @@
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/combobox.json

@@ -224,6 +224,7 @@
     "--cue-focus",
     "--cue-focus-ring",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-hair-strong",
     "--cue-icon-md",
     "--cue-icon-sm",
@@ -278,6 +279,7 @@
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
     "--cue-style-display-variation",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/command-palette.json

@@ -159,6 +159,7 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-icon-md",
     "--cue-icon-sm",
     "--cue-leading-ui",

package/manifest/components/composer-input.json

@@ -7,7 +7,7 @@
     "lucide-react"
   ],
   "clientOnly": true,
-  "description": "The text field. Enter submits, guarded against IME composition so accepting a\ncandidate does not send the message.",
+  "description": "The text field: a textarea that grows with what it holds, to a cap. Enter sends and\nShift+Enter breaks the line, both guarded against IME composition so accepting a\ncandidate does not send the message.",
   "props": [
     {
       "name": "onSubmit",
@@ -19,10 +19,24 @@
         "kind": "callback",
         "fixture": "callback.log"
       }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "`md` (the default) or `sm`: the smaller rung, a 36px floor with body type, for a\ncompact console.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md"
+        ]
+      }
     }
   ],
   "typeReferences": [
-    "Omit<ComponentProps<\"input\">, \"onSubmit\"> & {\n  /**\n   * Called on Enter, guarded against IME composition so accepting a candidate does not\n   * send.\n   */\n  onSubmit?: () => void;\n}"
+    "Omit<ComponentProps<\"textarea\">, \"onSubmit\"> & {\n  /**\n   * Called on Enter, guarded against IME composition so accepting a candidate does not\n   * send.\n   */\n  onSubmit?: () => void;\n  /**\n   * `md` (the default) or `sm`: the smaller rung, a 36px floor with body type, for a\n   * compact console.\n   */\n  size?: \"sm\" | \"md\";\n}"
   ],
   "subcomponents": [],
   "parts": [],

package/manifest/components/composer.json

@@ -225,6 +225,7 @@
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/context-menu.json

@@ -93,6 +93,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
     "--cue-paint-scrim-filter",

package/manifest/components/date-field.json

@@ -80,6 +80,7 @@
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/date-picker.json

@@ -243,6 +243,7 @@
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/date-range-picker.json

@@ -243,6 +243,7 @@
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/dialog.json

@@ -167,6 +167,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
     "--cue-paint-scrim-filter",

package/manifest/components/dmx-bar.json

@@ -65,6 +65,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
     "--cue-paint-scrim-filter",

package/manifest/components/dmx-strip.json

@@ -75,6 +75,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
     "--cue-paint-scrim-filter",

package/manifest/components/drawer.json

@@ -161,6 +161,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-leading-ui",
     "--cue-paint-rim-width",
     "--cue-paint-scrim-filter",

package/manifest/components/dropdown-menu.json

@@ -222,6 +222,7 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
+    "--cue-ground",
     "--cue-icon-sm",
     "--cue-leading-ui",
     "--cue-paint-rim-width",

package/manifest/components/elicitation-form.json

@@ -76,10 +76,25 @@
         "kind": "callback",
         "fixture": "callback.log"
       }
+    },
+    {
+      "name": "delivery",
+      "type": "\"failed\" | \"sending\" | \"sent\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where the answer has got to: `sending`, `sent` or `failed`. While it is on its way\nand once it has arrived, the form offers nothing to press. `failed` offers Decline\nand Send again. An outcome `state` wins over it.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "failed",
+          "sending",
+          "sent"
+        ]
+      }
     }
   ],
   "typeReferences": [
-    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"server\"\n  | \"message\"\n  | \"fields\"\n  | \"state\"\n  | \"onAccept\"\n  | \"onDecline\"\n> & {\n  /** Which server paused to ask. */\n  server: string;\n  /** Why the input is needed, in the server's words. */\n  message: string;\n  /** The schema the server sent, already resolved to display values. */\n  fields: readonly ElicitationField[];\n  /** Swaps the action row for the outcome once the user answers. */\n  state: ElicitationState;\n  /** Called when the filled form is sent back. */\n  onAccept?: () => void;\n  /** Called when the request is refused. */\n  onDecline?: () => void;\n}"
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"server\"\n  | \"message\"\n  | \"fields\"\n  | \"state\"\n  | \"onAccept\"\n  | \"onDecline\"\n  | \"delivery\"\n> & {\n  /** Which server paused to ask. */\n  server: string;\n  /** Why the input is needed, in the server's words. */\n  message: string;\n  /** The schema the server sent, already resolved to display values. */\n  fields: readonly ElicitationField[];\n  /** Swaps the action row for the outcome once the user answers. */\n  state: ElicitationState;\n  /** Called when the filled form is sent back. */\n  onAccept?: () => void;\n  /** Called when the request is refused. */\n  onDecline?: () => void;\n  /**\n   * Where the answer has got to: `sending`, `sent` or `failed`. While it is on its way\n   * and once it has arrived, the form offers nothing to press. `failed` offers Decline\n   * and Send again. An outcome `state` wins over it.\n   */\n  delivery?: RequestDelivery;\n}"
   ],
   "subcomponents": [],
   "parts": [],

package/manifest/components/env-var-input.json

@@ -180,6 +180,7 @@
     "--cue-style-disabled-fill",
     "--cue-style-disabled-ink",
     "--cue-style-disabled-opacity",
+    "--cue-style-field-fill",
     "--cue-style-field-focus-offset",
     "--cue-style-field-hover-edge",
     "--cue-style-field-pad",

package/manifest/components/event-feed.json

@@ -0,0 +1,171 @@
+{
+  "name": "EventFeed",
+  "slug": "event-feed",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A filterable activity feed: timestamped, typed records with a one-line\npreview, and a selection the detail pane follows (#103).\n\nThe chips are built from the kinds present, in the order each first\nappears, each with its count, so a feed never offers a filter that keeps\nnothing. The rows are a listbox: j and k, or the arrows, move the selection\nthrough the rows the filter keeps, and Home and End jump to the ends. The\nselection follows the keyboard, so the detail beside it follows too.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The feed's accessible name: `Run events`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "events",
+      "type": "readonly FeedEvent[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The records, oldest first or newest first: the feed keeps the order given.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.feed"
+      }
+    },
+    {
+      "name": "filter",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The kind the feed keeps, or `all`, when the caller holds it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "defaultFilter",
+      "type": "string",
+      "required": false,
+      "defaultValue": "all",
+      "description": "The kind to start on when nothing controls it. Defaults to `all`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onFilterChange",
+      "type": "((filter: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the kind, or `all`, when a chip is pressed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "selectedId",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": "null",
+      "description": "The selected event's `id`, or `null` for none.",
+      "control": {
+        "kind": "string",
+        "nullable": true
+      }
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with an event's `id` when a row is clicked or the keyboard moves to it.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "formatTime",
+      "type": "((timestamp: string | number | Date) => string)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Formats the time column. Defaults to a time of day for a `Date` or a number.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "labels",
+      "type": "Partial<EventFeedLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace any of the feed's own copy.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-focus-ring",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-stream",
+    "--cue-style-focus-width",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "A filterable activity feed: typed, timestamped records with a one-line preview and a selection.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "const [selected, setSelected] = React.useState<string | null>(null);\n\n<EventFeed\n  label=\"Run events\"\n  events={events}\n  selectedId={selected}\n  onSelect={setSelected}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/event-feed",
+  "mdUrl": "/docs/components/event-feed.md",
+  "jsonUrl": "/r/components/event-feed.json",
+  "whenToUse": [
+    "Inspecting a run beside its transcript: tool calls, permission asks, compactions, errors.",
+    "Any stream of typed records outside agents: MCP logs, device heartbeats, billing events, CI steps."
+  ],
+  "whenNotToUse": [
+    "The conversation itself. Tool calls in the transcript are `ToolGroup`'s; this is the list beside it.",
+    "Raw log lines with ANSI colour. `LogViewer`, from `@cueplusplus/ui/instruments/log-viewer`, reads those."
+  ],
+  "commonMistakes": [
+    "Drawing the detail inside the feed. The feed reports a selection; put the detail in `SplitPane`'s `detail` slot.",
+    "Kinds that are sentences. Each kind becomes a chip, so keep them to a word: `tool`, `permission`, `error`.",
+    "Formatting time strings and also passing `formatTime`. A string timestamp is drawn as given; pass a `Date` or a number to have it formatted."
+  ],
+  "specimens": [
+    {
+      "title": "EventFeed",
+      "group": "elements",
+      "components": [
+        "EventFeed"
+      ],
+      "code": "<div className=\"w-full max-w-md\">\n  <EventFeed\n    label=\"Patch run events\"\n    events={RUN_EVENTS}\n    selectedId={runEvent}\n    onSelect={setRunEvent}\n  />\n</div>",
+      "note": "The inspector beside a transcript: typed records, each a time, a toned dot, a kind, a title and a one-line preview. The chips are built from the kinds present, each with its count, so no chip keeps nothing. The detail is the host's: in a console it goes in SplitPane's detail slot.",
+      "interaction": "press a chip to keep one kind. Tab into the list, then j and k, or the arrows, move the selection through the rows the filter keeps, and Home and End jump to the ends."
+    }
+  ]
+}