@horon-ai/react 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@horon-ai/react",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/horon-ai/design.git",
@@ -30,7 +30,7 @@
 	"dependencies": {
 		"@base-ui/react": "^1.9.0",
 		"@fontsource-variable/geist-mono": "^5.3.0",
-		"@horon-ai/tokens": "0.1.0",
+		"@horon-ai/tokens": "0.1.2",
 		"@phosphor-icons/react": "^2.1.10",
 		"@tanstack/react-table": "^9.3.1",
 		"pretendard": "^1.3.9",

package/src/components/agent-activity.tsx

@@ -1,11 +1,26 @@
 import { CaretDown, CaretRight, CheckCircle, WarningCircle, Wrench } from "@phosphor-icons/react";
 import { type ComponentProps, type ReactNode, useEffect, useRef, useState } from "react";
 
+import { useReducedMotion } from "../hooks/use-reduced-motion";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
-/** Figma `Thinking` (Agent activity 108:660): a 69x31 subtle pill with three 7px dots at 35/55/80% ink. */
-export function ThinkingIndicator({ label = "Thinking", className }: { label?: string; className?: string }) {
+/**
+ * Figma `Thinking` (Agent activity 108:660): a 69x31 subtle pill with three 7px dots at 35/55/80% ink.
+ * Announced as `role="status"`; the three dots bounce with a 150ms stagger.
+ *
+ * @example
+ * ```tsx
+ * <ThinkingIndicator label="Searching the workspace…" />
+ * ```
+ */
+// prettier-ignore
+export function ThinkingIndicator({ label = "Thinking", className }: {
+  /** Accessible status text, not rendered visibly. @default "Thinking" */
+  label?: string;
+  /** Extra classes merged onto the pill, for margins or alignment. */
+  className?: string;
+}) {
   return (
     <span
       role="status"
@@ -37,7 +52,7 @@ function codePointEnd(text: string, end: number): number {
  * bursty chunks read as steady typing; otherwise, and under reduced motion, everything shows at once.
  * Text that no longer extends what was shown (a rewrite) restarts from the shared prefix.
  */
-function useRevealedLength(text: string, smooth: boolean): number {
+function useRevealedLength(text: string, smooth: boolean, reducedMotion: boolean): number {
   const [shown, setShown] = useState(text.length);
   const shownRef = useRef(text.length);
   const previous = useRef(text);
@@ -54,7 +69,7 @@ function useRevealedLength(text: string, smooth: boolean): number {
     while (shared < start && text[shared] === before[shared]) shared++;
     start = shared;
 
-    if (!smooth || window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+    if (!smooth || reducedMotion) {
       set(text.length);
       return undefined;
     }
@@ -73,18 +88,20 @@ function useRevealedLength(text: string, smooth: boolean): number {
       if (length < text.length) frame = requestAnimationFrame(tick);
     });
     return () => cancelAnimationFrame(frame);
-  }, [text, smooth]);
+  }, [text, smooth, reducedMotion]);
 
   return Math.min(shown, text.length);
 }
 
+/** Props for {@link StreamingText}: the growing answer, whether it is still streaming, and whether chunks are revealed smoothly. */
 export type StreamingTextProps = Omit<ComponentProps<"div">, "className" | "children"> & {
   /** Everything received so far; pass the growing string as chunks arrive. */
   text: string;
-  /** True while more text is coming: the caret shows, and the rest is revealed when it turns false. */
+  /** True while more text is coming: the caret shows, and the rest is revealed when it turns false. @default true */
   streaming?: boolean;
-  /** Reveal arriving chunks a few characters per frame instead of in jumps. Off under reduced motion. */
+  /** Reveal arriving chunks a few characters per frame instead of in jumps. Off under reduced motion. @default true */
   smooth?: boolean;
+  /** Extra classes merged onto the bubble, such as a maximum width. */
   className?: string;
 };
 
@@ -93,9 +110,20 @@ export type StreamingTextProps = Omit<ComponentProps<"div">, "className" | "chil
  * right after the last character and wraps with it. The caret holds still while characters land and blinks
  * while waiting for the next chunk; it goes away when the stream ends. Screen readers get the answer once,
  * when it is complete, instead of every chunk.
+ *
+ * `text` is the whole answer so far, not a delta: passing only the newest chunk would drop earlier text. The
+ * reveal restarts from the shared prefix when `text` is rewritten rather than extended.
+ *
+ * @example
+ * ```tsx
+ * function Answer({ text, done }: { text: string; done: boolean }) {
+ *   return <StreamingText text={text} streaming={!done} />;
+ * }
+ * ```
  */
 export function StreamingText({ text, streaming = true, smooth = true, className, ...props }: StreamingTextProps) {
-  const shown = useRevealedLength(text, streaming && smooth);
+  const reducedMotion = useReducedMotion();
+  const shown = useRevealedLength(text, streaming && smooth, reducedMotion);
   const typing = shown < text.length;
   return (
     <div
@@ -122,16 +150,31 @@ export function StreamingText({ text, streaming = true, smooth = true, className
   );
 }
 
+/** Progress of a tool call: `running` shows a spinner, `done` a check, `failed` a warning and danger text. */
 export type ToolStepState = "running" | "done" | "failed";
 
+/** Props for {@link ToolStep}: the tool line, an optional detail line and the progress state. */
 export type ToolStepProps = Omit<ComponentProps<"button">, "className" | "title"> & {
+  /** Progress state, which also picks the leading icon and the title colour. @default "running" */
   state?: ToolStepState;
+  /** The tool call line, truncated to one line. */
   title: ReactNode;
+  /** Optional second line, such as the target or a short result, truncated to one line. */
   detail?: ReactNode;
+  /** Extra classes merged onto the row, for margins. */
   className?: string;
 };
 
-/** Figma `Tool step` (108:660): a flat 12px-radius row with spinner, check or warning, and a caret. */
+/**
+ * Figma `Tool step` (108:660): a flat 12px-radius row with spinner, check or warning, and a caret.
+ * Renders a real `button`, so pass `onClick` to open the call's detail; the caret does not expand anything
+ * on its own.
+ *
+ * @example
+ * ```tsx
+ * <ToolStep state="done" title="Search the web" detail="3 results" onClick={openCall} />
+ * ```
+ */
 export function ToolStep({ state = "running", title, detail, className, ...props }: ToolStepProps) {
   return (
     <button
@@ -156,16 +199,43 @@ export function ToolStep({ state = "running", title, detail, className, ...props
   );
 }
 
-export type WorkLogStep = { id: string; title: ReactNode; detail?: ReactNode; running?: boolean };
+/** One compact line inside a work log. */
+export type WorkLogStep = {
+  /** Stable key for the step. */
+  id: string;
+  /** Step text, truncated to one line. */
+  title: ReactNode;
+  /** Optional second line with a short result or target. */
+  detail?: ReactNode;
+  /** Shows a small spinner instead of the check while the step is still running. */
+  running?: boolean;
+};
 
-/** Figma `Work log` (108:660): a flat subtle card with a wrench summary row and compact steps. */
+/**
+ * Figma `Work log` (108:660): a flat subtle card with a wrench summary row and compact steps. It is a native
+ * `<details open>`, so the summary collapses and expands without extra state; the caret rotates while closed.
+ *
+ * @example
+ * ```tsx
+ * <WorkLog
+ *   summary="4 steps"
+ *   steps={[
+ *     { id: "read", title: "Read the sheet", detail: "18 rows", running: false },
+ *     { id: "write", title: "Draft the summary", running: true },
+ *   ]}
+ * />
+ * ```
+ */
 export function WorkLog({
   summary,
   steps,
   className,
 }: {
+  /** Summary line in the toggle row, such as "4 steps". */
   summary: ReactNode;
+  /** Steps listed under the summary. */
   steps: WorkLogStep[];
+  /** Extra classes merged onto the card, for margins or a width override. */
   className?: string;
 }) {
   return (

package/src/components/agent-lane.tsx

@@ -4,20 +4,36 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/** Lifecycle of the lane: `running` shows a spinner and a pulsing tile, `done` a check, `failed` a warning and a danger rim. */
 export type AgentLaneStatus = "running" | "done" | "failed";
 
+/** Props for {@link AgentLane}: the sub-agent identity, its task, and the optional tool, output, usage and timing lines. */
 export type AgentLaneProps = {
+  /** Lifecycle state; also picks the tile shade (sky-400, sky-600, sky-800) and the result icon. */
   status: AgentLaneStatus;
-  bot: { initial: string; name: ReactNode };
+  /** Identity of the sub-agent shown in the header. */
+  bot: {
+    /** One-character tile label, usually the first letter of the name. */
+    initial: string;
+    /** Display name, truncated when the header runs out of room. */
+    name: ReactNode;
+  };
   /** Duration, such as "1.9s". */
   elapsed?: ReactNode;
+  /** The short task line under the header, wrapping onto several lines. */
   task: ReactNode;
   /** 14px tool icon and source, such as "Notion · Q3 metrics dashboard". */
-  tool?: { icon: ReactNode; label: ReactNode };
+  tool?: {
+    /** Tool icon, sized 14px by the row. */
+    icon: ReactNode;
+    /** Tool and source description, truncated to one line. */
+    label: ReactNode;
+  };
   /** Latest output, or the error when failed. */
   output?: ReactNode;
   /** Usage caption, such as "2.6k tokens". */
   usage?: ReactNode;
+  /** Extra classes merged onto the card, for layout inside a lane grid. */
   className?: string;
 };
 
@@ -27,7 +43,20 @@ const botTile: Record<AgentLaneStatus, string> = {
   failed: "bg-sky-800",
 };
 
-/** Figma `Agent lane` (Agent orchestrator 113:953): one sub-agent's card in a fan-out, flat subtle with a red rim on failure. */
+/**
+ * Figma `Agent lane` (Agent orchestrator 113:953): one sub-agent's card in a fan-out, flat subtle with a red rim on failure.
+ *
+ * @example
+ * ```tsx
+ * <AgentLane
+ *   status="running"
+ *   bot={{ initial: "R", name: "Researcher" }}
+ *   task="Gather the Q3 metrics"
+ *   tool={{ icon: <span aria-hidden>N</span>, label: "Notion · Q3 metrics dashboard" }}
+ *   elapsed="1.9s"
+ * />
+ * ```
+ */
 export function AgentLane({ status, bot, elapsed, task, tool, output, usage, className }: AgentLaneProps) {
   return (
     <div

package/src/components/agent-lanes-timeline.tsx

@@ -4,58 +4,99 @@ import { type ComponentProps, type CSSProperties, type ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/** Bar tone: done is 6% ink, running is 20% live green, failed is 14% red, waiting is an outlined brand bar. */
 export type LaneTaskTone = "done" | "running" | "failed" | "waiting";
 
+/** One bar on a bot's row: its label, time range in minutes before the window end, tone and optional badge. */
 export type LaneTask = {
+  /** Stable key; also how a `LaneHandoff` refers to this task. */
   id: string;
+  /** Text inside the bar, truncated when the bar is too narrow. */
   label: ReactNode;
+  /** 14px icon before the label. */
   icon?: ReactNode;
+  /** Bar fill and text colour. */
   tone: LaneTaskTone;
   /** Minutes before the end of the window, 0 is now: a task from 28 minutes ago to 16 minutes ago is `-28` to `-16`. */
   start: number;
+  /** Minutes before the end of the window where the bar ends; must be greater than `start`. */
   end: number;
   /** A pill inside the bar, such as "Needs you". */
   badge?: ReactNode;
 };
 
+/** Avatar tint of a bot row: `sky` is sky-500, `steel` sky-700, `neutral` neutral-500 and `ink` the brand fill. */
 export type LaneBotTone = "sky" | "steel" | "neutral" | "ink";
 
+/** One lane in the timeline: the bot's identity, its tag and the task bars on its row. */
 export type LaneBot = {
+  /** Stable key for the row; also the lane order. */
   id: string;
+  /** Bot name shown beside the avatar. */
   name: ReactNode;
+  /** Second line under the name, such as the tools the bot uses. */
   tools?: ReactNode;
+  /** One-character avatar label, usually the first letter of the name. */
   initial: string;
+  /** Avatar fill, chosen to keep neighbouring bots distinct. */
   tone: LaneBotTone;
   /** A small tag next to the name: "Idle", "Needs you". */
   badge?: ReactNode;
+  /** Tag fill: `ink` is the brand fill, `subtle` the default 6% ink. @default "subtle" */
   badgeTone?: "subtle" | "ink";
+  /** Bars on this bot's row; tasks from different bots may overlap in time. */
   tasks: LaneTask[];
 };
 
-export type LaneHandoff = { from: string; to: string };
+/** A dashed curve from one task's end to another task's start, such as a hand-off to the next bot. */
+export type LaneHandoff = {
+  /** Task id the curve starts from. */
+  from: string;
+  /** Task id the curve ends at. */
+  to: string;
+};
 
-export type LaneStatus = { id: string; tone: "live" | "ink"; label: ReactNode };
+/** A legend entry in the header: a dot plus a label. */
+export type LaneStatus = {
+  /** Stable key for the entry. */
+  id: string;
+  /** `live` paints the dot green, `ink` paints it with the brand fill. */
+  tone: "live" | "ink";
+  /** Legend text, such as "2 running". */
+  label: ReactNode;
+};
 
+/** The approval strip below the timeline: one question and its two actions. */
 export type AgentLanesTimelineApproval = {
+  /** The approval question in the strip at the bottom. */
   message: ReactNode;
+  /** Fires when "Later" is pressed. */
   onLater?: () => void;
+  /** Fires when "Approve" is pressed. */
   onApprove?: () => void;
 };
 
+/** Props for {@link AgentLanesTimeline}: the lanes, the time window and optional header, hand-offs and approval strip. */
 export type AgentLanesTimelineProps = Omit<ComponentProps<"section">, "className" | "title"> & {
+  /** Panel heading. @default "Bots" */
   title?: ReactNode;
+  /** Legend entries shown next to the heading. @default [] */
   statuses?: LaneStatus[];
-  /** The range pill at the header's right edge. */
+  /** The range pill at the header's right edge. @default "Last 30m" */
   range?: ReactNode;
+  /** One row per bot, in lane order; at least two row heights are always reserved. */
   bots: LaneBot[];
+  /** Hand-off curves drawn over the rows; a hand-off naming an unknown task is skipped. @default [] */
   handoffs?: LaneHandoff[];
-  /** Window length in minutes; the tick labels sit every five. */
+  /** Window length in minutes; the tick labels sit every five. @default 30 */
   windowMinutes?: number;
-  /** Where the current line sits, in minutes before the end of the window. The line glides to a new value in 280ms. */
+  /** Where the current line sits, in minutes before the end of the window. The line glides to a new value in 280ms. @default 0 */
   cursor?: number;
+  /** Adds the approval strip below the timeline. */
   approval?: AgentLanesTimelineApproval;
   /** Makes the range pill actionable; without it the range renders as a plain label. */
   onRangeClick?: () => void;
+  /** Extra classes merged onto the panel, for margins or a width override. */
   className?: string;
 };
 
@@ -75,7 +116,10 @@ const barTone: Record<LaneTaskTone, string> = {
 
 const noStatuses: LaneStatus[] = [];
 const noHandoffs: LaneHandoff[] = [];
-type RowStyle = CSSProperties & { "--i": number };
+type RowStyle = CSSProperties & {
+  /** Lane index, consumed by the staggered `motion-rise` delay. */
+  "--i": number;
+};
 const rowStyle = (lane: number): RowStyle => ({ top: TOP + lane * ROW, height: ROW, "--i": lane });
 
 const ROW = 64;
@@ -91,6 +135,32 @@ const trackW = (fraction: number) => `calc(${TRACK} * ${fraction})`;
  * Paper `Agent lanes` (YCO-1): a 24px-radius surface panel with one lane per bot on a shared time axis, a current
  * line, hand-off curves between bots and an approval strip. The current line glides in 280ms with the emphasized
  * easing, rows tint on hover in 150ms, and running bars carry a spinner.
+ *
+ * The track has a 700px minimum width and scrolls horizontally, so narrow panels stay readable instead of
+ * squeezing the bars. Times are minutes before the window's end, not timestamps.
+ *
+ * @example
+ * ```tsx
+ * <AgentLanesTimeline
+ *   bots={[
+ *     {
+ *       id: "researcher",
+ *       name: "Researcher",
+ *       initial: "R",
+ *       tone: "sky",
+ *       tasks: [{ id: "pull", label: "Pull metrics", tone: "done", start: -28, end: -16 }],
+ *     },
+ *     {
+ *       id: "writer",
+ *       name: "Writer",
+ *       initial: "W",
+ *       tone: "steel",
+ *       tasks: [{ id: "draft", label: "Draft summary", tone: "running", start: -16, end: 0 }],
+ *     },
+ *   ]}
+ *   handoffs={[{ from: "pull", to: "draft" }]}
+ * />
+ * ```
  */
 export function AgentLanesTimeline({
   title = "Bots",
@@ -106,7 +176,15 @@ export function AgentLanesTimeline({
   ...props
 }: AgentLanesTimelineProps) {
   const ticks = Array.from({ length: windowMinutes / 5 - 1 }, (_, i) => -(windowMinutes - 5 * (i + 1)));
-  const taskAt = new Map<string, { task: LaneTask; lane: number }>();
+  const taskAt = new Map<
+    string,
+    {
+      /** The task the hand-off refers to. */
+      task: LaneTask;
+      /** Lane index of the bot that owns the task, used for the curve's vertical endpoints. */
+      lane: number;
+    }
+  >();
   bots.forEach((bot, lane) => {
     for (const task of bot.tasks) taskAt.set(task.id, { task, lane });
   });

package/src/components/agent-panel.tsx

@@ -1,12 +1,28 @@
 import { CaretDown } from "@phosphor-icons/react";
 import type { ComponentProps, ReactNode } from "react";
 
+import { useDevice } from "../hooks/use-device";
+import { usePlatform } from "../hooks/use-platform";
 import { cn } from "../lib/cn";
+import { isModKey } from "../lib/platform";
 import { Kbd } from "./kbd";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** Drops the base type's `className` so the panel can own it. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged onto the root element. */
+  className?: string;
+};
 
-/** The solid panel that hosts the Figma Agents blocks (Agent tasks 112:797): surface fill, 24px radius, 16px padding. */
+/**
+ * The solid panel that hosts the Figma Agents blocks (Agent tasks 112:797): surface fill, 24px radius, 16px padding.
+ *
+ * @example
+ * ```tsx
+ * <AgentPanel filter={<FilterBar items={[{ value: "all", label: "All" }]} />}>
+ *   <TaskComposer onStart={start} pickers={<ComposerChip leading="R">Researcher</ComposerChip>} />
+ * </AgentPanel>
+ * ```
+ */
 export function AgentPanel({
   className,
   filter,
@@ -29,13 +45,18 @@ export function AgentPanel({
   );
 }
 
+/** Props for {@link ComposerChip}: a leading tile letter or icon, its fill, and the usual button props. */
 export type ComposerChipProps = WithClass<ComponentProps<"button">> & {
   /** 16px tile initial (bots) or a 14px icon (projects). */
   leading?: ReactNode;
+  /** Tile fill, defaulting to the brand; pass a sky or neutral shade to match the bot it stands for. */
   tileClassName?: string;
 };
 
-/** A 30px 5% ink picker chip with a 12px caret, used for the bot and project in the task composer. */
+/**
+ * A 30px 5% ink picker chip with a 12px caret, used for the bot and project in the task composer.
+ * Part of {@link TaskComposer}; the chip is a plain button, so it needs its own `onClick` or menu wiring.
+ */
 export function ComposerChip({ leading, tileClassName, className, children, ...props }: ComposerChipProps) {
   return (
     <button
@@ -64,18 +85,42 @@ export function ComposerChip({ leading, tileClassName, className, children, ...p
   );
 }
 
+/** Props for {@link TaskComposer}: the draft text, picker chips, the start handler and the labels. */
 export type TaskComposerProps = {
+  /** Placeholder of the textarea; also its accessible name. @default "Describe a task for a bot" */
   placeholder?: string;
+  /** Controlled draft text; leave undefined and pass `onValueChange` to lift the text, or omit both for a free draft. */
   value?: string;
+  /** Fires on every keystroke with the next text, so the caller can hold the draft. */
   onValueChange?: (value: string) => void;
   /** Picker chips, usually two `ComposerChip`s. */
   pickers?: ReactNode;
+  /** Fires on the Start button and on Mod+Enter; the composer does not clear the draft itself. */
   onStart?: () => void;
+  /** Label of the start button. @default "Start" */
   startLabel?: string;
+  /** Extra classes merged onto the box, for margins or width overrides. */
   className?: string;
 };
 
-/** Figma task `Composer` (Agent tasks 112:797): a 4% ink box, 18px radius, with pickers, ⌘↵ hint and Start. */
+/**
+ * Figma task `Composer` (Agent tasks 112:797): a 4% ink box, 20px radius, with pickers, a key hint and Start.
+ *
+ * The textarea starts at one row and grows with its content up to 160px (`max-h-40`) before it scrolls.
+ * Mod+Enter submits: ⌘Enter on macOS and iOS, Ctrl+Enter on Windows, Linux and Android. The hint is a
+ * `Kbd keys="Mod+Enter"` chip, so it draws the same OS keys, and it is hidden on touch devices that have
+ * no hovering fine pointer.
+ *
+ * @example
+ * ```tsx
+ * <TaskComposer
+ *   value={draft}
+ *   onValueChange={setDraft}
+ *   onStart={start}
+ *   pickers={<ComposerChip leading="R">Researcher</ComposerChip>}
+ * />
+ * ```
+ */
 export function TaskComposer({
   placeholder = "Describe a task for a bot",
   value,
@@ -85,6 +130,8 @@ export function TaskComposer({
   startLabel = "Start",
   className,
 }: TaskComposerProps) {
+  const { os } = usePlatform();
+  const { keyboardHints } = useDevice();
   return (
     <div
       className={cn(
@@ -97,7 +144,7 @@ export function TaskComposer({
         value={value}
         onChange={(event) => onValueChange?.(event.target.value)}
         onKeyDown={(event) => {
-          if (event.key === "Enter" && event.metaKey) onStart?.();
+          if (event.key === "Enter" && isModKey(event, os)) onStart?.();
         }}
         placeholder={placeholder}
         aria-label={placeholder}
@@ -106,8 +153,7 @@ export function TaskComposer({
       <div className="flex flex-wrap items-center gap-1.5">
         {pickers && <span className="flex min-w-0 flex-wrap items-center gap-1.5">{pickers}</span>}
         <span className="min-w-0 flex-1" />
-        <Kbd>⌘</Kbd>
-        <Kbd>↵</Kbd>
+        {keyboardHints && <Kbd keys="Mod+Enter" />}
         <button
           type="button"
           onClick={onStart}