` attribute except `title`, and a ref to it. ## Keyboard - `Tab`: Focuses the card, then Reject, then Approve. - `Enter`: Approves when the card itself is focused. High risk asks for a second press. - `Esc`: Focuses Reject. In the note, closes it and returns to Reject. On an armed high-risk approval, disarms it. - `Enter`: In the note field, sends the rejection with the note. ## Accessibility - The card is a section labelled by its title, so it reads as a named region. - Approve and Reject are real buttons; pending work uses aria-busy, never disabled, so focus stays put. - Status changes (approving, approved, rejected, errors, the high-risk confirm) are announced in a polite live region. - When the card folds, focus moves to the receipt so keyboard users are never dropped to the page. ## Motion - Approving folds the card into a one-line receipt: its height shrinks on the smooth spring while the radius and surface stay one material. - The old face fades out in 120ms through a 2px blur; the receipt's parts arrive in reading order 35ms apart. - The receipt check draws itself and scales in on the snappy spring. No glow, no confetti. - Opening the note grows the card on the morph spring; the Approve label morphs to Approving and to Yes, approve on high risk. - Reduced motion: the fold is instant and the receipt fades in. ## Responsive - Fills its container. When the source and the actions no longer fit on one line, the actions wrap to their own line, right-aligned; the note field does the same. - Uses flex-wrap, not container queries, so it keeps its width inside shrink-to-fit parents. - Long titles wrap; long values break inside their row. ## Performance - One ResizeObserver per card drives the fold; nothing animates on mount. ## Notes for AI - Return a promise from onApprove and onReject: the card shows pending, recovers on a thrown error, and folds when it resolves. - Name the action in labels.approve ("Approve and send"); keep the title one sentence in the agent's words. - Put amounts, counts and IDs in items with numeric: true so they set in tabular figures. - Pass status to control it from your store; leave it out and the card tracks its own decision. - Pass the agent's mark as icon; the component never imports an icon library. ## Related - `hold-to-confirm` (planned) - `agent-plan` (planned) - [Tool call row](https://pixilui.com/components/tool-call-row/markdown): One line per tool call: what it did in plain words, the tool's name, a live timer, and a fold-out with the input and output as copyable JSON. ToolCallRowGroup sums several calls into one line. - [Run timeline](https://pixilui.com/components/run-timeline/markdown): The steps of one agent run as a vertical timeline: a connector that fills as steps finish, a live timer on the active step, and a waiting step that holds an approval. - [Button](https://pixilui.com/components/button/markdown): A button whose label can change without a jump: the width springs to the new words while they swap in place. # Button A button whose label can change without a jump: the width springs to the new words while they swap in place. Tier: free. Type: component. Category: actions. Tags: motion, keyboard. ## Install ```bash npx shadcn@latest add @pixilui/button ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/button.tsx`. npm: `motion`. ## Preview Live preview: https://pixilui.com/components/button Knobs: - `variant`: `primary`, `secondary`, `ghost`, `danger` - `size`: `md`, `sm`, `lg` - `loading`: `false`, `true` Signature: The label changes and the button grows into the new words on a spring, never a jump. ## Code `components/pixilui/button.tsx` ```tsx "use client"; import { forwardRef, useCallback, useRef, type ComponentPropsWithoutRef, type KeyboardEvent, type MouseEvent, type PointerEvent, type ReactNode, } from "react"; import { AnimatePresence, animate, motion, useReducedMotion } from "motion/react"; import { cn } from "./lib/utils"; import { useMorphSize } from "./lib/use-morph-size"; import { motionTokens, reducedTransition } from "./motion-tokens"; type ButtonOwnProps = { /** Visual weight. Keep one primary per surface. */ variant?: "primary" | "secondary" | "ghost" | "danger"; /** Control height: sm is 36px, md 44px, lg 50px. */ size?: "sm" | "md" | "lg"; /** Shows a spinner, sets aria-busy and aria-disabled, and ignores presses. Focus stays on the button. */ loading?: boolean; /** Leading icon. The spinner takes its place while loading. */ icon?: ReactNode; /** Trailing icon, after the label. */ iconEnd?: ReactNode; }; type ButtonLabelProps = | { /** The label. When it changes, the button morphs to the new width and the words swap. */ children: ReactNode; } | { children?: undefined; /** Icon-only buttons need an accessible name. */ "aria-label": string; icon: ReactNode; }; export type ButtonProps = Omit, "children"> & ButtonOwnProps & ButtonLabelProps; const variants = { primary: "bg-accent-solid text-accent-contrast shadow-control inset-shadow-highlight hover-fine:bg-accent-solid/90", secondary: "bg-surface text-foreground shadow-control hairline hairline-strong hover-fine:bg-surface-muted", ghost: "bg-transparent text-foreground hover-fine:bg-surface-muted", danger: "bg-danger text-danger-foreground shadow-resting hover-fine:bg-danger/90", } as const; const sizes = { sm: "h-control-sm px-3.5 text-14", md: "h-control-md px-4 text-14", lg: "h-control-lg px-5 text-16", } as const; const gaps = { sm: "gap-1.5", md: "gap-2", lg: "gap-2" } as const; const iconOnlySizes = { sm: "w-control-sm px-0", md: "w-control-md px-0", lg: "w-control-lg px-0", } as const; function labelKeyOf(children: ReactNode) { return typeof children === "string" || typeof children === "number" ? String(children) : "node"; } /** A ring that turns while work is in flight. Still under reduced motion. */ function ButtonSpinner() { return ( ); } export const Button = forwardRef(function Button( { variant = "primary", size = "md", loading = false, icon, iconEnd, children, type = "button", disabled, className, onClick, onPointerDown, onPointerUp, onPointerLeave, onPointerCancel, onKeyDown, onKeyUp, "aria-disabled": ariaDisabledProp, ...rest }, forwardedRef, ) { const reduced = useReducedMotion(); const buttonRef = useRef(null); const labelKey = labelKeyOf(children); const { containerRef, measureRef } = useMorphSize("width", labelKey); const ariaDisabled = ariaDisabledProp === true || ariaDisabledProp === "true"; const inert = loading || ariaDisabled || Boolean(disabled); const iconOnly = children === undefined || children === null; const setRef = useCallback( (node: HTMLButtonElement | null) => { buttonRef.current = node; if (typeof forwardedRef === "function") forwardedRef(node); else if (forwardedRef) forwardedRef.current = node; }, [forwardedRef], ); const press = (down: boolean) => { const el = buttonRef.current; if (!el || reduced || (down && inert)) return; animate(el, { scale: down ? motionTokens.scale.press : 1 }, motionTokens.spring.snappy); }; const swap = reduced ? reducedTransition : { duration: motionTokens.duration.quick, ease: motionTokens.ease.swap }; const blur = `blur(${motionTokens.blur.subtle}px)`; return ( ); }); ``` ## Usage When to use: - Any action someone triggers: submit, send, deploy, approve. - Actions whose label follows the work (Send, Sending, Sent) so the button tells the story without a toast. When not to use: - Navigation to another page: use a link styled as you need. - A destructive action on its own: pair the danger variant with a confirm step or hold-to-confirm. ```tsx import { useState } from "react"; import { Check, Ellipsis, Eye, Send } from "lucide-react"; import { Button } from "@/components/pixilui/button"; export const knobs = { variant: ["primary", "secondary", "ghost", "danger"], size: ["md", "sm", "lg"], loading: [false, true], } as const; type Phase = "idle" | "sending" | "sent"; const labels: Record = { idle: "Send invoice", sending: "Sending to Northwind Freight", sent: "Sent", }; export default function ButtonDemo({ variant = "primary", size = "md", loading = false }: KnobValues) { const [phase, setPhase] = useState("idle"); const send = () => { if (phase !== "idle") { setPhase("idle"); return; } setPhase("sending"); setTimeout(() => setPhase("sent"), 1600); }; return (

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `aria-label` | `string` | | Icon-only buttons need an accessible name. | | `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"primary"` | Visual weight. Keep one primary per surface. | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control height: sm is 36px, md 44px, lg 50px. | | `loading` | `boolean` | `false` | Shows a spinner, sets aria-busy and aria-disabled, and ignores presses. Focus stays on the button. | | `icon` | `ReactNode` | | Leading icon. The spinner takes its place while loading. | | `iconEnd` | `ReactNode` | | Trailing icon, after the label. | | `children` | `ReactNode \| undefined` | | The label. When it changes, the button morphs to the new width and the words swap. | Also accepts every native ` ) : null} ); }); ``` ## Usage When to use: - A decision has to be made before the person goes on: connect a tool, delete an agent, discard a run. - A short task that needs focus and fits on one screen: rename, invite, set a budget. When not to use: - Details the person reads while working on the page: use a drawer. - A few options anchored to a control: use a popover. - An agent asking a human to sign off inside a run: use approval-card, which stays in the timeline. ```tsx import { useState } from "react"; import { Plug, Trash2 } from "lucide-react"; import { Button } from "@/components/pixilui/button"; import { Dialog, DialogActions, DialogDescription, DialogTitle } from "@/components/pixilui/dialog"; // The first option of each knob is the demo's default; the docs preview starts there. export const knobs = { variant: ["default", "danger"], size: ["md", "sm", "lg"], state: ["open", "closed"], } as const; const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); const scopes = [ { label: "Reads", value: "Issues and comments in Support, Platform" }, { label: "Writes", value: "Draft replies, labels" }, { label: "Never", value: "Closes or deletes an issue" }, ]; export default function DialogDemo({ variant = "default", size = "md", state = "open" }: KnobValues) { // The dialog portals into this stage, so it keeps the preview's theme and accent and stays inside it. // It waits while the stage is null, so pass the element itself (a ref object would resolve too late). const [stage, setStage] = useState(null); const danger = variant === "danger"; return (

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | | The dialog's parts: DialogTitle, DialogDescription, your content, DialogActions. | | `open` | `boolean` | | Controlled open state. Pair with onOpenChange. | | `defaultOpen` | `boolean` | `false` | Starting open state when uncontrolled. | | `onOpenChange` | `(open: boolean) => void` | | Runs whenever the dialog opens or closes, from the trigger, Esc, an outside press or an action. | | `trigger` | `ReactElement` | | The element that opens the dialog, usually a Button. It is rendered through Base UI's render prop, so any element works and keeps its own props. | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Panel width: sm is 384px, md 448px, lg 576px. It never exceeds the viewport. | | `variant` | `"default" \| "danger"` | `"default"` | danger tints the icon tile, styles the confirm action with the danger tokens, places it second and focuses Cancel first. | | `dismissible` | `boolean` | `true` | Close on Esc and on a press outside the panel. Turn off for a decision that must be made. | | `icon` | `ReactNode` | | A mark shown in a tile above the title. Components never bake in an icon. | | `container` | `DialogContainer` | | Where the dialog portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. | | `modal` | `boolean \| "trap-focus"` | | true traps focus, locks page scroll and blocks the page; "trap-focus" only traps focus. Defaults to true, or "trap-focus" when a container is set. | Also accepts every native `

` attribute except `role`, and a ref to it. ## Keyboard - `Enter`: On the trigger, opens the dialog and moves focus inside it. - `Tab`: Moves between the controls in the dialog; focus never leaves it while it is open. - `Esc`: Closes the dialog and returns focus to the trigger, unless dismissible is false or an action is pending. ## Accessibility - Base UI renders role dialog with aria-modal and wires DialogTitle and DialogDescription to aria-labelledby and aria-describedby. - The danger variant renders role alertdialog and puts focus on Cancel first, so a stray Enter never deletes anything. - Focus is trapped while open and returns to the trigger on close; page scroll is locked for a full-page dialog. - The confirm action shows pending with aria-busy and aria-disabled, never disabled, so focus stays on it; errors are announced in a polite live region. ## Motion - The panel opens on the morph spring from scale 0.96 while a 2px blur clears, and closes faster on the exit ease in 150ms. - The backdrop fades in on duration-fast. - Reduced motion: both fade only, with no scale or blur. ## Responsive - The panel fills the width up to its size (384, 448 or 576px) with 16px of margin, and never exceeds the viewport height. - Long content scrolls inside the panel while the actions stay pinned to the bottom. - Below 640px the actions stack full width with the main action on top. ## Performance - Nothing is mounted while closed; the panel and backdrop mount on open and unmount after the exit animation. ## Notes for AI - Pass the opener as trigger (any element; a Button is usual). For a dialog opened from code, leave trigger out and control open and onOpenChange. - Compose the parts: DialogTitle, DialogDescription, your content, then DialogActions with confirm and onConfirm. - Return a promise from onConfirm: the button shows pending, Esc and outside presses wait, and the dialog closes when it resolves or shows an error when it throws. - Name the action in confirm ("Delete agent", "Connect Linear"), never "OK" or "Continue". - Use variant danger for anything destructive; it styles the action with the danger tokens, puts it second and focuses Cancel. - Pass container to keep the dialog inside a region of the page; it then traps focus without locking page scroll. ## Related - [Drawer](https://pixilui.com/components/drawer/markdown): A sheet that slides in from the right, left or bottom for details read alongside the page: a run, a trace, a record, a settings panel. - [Popover](https://pixilui.com/components/popover/markdown): A small panel anchored to a control for a closer look or a quick change: a run's budget, a model's settings, who can see a thread. - [Approval card](https://pixilui.com/components/approval-card/markdown): An agent asks before it acts: what it will do, the rows that matter, the risk, and approve or reject with a note. - [Button](https://pixilui.com/components/button/markdown): A button whose label can change without a jump: the width springs to the new words while they swap in place. # Drawer A sheet that slides in from the right, left or bottom for details read alongside the page: a run, a trace, a record, a settings panel. Tier: free. Type: component. Category: overlays. Tags: keyboard, motion, run. ## Install ```bash npx shadcn@latest add @pixilui/drawer ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/drawer.tsx`. npm: `@base-ui/react`, `motion`. ## Preview Live preview: https://pixilui.com/components/drawer Knobs: - `side`: `right`, `bottom`, `left` - `size`: `md`, `sm`, `lg` - `state`: `open`, `closed` Signature: On a phone, flick the handle and the sheet leaves at the speed you threw it, on a spring that never bounces back. ## Code `components/pixilui/drawer.tsx` ```tsx "use client"; import { forwardRef, isValidElement, useCallback, useId, useMemo, useRef, useState, useSyncExternalStore, type ComponentPropsWithoutRef, type ReactElement, type ReactNode, } from "react"; import { Dialog as BaseDialog } from "@base-ui/react/dialog"; import { AnimatePresence, motion, useDragControls, useReducedMotion, type PanInfo } from "motion/react"; import { cn } from "./lib/utils"; import { motionTokens, reducedTransition } from "./motion-tokens"; import { DialogActions, DialogClose, DialogDescription, DialogProvider, DialogTitle, dialogTriggerIsNativeButton, type DialogContainer, } from "./dialog"; export type DrawerSide = "right" | "left" | "bottom"; export type DrawerSize = "sm" | "md" | "lg"; export type DrawerProps = Omit, "children" | "role"> & { /** The drawer's parts: DrawerTitle, DrawerDescription, your content, DrawerActions. */ children?: ReactNode; /** Controlled open state. Pair with onOpenChange. */ open?: boolean; /** Starting open state when uncontrolled. */ defaultOpen?: boolean; /** Runs whenever the drawer opens or closes, from the trigger, Esc, an outside press, a swipe or an action. */ onOpenChange?: (open: boolean) => void; /** The element that opens the drawer, usually a Button. Rendered through Base UI's render prop, so any element works. */ trigger?: ReactElement; /** The edge the sheet slides from. */ side?: DrawerSide; /** Width for left and right (320, 384 or 512px); maximum height for bottom (40, 65 or 90% of the screen). */ size?: DrawerSize; /** Close on Esc, an outside press and, for bottom drawers on touch screens, a swipe down. */ dismissible?: boolean; /** Where the drawer portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. */ container?: DialogContainer; /** true traps focus, locks page scroll and blocks the page; "trap-focus" only traps focus. Defaults to true, or "trap-focus" when a container is set. */ modal?: boolean | "trap-focus"; }; const panelSides: Record = { right: "inset-y-2 right-2 w-[calc(100%-1rem)]", left: "inset-y-2 left-2 w-[calc(100%-1rem)]", bottom: "inset-x-2 bottom-2 mx-auto max-w-2xl", }; const panelSizes: Record> = { right: { sm: "max-w-xs", md: "max-w-sm", lg: "max-w-lg" }, left: { sm: "max-w-xs", md: "max-w-sm", lg: "max-w-lg" }, bottom: { sm: "max-h-[40%]", md: "max-h-[65%]", lg: "max-h-[90%]" }, }; /** How far off screen the sheet waits: past its own size plus the 8px inset. */ const offscreen: Record = { right: { x: "110%" }, left: { x: "-110%" }, bottom: { y: "110%" }, }; /** A swipe closes the sheet past this share of its height, or faster than this many px/s. */ const SWIPE_DISTANCE = 0.3; const SWIPE_VELOCITY = 600; /** Upward pull resistance: the sheet gives about 10px before it stops. */ const PULL_ELASTIC = 0.04; const coarseQuery = "(pointer: coarse)"; const subscribeCoarse = (onChange: () => void) => { const list = window.matchMedia(coarseQuery); list.addEventListener("change", onChange); return () => list.removeEventListener("change", onChange); }; const readCoarse = () => window.matchMedia(coarseQuery).matches; const readCoarseOnServer = () => false; function usePointerCoarse() { return useSyncExternalStore(subscribeCoarse, readCoarse, readCoarseOnServer); } export const Drawer = forwardRef(function Drawer( { children, open: openProp, defaultOpen = false, onOpenChange, trigger, side = "right", size = "md", dismissible = true, container, modal, className, ...rest }, forwardedRef, ) { const reduced = useReducedMotion() ?? false; const coarse = usePointerCoarse(); const dragControls = useDragControls(); const [innerOpen, setInnerOpen] = useState(defaultOpen); const open = openProp ?? innerOpen; const generatedTriggerId = useId(); const triggerId = (isValidElement<{ id?: string }>(trigger) && trigger.props.id) || generatedTriggerId; const cancelRef = useRef(null); const pendingRef = useRef(false); const panelRef = useRef(null); const swipeable = side === "bottom" && coarse && dismissible; const setOpen = useCallback( (next: boolean) => { setInnerOpen(next); onOpenChange?.(next); }, [onOpenChange], ); const context = useMemo( () => ({ variant: "default" as const, close: () => setOpen(false), cancelRef, setPending: (pending: boolean) => { pendingRef.current = pending; }, }), [setOpen], ); const setPanelRef = useCallback( (node: HTMLDivElement | null) => { panelRef.current = node; if (typeof forwardedRef === "function") forwardedRef(node); else if (forwardedRef) forwardedRef.current = node; }, [forwardedRef], ); const onDragEnd = (event: PointerEvent | MouseEvent | TouchEvent, info: PanInfo) => { const height = (event.target as HTMLElement | null)?.closest('[data-slot="drawer"]')?.getBoundingClientRect().height ?? 0; if (info.offset.y > height * SWIPE_DISTANCE || info.velocity.y > SWIPE_VELOCITY) setOpen(false); }; const backdrop = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: reducedTransition } : { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0, transition: { duration: motionTokens.duration.medium, ease: motionTokens.ease.smoothOut } }, transition: { duration: motionTokens.duration.fast, ease: motionTokens.ease.smoothOut }, }; const panel = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: reducedTransition } : { initial: { opacity: 0, ...offscreen[side] }, animate: { opacity: 1, x: 0, y: 0 }, // The exit is a spring too, so a flick carries its velocity off screen. exit: { opacity: 0, ...offscreen[side], transition: { default: motionTokens.spring.smooth, opacity: { duration: motionTokens.duration.medium, ease: motionTokens.ease.exit } }, }, transition: { default: motionTokens.spring.smooth, opacity: { duration: motionTokens.duration.fast, ease: motionTokens.ease.enter } }, }; const state = open ? "open" : "closed"; return ( { if (!next && (pendingRef.current || (!dismissible && details.reason === "escape-key"))) { details.cancel(); return; } setOpen(next); }} > {trigger ? : null} {open ? ( } /> } {...rest} > {side === "bottom" && coarse ? ( ) : null}

{children}

) : null} ); }); /** The drawer's name, wired to aria-labelledby. Same part as DialogTitle. */ export const DrawerTitle = DialogTitle; /** Supporting sentence, wired to aria-describedby. Same part as DialogDescription. */ export const DrawerDescription = DialogDescription; /** The button row, pinned to the bottom while content scrolls. Same part as DialogActions. */ export const DrawerActions = DialogActions; /** A Button that closes the drawer. Same part as DialogClose. */ export const DrawerClose = DialogClose; ``` ## Usage When to use: - Details of one row the person opens and closes while scanning a list: a run, a tool call, a customer. - A form too long for a dialog that still belongs to the current page: agent settings, a schedule. - On phones, actions and filters from the bottom edge where a thumb reaches them. When not to use: - A single decision: use a dialog. - A few options anchored to a control: use a popover. - Navigation that stays open: use a sidebar in the layout, not an overlay. ```tsx import { useState } from "react"; import { Button } from "@/components/pixilui/button"; import { Drawer, DrawerActions, DrawerDescription, DrawerTitle } from "@/components/pixilui/drawer"; // The first option of each knob is the demo's default; the docs preview starts there. export const knobs = { side: ["right", "bottom", "left"], size: ["md", "sm", "lg"], state: ["open", "closed"], } as const; const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); const steps = [ { time: "09:41:02", text: "Read 48 open invoices from Stripe" }, { time: "09:41:09", text: "Matched 46 to customers in HubSpot" }, { time: "09:41:15", text: "Drafted reminders in the Q3 renewal template" }, { time: "09:42:30", text: "Sent 46 reminders from billing@northwind.co" }, { time: "09:42:31", text: "Skipped Arden Labs: no billing contact" }, { time: "09:42:31", text: "Skipped Kova Health: invoice disputed" }, { time: "09:42:40", text: "Logged the run to #billing-ops in Slack" }, ]; export default function DrawerDemo({ side = "right", size = "md", state = "open" }: KnobValues) { // The drawer portals into this stage, so it keeps the preview's theme and accent and stays inside it. const [stage, setStage] = useState(null); return (

Open run 4821} > Run 4821, Billing agent Finished 2 minutes ago. 46 of 48 reminders sent.

{step.time} {step.text}

wait(900)} labels={{ cancel: "Close" }} />

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | | The drawer's parts: DrawerTitle, DrawerDescription, your content, DrawerActions. | | `open` | `boolean` | | Controlled open state. Pair with onOpenChange. | | `defaultOpen` | `boolean` | `false` | Starting open state when uncontrolled. | | `onOpenChange` | `(open: boolean) => void` | | Runs whenever the drawer opens or closes, from the trigger, Esc, an outside press, a swipe or an action. | | `trigger` | `ReactElement` | | The element that opens the drawer, usually a Button. Rendered through Base UI's render prop, so any element works. | | `side` | `"right" \| "left" \| "bottom"` | `"right"` | The edge the sheet slides from. | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Width for left and right (320, 384 or 512px); maximum height for bottom (40, 65 or 90% of the screen). | | `dismissible` | `boolean` | `true` | Close on Esc, an outside press and, for bottom drawers on touch screens, a swipe down. | | `container` | `DialogContainer` | | Where the drawer portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. | | `modal` | `boolean \| "trap-focus"` | | true traps focus, locks page scroll and blocks the page; "trap-focus" only traps focus. Defaults to true, or "trap-focus" when a container is set. | Also accepts every native `

` attribute except `role`, and a ref to it. ## Keyboard - `Enter`: On the trigger, opens the drawer and focuses the sheet, so reading starts at its title. - `Tab`: Moves between the controls in the drawer; focus stays inside while it is open. - `Esc`: Closes the drawer and returns focus to the trigger, unless dismissible is false or an action is pending. ## Accessibility - Built on Base UI Dialog: role dialog, aria-modal, and the title and description wired to aria-labelledby and aria-describedby. - The sheet itself takes focus on open, so a screen reader starts at the title instead of the footer button; Tab then moves through its controls. - Focus is trapped while open and returns to the trigger on close; page scroll is locked for a full-page drawer. - The drag handle is decorative (aria-hidden); keyboard and screen reader users close with Esc or the Close action. - Swipe to dismiss only exists on coarse pointers, so a mouse never drags the sheet by accident. ## Motion - The sheet slides in on the smooth spring, which never overshoots, and fades in on duration-fast. - Closing uses the smooth spring too, so a flick down on the handle carries its velocity off screen. - Pulling a bottom sheet up rubber-bands about 10px; letting go short of a third of its height springs it back. - Reduced motion: the sheet and backdrop fade only, and dragging is off. ## Responsive - Side sheets take the full width minus 16px on phones and cap at 320, 384 or 512px. - Bottom sheets center at up to 672px wide and cap their height at 40, 65 or 90% of the screen. - Content scrolls inside the sheet; DrawerActions stay pinned to its bottom. - Bottom sheets show a drag handle on touch screens only. ## Performance - Nothing is mounted while closed. Dragging runs on a motion value, outside React renders. ## Notes for AI - Same API as dialog: trigger, open, defaultOpen, onOpenChange, dismissible, container. - Compose DrawerTitle, DrawerDescription, your content and DrawerActions; they are the dialog parts under drawer names. - Use side bottom for mobile action sheets and side right for detail panels on desktop. - Return a promise from DrawerActions onConfirm to get pending and error handling for free. ## Related - [Dialog](https://pixilui.com/components/dialog/markdown): A modal panel for one decision or one short task: a title, what happens, and the buttons that do it, with pending and error handled. - [Popover](https://pixilui.com/components/popover/markdown): A small panel anchored to a control for a closer look or a quick change: a run's budget, a model's settings, who can see a thread. - [Button](https://pixilui.com/components/button/markdown): A button whose label can change without a jump: the width springs to the new words while they swap in place. # Input A text field with its label, help, error, prefix and suffix slots and a clear button, wired for screen readers. Tier: free. Type: component. Category: inputs. Tags: form, keyboard. ## Install ```bash npx shadcn@latest add @pixilui/input ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/input.tsx`. npm: `motion`. ## Preview Live preview: https://pixilui.com/components/input Knobs: - `size`: `md`, `sm`, `lg` - `state`: `default`, `error`, `disabled` Signature: Esc clears the field and hands focus straight back, and an error rises into place instead of popping. ## Code `components/pixilui/input.tsx` ```tsx "use client"; import { forwardRef, useCallback, useId, useRef, useState, type ChangeEvent, type ComponentPropsWithoutRef, type KeyboardEvent, type ReactNode, } from "react"; import { AnimatePresence, motion, useReducedMotion } from "motion/react"; import { cn } from "./lib/utils"; import { motionTokens, reducedTransition } from "./motion-tokens"; export type InputProps = Omit, "size" | "prefix"> & { /** Visible label. Use aria-label instead only when the surrounding UI already names the field. */ label?: ReactNode; /** Help under the field, linked with aria-describedby. */ description?: ReactNode; /** Error message. Marks the field invalid, replaces nothing, and is announced politely. */ error?: ReactNode; /** Content before the value: an icon, a currency sign, a URL scheme. */ prefix?: ReactNode; /** Content after the value: a unit, a shortcut hint, a status. */ suffix?: ReactNode; /** Control height: sm is 36px, md 44px, lg 50px. */ size?: "sm" | "md" | "lg"; /** Shows a clear button while there is a value. Esc clears too. */ clearable?: boolean; /** Runs after the clear button or Esc empties the field. onChange also fires with an empty value. */ onClear?: () => void; /** Accessible name of the clear button. */ clearLabel?: string; /** Icon for the clear button. Defaults to a drawn cross. */ clearIcon?: ReactNode; /** Classes for the outer wrapper (label, field and messages). Native attributes and the ref go to the input. */ className?: string; }; const fieldSizes = { sm: "h-control-sm gap-2 px-3 text-14", md: "h-control-md gap-2 px-3.5 text-16 sm:text-14", lg: "h-control-lg gap-2.5 px-4 text-16", } as const; function InputClearMark() { return ( ); } export const Input = forwardRef(function Input( { label, description, error, prefix, suffix, size = "md", clearable = false, onClear, clearLabel = "Clear", clearIcon, className, id, value, defaultValue, onChange, onKeyDown, disabled, readOnly, "aria-describedby": describedBy, "aria-invalid": ariaInvalid, ...rest }, forwardedRef, ) { const reduced = useReducedMotion(); const autoId = useId(); const inputId = id ?? `${autoId}-input`; const descriptionId = `${autoId}-description`; const errorId = `${autoId}-error`; const inputRef = useRef(null); const [innerValue, setInnerValue] = useState(() => String(defaultValue ?? "")); const controlled = value !== undefined; const hasValue = String(controlled ? (value ?? "") : innerValue).length > 0; const invalid = Boolean(error) || ariaInvalid === true || ariaInvalid === "true"; const showClear = clearable && hasValue && !disabled && !readOnly; const setRef = useCallback( (node: HTMLInputElement | null) => { inputRef.current = node; if (typeof forwardedRef === "function") forwardedRef(node); else if (forwardedRef) forwardedRef.current = node; }, [forwardedRef], ); const clear = () => { const el = inputRef.current; if (!el) return; // Set the value the way typing does, so React's onChange fires for controlled fields too. Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set?.call(el, ""); el.dispatchEvent(new Event("input", { bubbles: true })); el.focus(); onClear?.(); }; const describedByIds = [describedBy, description ? descriptionId : undefined, error ? errorId : undefined].filter(Boolean).join(" ") || undefined; const enter = reduced ? reducedTransition : { duration: motionTokens.duration.fast, ease: motionTokens.ease.enter }; return (

{label ? ( {label} ) : null}

{ // Clicking the padding or a prefix focuses the input, like a native field. if (event.target === event.currentTarget || !(event.target as HTMLElement).closest("button,input")) { event.preventDefault(); inputRef.current?.focus(); } }} > {prefix ? {prefix} : null} ) => { if (!controlled) setInnerValue(event.target.value); onChange?.(event); }} onKeyDown={(event: KeyboardEvent) => { if (event.key === "Escape" && showClear) { event.preventDefault(); event.stopPropagation(); clear(); } onKeyDown?.(event); }} {...rest} /> {showClear ? ( {clearIcon ?? } ) : null} {suffix ? {suffix} : null}

{description ? (

{description}

) : null}

{error ? ( {error} ) : null}

); }); ``` ## Usage When to use: - Single-line text: names, URLs, amounts, API keys, search inside a panel. - Fields that need a unit or scheme beside the value (USD, https://, a shortcut hint). When not to use: - Several lines of text: use textarea. - Numbers someone nudges up and down: use number-field. - Picking from a known list: use select or combobox. ```tsx import { useState } from "react"; import { Link2 } from "lucide-react"; import { Input } from "@/components/pixilui/input"; export const knobs = { size: ["md", "sm", "lg"], state: ["default", "error", "disabled"], } as const; export default function InputDemo({ size = "md", state = "default" }: KnobValues) { const [url, setUrl] = useState("hooks.northwind.co/agent-runs"); const [limit, setLimit] = useState("2,400"); return (

} suffix={POST} description="Called once for every finished run." error={state === "error" ? "That URL returned 404. Check the path." : undefined} disabled={state === "disabled"} clearable value={url} onChange={(event) => setUrl(event.target.value)} type="url" inputMode="url" spellCheck={false} /> setLimit(event.target.value)} />

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `className` | `string` | | Classes for the outer wrapper (label, field and messages). Native attributes and the ref go to the input. | | `label` | `ReactNode` | | Visible label. Use aria-label instead only when the surrounding UI already names the field. | | `description` | `ReactNode` | | Help under the field, linked with aria-describedby. | | `error` | `ReactNode` | | Error message. Marks the field invalid, replaces nothing, and is announced politely. | | `prefix` | `ReactNode` | | Content before the value: an icon, a currency sign, a URL scheme. | | `suffix` | `ReactNode` | | Content after the value: a unit, a shortcut hint, a status. | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control height: sm is 36px, md 44px, lg 50px. | | `clearable` | `boolean` | `false` | Shows a clear button while there is a value. Esc clears too. | | `onClear` | `() => void` | | Runs after the clear button or Esc empties the field. onChange also fires with an empty value. | | `clearLabel` | `string` | `"Clear"` | Accessible name of the clear button. | | `clearIcon` | `ReactNode` | | Icon for the clear button. Defaults to a drawn cross. | Also accepts every native `` attribute except `size`, `prefix`, and a ref to it. ## Keyboard - `Tab`: Moves focus into the field; the clear button stays out of the tab order. - `Esc`: Clears the value when the field is clearable and has a value; otherwise Esc passes through to the dialog or card around it. ## Accessibility - The label is a real label element tied to the input with htmlFor. - Description and error are linked with aria-describedby; an error sets aria-invalid. - Errors appear inside a polite live region, so they are announced when they arrive. - The clear button has an accessible name (clearLabel) and returns focus to the input. ## Motion - The error rises 4px out of a 4px blur on the enter ease in 250ms. - The clear button fades and settles from 0.96 on the swap ease; it leaves in 120ms. - Reduced motion: both only fade. ## Responsive - Fills its container's width. - The md size uses 16px text on small screens so iOS does not zoom on focus. ## Performance - Uncontrolled by default; pass value and onChange to control it. ## Notes for AI - Native attributes (name, type, required, autoComplete) and the ref go to the input element; className goes to the wrapper. - Pass error as a string after validation; do not also change the label colour. - Use prefix and suffix for scheme, currency and units instead of putting them in the placeholder. ## Related - `textarea` (planned) - `number-field` (planned) - `search-field` (planned) - `tag-input` (planned) # Popover A small panel anchored to a control for a closer look or a quick change: a run's budget, a model's settings, who can see a thread. Tier: free. Type: component. Category: overlays. Tags: keyboard, motion. ## Install ```bash npx shadcn@latest add @pixilui/popover ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/popover.tsx`. npm: `@base-ui/react`, `motion`. ## Preview Live preview: https://pixilui.com/components/popover Knobs: - `side`: `bottom`, `top`, `right`, `left` - `align`: `center`, `start`, `end` - `arrow`: `off`, `on` - `state`: `open`, `closed` Signature: The panel grows out of the exact corner of its trigger on a snappy spring, wherever Base UI places it. ## Code `components/pixilui/popover.tsx` ```tsx "use client"; import { forwardRef, isValidElement, useCallback, useId, useState, type ComponentPropsWithoutRef, type ReactElement, type ReactNode, } from "react"; import { Popover as BasePopover } from "@base-ui/react/popover"; import { AnimatePresence, motion, useReducedMotion } from "motion/react"; import { cn } from "./lib/utils"; import { motionTokens, reducedTransition } from "./motion-tokens"; import { Button, type ButtonProps } from "./button"; export type PopoverSide = "top" | "bottom" | "left" | "right"; export type PopoverAlign = "start" | "center" | "end"; export type PopoverProps = Omit, "children"> & { /** What the panel holds: PopoverTitle, PopoverDescription, controls, PopoverClose. */ children?: ReactNode; /** The element the panel anchors to and opens from, usually a Button. Rendered through Base UI's render prop. */ trigger: ReactElement; /** Controlled open state. Pair with onOpenChange. */ open?: boolean; /** Starting open state when uncontrolled. */ defaultOpen?: boolean; /** Runs whenever the popover opens or closes. */ onOpenChange?: (open: boolean) => void; /** Preferred side of the trigger. It flips when there is no room. */ side?: PopoverSide; /** Alignment along that side. */ align?: PopoverAlign; /** Gap between the trigger and the panel, in px. */ offset?: number; /** Draw a small arrow pointing at the trigger. */ arrow?: boolean; /** Also open when the trigger is hovered (fine pointers only). Clicks still toggle it. */ hoverOpen?: boolean; /** Where the popover portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. */ container?: HTMLElement | null; }; /** Keeps the arrow clear of the panel's rounded corners. */ const ARROW_PADDING = 22; function PopoverArrow() { return ( ); } export const Popover = forwardRef(function Popover( { children, trigger, open: openProp, defaultOpen = false, onOpenChange, side = "bottom", align = "center", offset = 8, arrow = false, hoverOpen = false, container, className, ...rest }, forwardedRef, ) { const reduced = useReducedMotion() ?? false; const [innerOpen, setInnerOpen] = useState(defaultOpen); const open = openProp ?? innerOpen; const generatedTriggerId = useId(); const triggerId = (isValidElement<{ id?: string }>(trigger) && trigger.props.id) || generatedTriggerId; const setOpen = useCallback( (next: boolean) => { setInnerOpen(next); onOpenChange?.(next); }, [onOpenChange], ); const panel = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: reducedTransition } : { initial: { opacity: 0, scale: motionTokens.scale.enterFrom }, animate: { opacity: 1, scale: 1 }, exit: { opacity: 0, scale: motionTokens.scale.enterFrom, transition: { duration: motionTokens.duration.quick, ease: motionTokens.ease.exit }, }, transition: { scale: motionTokens.spring.snappy, opacity: { duration: motionTokens.duration.quick, ease: motionTokens.ease.enter }, }, }; const nativeButton = typeof trigger.type === "string" ? trigger.type === "button" : true; return ( setOpen(next)}> {open ? ( } {...rest} > {arrow ? : null} {children} ) : null} ); }); export type PopoverTitleProps = ComponentPropsWithoutRef<"h2">; /** Names the popover; Base UI wires it to aria-labelledby. */ export const PopoverTitle = forwardRef(function PopoverTitle({ className, ...rest }, ref) { return ; }); export type PopoverDescriptionProps = ComponentPropsWithoutRef<"p">; /** Supporting sentence; Base UI wires it to aria-describedby. */ export const PopoverDescription = forwardRef(function PopoverDescription({ className, ...rest }, ref) { return ; }); export type PopoverCloseProps = ButtonProps; /** A Button that closes the popover and returns focus to the trigger. Secondary and small by default. */ export const PopoverClose = forwardRef(function PopoverClose( { variant = "secondary", size = "sm", icon, iconEnd, loading, ...rest }, ref, ) { return ( } > Budget for run 4821 The agent pauses and asks you before it spends past the limit.

{row.label}: {row.value}

Raise to $20

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | | What the panel holds: PopoverTitle, PopoverDescription, controls, PopoverClose. | | `trigger` (required) | `ReactElement` | | The element the panel anchors to and opens from, usually a Button. Rendered through Base UI's render prop. | | `open` | `boolean` | | Controlled open state. Pair with onOpenChange. | | `defaultOpen` | `boolean` | `false` | Starting open state when uncontrolled. | | `onOpenChange` | `(open: boolean) => void` | | Runs whenever the popover opens or closes. | | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred side of the trigger. It flips when there is no room. | | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along that side. | | `offset` | `number` | `8` | Gap between the trigger and the panel, in px. | | `arrow` | `boolean` | `false` | Draw a small arrow pointing at the trigger. | | `hoverOpen` | `boolean` | `false` | Also open when the trigger is hovered (fine pointers only). Clicks still toggle it. | | `container` | `HTMLElement \| null` | | Where the popover portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. | Also accepts every native `

` attribute, and a ref to it. ## Keyboard - `Enter`: On the trigger, toggles the popover; Space does the same. - `Tab`: Moves through the controls inside; tabbing past the last one closes it and moves on. - `Esc`: Closes the popover and returns focus to the trigger. ## Accessibility - Base UI renders the panel as a dialog labelled by PopoverTitle and described by PopoverDescription, and sets aria-expanded and aria-controls on the trigger. - Focus moves into the panel on open and back to the trigger on close. - It is not modal: the page stays scrollable and usable, and an outside press closes it. - hoverOpen is off by default because hover alone never reaches touch or keyboard users; clicking still works when it is on. ## Motion - The panel scales up from 0.96 on the snappy spring, growing out of the trigger: transform-origin follows the side and alignment Base UI resolved. - It closes in 150ms on the exit ease. - Reduced motion: fade only. ## Responsive - The panel is as wide as its content up to 352px and never wider than the space beside the trigger. - It flips to the other side when there is no room and shifts to stay on screen. ## Performance - Nothing is mounted while closed; positioning updates only while open. ## Notes for AI - Pass the anchor as trigger; the popover opens from it and returns focus to it. - Start content with PopoverTitle so the panel has an accessible name. - Use PopoverClose for the action that finishes the job ("Raise to $20"); it closes and restores focus. - Pass side and align for placement; it still flips when it would leave the screen. ## Related - [Tooltip](https://pixilui.com/components/tooltip/markdown): A short text label for an icon button, with its keyboard shortcut, that waits 400ms and then opens neighbours instantly while you scan a toolbar. - [Dialog](https://pixilui.com/components/dialog/markdown): A modal panel for one decision or one short task: a title, what happens, and the buttons that do it, with pending and error handled. - [Drawer](https://pixilui.com/components/drawer/markdown): A sheet that slides in from the right, left or bottom for details read alongside the page: a run, a trace, a record, a settings panel. - [Button](https://pixilui.com/components/button/markdown): A button whose label can change without a jump: the width springs to the new words while they swap in place. # Run timeline The steps of one agent run as a vertical timeline: a connector that fills as steps finish, a live timer on the active step, and a waiting step that holds an approval. Tier: free. Type: pattern. Category: ai. Tags: agent, run, trace, approval, motion. ## Install ```bash npx shadcn@latest add @pixilui/run-timeline ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/run-timeline.tsx`. npm: `motion`. ## Preview Live preview: https://pixilui.com/components/run-timeline Knobs: - `state`: `play`, `waiting`, `error`, `done` - `mode`: `expanded`, `compact` - `approval`: `auto`, `manual` Signature: The connector fills down to the next step as each check draws itself, until the run stops on an approval card and the card folds into a receipt. ## Code `components/pixilui/run-timeline.tsx` ```tsx "use client"; import { forwardRef, useEffect, useState, useSyncExternalStore, type ComponentPropsWithoutRef, type KeyboardEvent, type ReactNode } from "react"; import { AnimatePresence, motion, useReducedMotion } from "motion/react"; import { cn } from "./lib/utils"; import { instantTransition, motionTokens, reducedTransition } from "./motion-tokens"; const noSubscription = () => () => {}; /** * useReducedMotion, held at false until hydration finishes. The server cannot know the * preference, so reading it on the first client render would change the markup and break * hydration; the reduced branch takes over on the next render instead. */ function useReducedMotionAfterHydration() { const hydrated = useSyncExternalStore(noSubscription, () => true, () => false); const reduced = useReducedMotion(); return hydrated && (reduced ?? false); } export type RunTimelineStatus = "pending" | "active" | "done" | "error" | "waiting"; export type RunTimelineStep = { /** Stable key for the step; onStepSelect receives it. */ id: string; /** What the step does, in a few words: "Pull stuck refunds from Stripe". */ title: ReactNode; /** Evidence once it ran ("9 refunds pending for more than 72 hours"), or why it failed. Hidden in compact mode. */ detail?: ReactNode; /** Pending, active (live timer), done (drawn check), error, or waiting on a person. */ status: RunTimelineStatus; /** When the step started (epoch ms). Drives the live timer and the duration. */ startedAt?: number; /** When the step finished (epoch ms). With startedAt, shows how long it took. */ endedAt?: number; /** Content under the step: an approval card on a waiting step, a tool call, a diff. Waiting steps show it in compact mode too. */ children?: ReactNode; }; export type RunTimelineLabels = Record; const defaultLabels: RunTimelineLabels = { pending: "Up next", active: "In progress", done: "Done", error: "Failed", waiting: "Needs approval", }; export type RunTimelineProps = Omit, "children"> & { /** The run's steps, in order. Update a step's status and the timeline animates the change. */ steps: RunTimelineStep[]; /** Titles only, tighter rhythm. Waiting steps still show their children. */ compact?: boolean; /** Makes each step a button. Called with the step's id. */ onStepSelect?: (id: string) => void; /** The step shown elsewhere (a detail pane), marked with data-selected. */ selectedId?: string; /** Status words, read by screen readers and shown for waiting and failed steps. */ labels?: Partial; }; const TICK_MS = 250; /** "820ms", "1.4s", "1m 04s". */ function formatDuration(ms: number) { if (ms < 1000) return `${Math.round(ms)}ms`; if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`; const s = Math.round(ms / 1000); return `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`; } function formatLive(ms: number) { const s = Math.floor(ms / 1000); return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`; } /** A live timer whose digits are keyed by place and roll up. Only this re-renders each tick. */ function LiveTimer({ startedAt, reduced }: { startedAt: number; reduced: boolean }) { const [now, setNow] = useState(null); useEffect(() => { const tick = () => setNow(Date.now()); tick(); const id = setInterval(tick, TICK_MS); return () => clearInterval(id); }, [startedAt]); if (now === null) return null; const value = formatLive(Math.max(0, now - startedAt)); const chars = value.split(""); return ( {chars.map((char, index) => { const place = chars.length - index; if (reduced || !/\d/.test(char)) { return ( ); } return ( ); })} ); } /** Glyph rings sit between the 1px hairline and a 2px border. */ const ring = { borderWidth: 1.5 }; function Mark({ status, reduced }: { status: RunTimelineStatus; reduced: boolean }) { const draw = reduced ? { initial: { pathLength: 1 }, transition: reducedTransition } : { initial: { pathLength: 0 }, transition: { duration: motionTokens.duration.slow, ease: motionTokens.ease.enter, delay: motionTokens.stagger.item * 2 } }; switch (status) { case "pending": return ; case "active": return ( ); case "done": return ( ); case "error": return ( ); case "waiting": return ( ); } } /** * Detail and children open their own height, so the steps below are pushed along in the flow * (no overlap while the content fades in). Growing uses morph, closing uses smooth. The clip is * lifted once it has opened, so an approval card's shadow and focus ring show in full. */ function Reveal({ reduced, className, children, ...rest }: { reduced: boolean; className?: string; children: ReactNode; "data-slot"?: string }) { const [clip, setClip] = useState(true); const motionProps = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0, height: 0, transition: instantTransition }, transition: reducedTransition, } : { initial: { opacity: 0, height: 0, filter: `blur(${motionTokens.blur.subtle}px)` }, animate: { opacity: 1, height: "auto", filter: "blur(0px)", transition: { height: motionTokens.spring.morph, default: { duration: motionTokens.duration.fast, ease: motionTokens.ease.enter, delay: motionTokens.stagger.item * 2 }, }, }, exit: { opacity: 0, height: 0, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { height: motionTokens.spring.smooth, default: { duration: motionTokens.duration.instant, ease: motionTokens.ease.exit } }, }, }; return ( setClip(true)} onAnimationComplete={() => setClip(false)} > {children} ); } export const RunTimeline = forwardRef(function RunTimeline( { steps, compact = false, onStepSelect, selectedId, labels: labelsProp, className, onKeyDown, ...rest }, ref, ) { const labels = { ...defaultLabels, ...labelsProp }; const reduced = useReducedMotionAfterHydration(); // Up and Down walk the step buttons, Home and End jump to the ends. const handleKeyDown = (event: KeyboardEvent) => { onKeyDown?.(event); if (event.defaultPrevented || !onStepSelect || !["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) return; const buttons = Array.from(event.currentTarget.querySelectorAll('[data-slot="run-timeline-trigger"]')); const current = buttons.indexOf(event.target as HTMLElement); if (current === -1) return; event.preventDefault(); const next = event.key === "Home" ? 0 : event.key === "End" ? buttons.length - 1 : Math.min(buttons.length - 1, Math.max(0, current + (event.key === "ArrowDown" ? 1 : -1))); buttons[next]?.focus(); }; const swapIn = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0, transition: instantTransition }, transition: instantTransition } : { initial: { opacity: 0, scale: motionTokens.scale.enterFrom, filter: `blur(${motionTokens.blur.subtle}px)` }, animate: { opacity: 1, scale: 1, filter: "blur(0px)" }, exit: { opacity: 0, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.instant, ease: motionTokens.ease.exit } }, transition: { duration: motionTokens.duration.fast, ease: motionTokens.ease.swap }, }; return (

{step.title}

{flagged ? {labels[step.status]} : null} {step.status === "active" && step.startedAt !== undefined ? : null} {step.status === "done" && duration !== null ? {formatDuration(duration)} : null}

{/* Rail: the glyph, then the connector to the next step, which fills when this one is done. */}
{onStepSelect ? ( ) : (
{titleRow}
)} {labels[step.status]} {showDetail ? (
{step.detail}
) : null} {showChildren ? (
{step.children}
) : null}

); }); ``` ## Usage When to use: - Showing an agent run in progress, step by step, with the evidence of what each step did. - A run that pauses for a person: the waiting step hosts an approval card in place. - A run history view where each step can open details elsewhere (onStepSelect). When not to use: - A flat list of tool calls inside one message: use tool-call-row with ToolCallRowGroup. - A quiet status line while a model thinks: use thinking-state. - A form wizard or onboarding progress: use a stepper. ```tsx import { useEffect, useState, useSyncExternalStore } from "react"; import { useReducedMotion } from "motion/react"; import { Mail, RotateCcw } from "lucide-react"; import { Button } from "@/components/pixilui/button"; import { ApprovalCard, type ApprovalCardItem, type ApprovalCardStatus } from "@/components/pixilui/approval-card"; import { RunTimeline, type RunTimelineStatus, type RunTimelineStep } from "@/components/pixilui/run-timeline"; const noSubscription = () => () => {}; /** * useReducedMotion, held at false until hydration finishes. The server cannot know the * preference, so reading it on the first client render would change the markup and break * hydration; the reduced branch takes over on the next render instead. */ function useReducedMotionAfterHydration() { const hydrated = useSyncExternalStore(noSubscription, () => true, () => false); const reduced = useReducedMotion(); return hydrated && (reduced ?? false); } // The first option of each knob is the demo's default; the docs preview starts there. export const knobs = { state: ["play", "waiting", "error", "done"], mode: ["expanded", "compact"], approval: ["auto", "manual"], } as const; type StepCopy = { id: string; title: string; detail: string }; const STEPS: StepCopy[] = [ { id: "pull", title: "Pull stuck refunds from Stripe", detail: "9 refunds pending for more than 72 hours" }, { id: "match", title: "Match refunds to customer accounts", detail: "7 accounts, with 2 duplicate refunds merged" }, { id: "draft", title: "Draft apology emails with a $15 credit", detail: "7 drafts in the support voice, 94 to 118 words each" }, { id: "approve", title: "Get approval to send", detail: "Approved by Dana Whitfield" }, { id: "post", title: "Post the summary to #support-ops", detail: "Posted with links to ENG-4127 and the 7 tickets" }, ]; const ITEMS: ApprovalCardItem[] = [ { label: "Recipients", value: "7 customers" }, { label: "Credits", value: "$105.00", numeric: true }, { label: "Sends from", value: "support@northwind.co" }, ]; type StepState = { status: RunTimelineStatus; startedAt?: number; endedAt?: number }; type Frame = { steps: StepState[]; approval: ApprovalCardStatus }; // Fixed clock for the still states, so durations read the same on every render. const T0 = 1_761_400_000_000; const DURATIONS = [1140, 870, 2260, 4120, 930]; const ended = (index: number): StepState => { const start = T0 + DURATIONS.slice(0, index).reduce((a, b) => a + b, 0); return { status: "done", startedAt: start, endedAt: start + DURATIONS[index]! }; }; const STILL: Record<"waiting" | "error" | "done", Frame> = { waiting: { steps: [ended(0), ended(1), ended(2), { status: "waiting" }, { status: "pending" }], approval: "pending" }, error: { steps: [ended(0), ended(1), { status: "error" }, { status: "pending" }, { status: "pending" }], approval: "pending" }, done: { steps: STEPS.map((_, index) => ended(index)), approval: "approved" }, }; const START: Frame = { steps: STEPS.map(() => ({ status: "pending" })), approval: "pending" }; const STEP_MS = 900; export default function RunTimelineDemo({ state = "play", mode = "expanded", approval = "auto" }: KnobValues) { const reduced = useReducedMotionAfterHydration(); const [run, setRun] = useState(0); const [frame, setFrame] = useState(START); const [finished, setFinished] = useState(false); const playing = state === "play" && !reduced; const combo = `${state}-${approval}-${reduced}`; const [seen, setSeen] = useState(null); if (seen !== combo) { setSeen(combo); setFinished(false); setFrame(playing ? START : STILL[state === "play" ? "done" : state]); } const setStep = (index: number, next: StepState) => setFrame((f) => ({ ...f, steps: f.steps.map((s, i) => (i === index ? next : s)) })); // Steps 1 to 3 run at reading speed, then the run waits on a person. useEffect(() => { if (!playing) return; const begin = (index: number) => () => setFrame((f) => ({ ...f, steps: f.steps.map((s, i) => (i === index ? { status: "active", startedAt: Date.now() } : s)) })); const finish = (index: number) => () => setFrame((f) => ({ ...f, steps: f.steps.map((s, i) => (i === index ? { ...s, status: "done", endedAt: Date.now() } : s)) })); const plan: [number, () => void][] = [ [300, begin(0)], [300 + STEP_MS, finish(0)], [300 + STEP_MS, begin(1)], [300 + STEP_MS * 2, finish(1)], [300 + STEP_MS * 2, begin(2)], [300 + STEP_MS * 3, finish(2)], [300 + STEP_MS * 3, () => setFrame((f) => ({ ...f, steps: f.steps.map((s, i) => (i === 3 ? { status: "waiting", startedAt: Date.now() } : s)) }))], ]; if (approval === "auto") plan.push([300 + STEP_MS * 3 + 2000, () => setFrame((f) => ({ ...f, approval: "approved" }))]); const timers = plan.map(([at, fn]) => setTimeout(fn, at)); return () => timers.forEach(clearTimeout); }, [playing, approval, run]); // Once approved: close the waiting step, then run the last one. const approved = frame.approval === "approved"; const waitingOnApproval = frame.steps[3]!.status === "waiting"; const lastStatus = frame.steps[4]!.status; useEffect(() => { if (!approved || !waitingOnApproval) return; const id = setTimeout( () => setFrame((f) => ({ ...f, steps: f.steps.map((s, i) => (i === 3 ? { ...s, status: "done", endedAt: Date.now() } : i === 4 ? { status: "active", startedAt: Date.now() } : s)) })), 500, ); return () => clearTimeout(id); }, [approved, waitingOnApproval]); useEffect(() => { if (lastStatus === "active") { const id = setTimeout(() => setFrame((f) => ({ ...f, steps: f.steps.map((s, i) => (i === 4 ? { ...s, status: "done", endedAt: Date.now() } : s)) })), STEP_MS + 100); return () => clearTimeout(id); } if (lastStatus === "done") { const id = setTimeout(() => setFinished(true), STEP_MS); return () => clearTimeout(id); } }, [lastStatus]); const steps: RunTimelineStep[] = STEPS.map((copy, index) => { const s = frame.steps[index]!; const detail = s.status === "done" ? copy.detail : s.status === "error" ? "Template refund-apology-v2 was archived on Oct 21. Pick another and retry." : undefined; const card = copy.id === "approve" && (s.status === "waiting" || s.status === "done") ? ( } source="Support agent, run 7f2e1c" items={ITEMS} risk="medium" status={frame.approval} receipt="7 emails queued, $105.00 in credits applied" labels={{ approve: "Approve and send" }} onApprove={async () => { await new Promise((resolve) => setTimeout(resolve, 700)); setFrame((f) => ({ ...f, approval: "approved" })); }} onReject={async () => { await new Promise((resolve) => setTimeout(resolve, 500)); setStep(3, { status: "error" }); }} /> ) : undefined; return { id: copy.id, title: copy.title, detail: copy.id === "approve" ? undefined : detail, status: s.status, startedAt: s.startedAt, endedAt: s.endedAt, children: card }; }); return (

{state === "play" && !reduced && finished ? ( ) : null}

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `steps` (required) | `RunTimelineStep[]` | | The run's steps, in order. Update a step's status and the timeline animates the change. | | `compact` | `boolean` | `false` | Titles only, tighter rhythm. Waiting steps still show their children. | | `onStepSelect` | `(id: string) => void` | | Makes each step a button. Called with the step's id. | | `selectedId` | `string` | | The step shown elsewhere (a detail pane), marked with data-selected. | | `labels` | `Partial` | | Status words, read by screen readers and shown for waiting and failed steps. | Also accepts every native `

, "children"> & { /** Everything received so far. Pass the growing string on every chunk; only the new words animate. */ text: string; /** More text is on its way: shows the caret and holds back a word that has not finished arriving. */ streaming?: boolean; /** Show a caret at the end while streaming. */ caret?: boolean; /** Milliseconds between words as they reveal. A large chunk speeds up until the reveal is back within about 1.5s of the stream. */ speed?: number; /** Pause the reveal while a mouse rests on the text, so people can read; it catches up on leave. */ pauseOnHover?: boolean; /** Render text between backticks as inline code. */ inlineCode?: boolean; /** Called once every word has revealed after streaming ends. */ onRevealComplete?: () => void; }; type Token = { /** The word, without the whitespace after it. */ word: string; /** Whitespace after the word (may hold newlines). Rendered as plain text, never animated. */ space: string; code: boolean; }; type Reveal = { tokens: Token[]; /** Tokens on screen. */ released: number; /** Tokens that have finished animating and render as plain text. */ settled: number; /** The tokens released in the last tick, spread across it. */ batchFrom: number; batchSize: number; /** Words per tick while catching up. Held steady until the backlog is back inside the window. */ rate: number; }; /** A large chunk speeds the reveal up until it is back within this many milliseconds of words. */ const MAX_LAG_MS = 1500; function tokenize(text: string, inlineCode: boolean): Token[] { const tokens: Token[] = []; const parts = inlineCode ? text.split("`") : [text]; parts.forEach((part, index) => { if (!part) return; const code = inlineCode && index % 2 === 1; const lead = /^\s+/.exec(part); if (lead) tokens.push({ word: "", space: lead[0], code }); for (const match of part.slice(lead ? lead[0].length : 0).matchAll(/(\S+)(\s*)/g)) { tokens.push({ word: match[1]!, space: match[2]!, code }); } }); return tokens; } /** How many leading tokens two token lists share (words and code only; trailing space may grow). */ function sharedPrefix(a: Token[], b: Token[]) { const max = Math.min(a.length, b.length); let i = 0; while (i < max && a[i]!.word === b[i]!.word && a[i]!.code === b[i]!.code) i++; return i; } /** Settled tokens as a few plain runs: one text node per run, however long the text gets. */ function runs(tokens: Token[]) { const out: { text: string; code: boolean }[] = []; for (const token of tokens) { const last = out[out.length - 1]; if (last && last.code === token.code) last.text += token.word + token.space; else out.push({ text: token.word + token.space, code: token.code }); } return out; } const codeClass = "rounded-control bg-surface-muted px-1 py-px font-mono"; const codeStyle = { fontSize: "0.9em" }; export const StreamingText = forwardRef(function StreamingText( { text, streaming = false, caret = true, speed = 50, pauseOnHover = false, inlineCode = true, onRevealComplete, className, onPointerEnter, onPointerLeave, ...rest }, ref, ) { const reduced = useReducedMotionAfterHydration(); const tokens = useMemo(() => tokenize(text, inlineCode), [text, inlineCode]); const last = tokens[tokens.length - 1]; // A word without whitespace after it may still be arriving ("Searc" then "hed"): hold it back. const available = streaming && last && last.space === "" ? tokens.length - 1 : tokens.length; const [state, setState] = useState(() => ({ tokens, released: 0, settled: 0, batchFrom: 0, batchSize: 0, rate: 1 })); const [paused, setPaused] = useState(false); // Append-only diff, during render: keep what still matches, rewind past anything that changed. let reveal = state; if (state.tokens !== tokens) { const keep = sharedPrefix(state.tokens, tokens); reveal = { tokens, released: Math.min(state.released, keep), settled: Math.min(state.settled, keep), batchFrom: state.batchFrom, batchSize: state.batchSize, rate: state.rate, }; setState(reveal); } const released = reduced ? available : Math.min(reveal.released, tokens.length); const settled = reduced ? available : Math.min(reveal.settled, released); const hasBacklog = !reduced && reveal.released < available; const availableRef = useRef(available); const generation = useRef(0); useLayoutEffect(() => { availableRef.current = available; }, [available]); useLayoutEffect(() => { generation.current += 1; }, [tokens]); // The clock: one tick per `speed` ms while there is a backlog. New chunks never restart it. useEffect(() => { if (!hasBacklog || paused) return; const id = setTimeout(() => { setState((prev) => { const backlog = availableRef.current - prev.released; if (backlog <= 0) return prev; // Inside the window: one word per tick. Beyond it: a steady rate that drains the excess in about one window. const inWindow = Math.max(1, Math.floor(MAX_LAG_MS / speed)); const rate = backlog <= inWindow ? 1 : Math.max(prev.rate, Math.ceil(backlog / inWindow)); const size = Math.min(backlog, rate); return { ...prev, released: prev.released + size, batchFrom: prev.released, batchSize: size, rate }; }); }, speed); return () => clearTimeout(id); }, [hasBacklog, paused, reveal.released, speed]); // Words settle into plain text once their rise has finished, so the DOM stays a few nodes deep. const settleTimers = useRef(new Set>()); useEffect(() => { if (reduced || reveal.released <= reveal.settled) return; const target = reveal.released; const gen = generation.current; const timers = settleTimers.current; const id = setTimeout(() => { timers.delete(id); if (gen !== generation.current) return; setState((prev) => ({ ...prev, settled: Math.max(prev.settled, Math.min(target, prev.released)) })); }, motionTokens.duration.fast * 1000 + speed); timers.add(id); }, [reduced, reveal.released, reveal.settled, speed]); useEffect(() => { const timers = settleTimers.current; return () => timers.forEach(clearTimeout); }, []); const complete = !streaming && released >= tokens.length; const completeRef = useRef(complete); useEffect(() => { if (complete && !completeRef.current) onRevealComplete?.(); completeRef.current = complete; }, [complete, onRevealComplete]); const plain = useMemo(() => runs(tokens.slice(0, settled)), [tokens, settled]); const tail = tokens.slice(settled, released); const handleEnter = (event: PointerEvent) => { onPointerEnter?.(event); if (pauseOnHover && event.pointerType === "mouse") setPaused(true); }; const handleLeave = (event: PointerEvent) => { onPointerLeave?.(event); setPaused(false); }; const spread = reveal.batchSize > 1 ? speed / reveal.batchSize / 1000 : 0; return (

{plain.map((run, index) => run.code ? (


            {run.text}

) : ( {run.text} ), )} {tail.map((token, offset) => { const index = settled + offset; const inBatch = index - reveal.batchFrom; const delay = inBatch > 0 && inBatch < reveal.batchSize ? inBatch * spread : 0; return ( {token.word ? ( {token.word} ) : null} {token.space} ); })} {caret && !complete ? (

); }); ``` ## Usage When to use: - Showing a model's reply token by token in a chat, a summary panel or an inline suggestion. - Any text that arrives in chunks of uneven size and should read as one calm stream. When not to use: - Markdown with headings, lists and code blocks: render it with your markdown renderer and stream into that. - Static copy that is already complete: render it as text. - Status while the model has not started answering: use thinking-state. ```tsx import { useEffect, useState, useSyncExternalStore } from "react"; import { useReducedMotion } from "motion/react"; import { RotateCcw } from "lucide-react"; import { Button } from "@/components/pixilui/button"; import { StreamingText } from "@/components/pixilui/streaming-text"; const noSubscription = () => () => {}; /** * useReducedMotion, held at false until hydration finishes. The server cannot know the * preference, so reading it on the first client render would change the markup and break * hydration; the reduced branch takes over on the next render instead. */ function useReducedMotionAfterHydration() { const hydrated = useSyncExternalStore(noSubscription, () => true, () => false); const reduced = useReducedMotion(); return hydrated && (reduced ?? false); } // The first option of each knob is the demo's default; the docs preview starts there. export const knobs = { state: ["play", "done"], chunks: ["tokens", "one big chunk"], speed: [50, 30, 80], } as const; const ANSWER = "Checkout errors started at 09:42 UTC, four minutes after deploy `4f3a9c1` shipped new retry logic in `payments-client`. " + "Every failed call to Stripe retried three times with no backoff, so request volume doubled and 1,318 checkouts timed out " + "before Priya Nair rolled the deploy back at 09:58.\n\n" + "About $41,300 in carts were abandoned, mostly from 212 merchants on the EU cluster. I opened ENG-4127 to add jittered " + "backoff and a test that fails on more than one retry per second."; // Uneven chunk sizes (in characters) and gaps, the way a model streams: words often split mid-way. const SIZES = [7, 3, 12, 5, 18, 2, 9, 4, 14, 6, 11, 8]; const GAPS = [70, 45, 110, 60, 90, 40, 130]; function chunkPlan(bigChunk: boolean) { if (bigChunk) { const cut = ANSWER.indexOf("\n\n") + 2; return [ { at: 400, end: cut }, { at: 2600, end: ANSWER.length }, ]; } const plan: { at: number; end: number }[] = []; let end = 0; let at = 400; for (let i = 0; end < ANSWER.length; i++) { end = Math.min(ANSWER.length, end + SIZES[i % SIZES.length]!); at += GAPS[i % GAPS.length]!; plan.push({ at, end }); } return plan; } export default function StreamingTextDemo({ state = "play", chunks = "tokens", speed = 50 }: KnobValues) { const reduced = useReducedMotionAfterHydration(); const [run, setRun] = useState(0); const [received, setReceived] = useState(0); const [finished, setFinished] = useState(false); const [revealed, setRevealed] = useState(false); const playing = state === "play" && !reduced; // A knob change starts the stream again. const combo = `${state}-${chunks}-${speed}`; const [seen, setSeen] = useState(combo); if (seen !== combo) { setSeen(combo); setReceived(0); setFinished(false); setRevealed(false); } useEffect(() => { if (!playing) return; const plan = chunkPlan(chunks === "one big chunk"); const timers = plan.map(({ at, end }, index) => setTimeout(() => { setReceived(end); if (index === plan.length - 1) setFinished(true); }, at), ); return () => timers.forEach(clearTimeout); }, [playing, chunks, run]); const text = playing ? ANSWER.slice(0, received) : ANSWER; const streaming = playing && !finished; return (

Why did checkout errors spike this morning?

setRevealed(true)} className="min-h-48" />

{playing && revealed ? ( ) : null}

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `text` (required) | `string` | | Everything received so far. Pass the growing string on every chunk; only the new words animate. | | `streaming` | `boolean` | `false` | More text is on its way: shows the caret and holds back a word that has not finished arriving. | | `caret` | `boolean` | `true` | Show a caret at the end while streaming. | | `speed` | `number` | `50` | Milliseconds between words as they reveal. A large chunk speeds up until the reveal is back within about 1.5s of the stream. | | `pauseOnHover` | `boolean` | `false` | Pause the reveal while a mouse rests on the text, so people can read; it catches up on leave. | | `inlineCode` | `boolean` | `true` | Render text between backticks as inline code. | | `onRevealComplete` | `() => void` | | Called once every word has revealed after streaming ends. | Also accepts every native `

` attribute, and a ref to it. ## Keyboard - `Tab`: Nothing to focus; the text is read as it is, and links or code inside it keep their own behaviour. ## Accessibility - The root sets aria-busy while text is still arriving, so assistive tech can wait for the whole answer. - It is not a live region on its own: put it inside your message list's role="log" so new messages are announced once, not word by word. - Words are kept whole in the DOM and the caret is aria-hidden, so the text reads normally at any moment. ## Motion - Only new words animate: each rises 0.3em out of a 4px blur in 250ms on the enter easing. - Words reveal about 50ms apart (speed). A large chunk speeds up until the reveal is back within about 1.5s of the stream. - A word whose end has not arrived yet is held back, so a word never animates in two halves. - The caret fades out in 150ms when the stream ends and every word is shown. - Reduced motion: chunks appear instantly, no rise, no blur. ## Responsive - Wraps like normal text and keeps newlines (white-space: pre-wrap); long words and URLs break inside the line. - Inherits the container's width; default size is text-16, override with className. ## Performance - Text is diffed per chunk (append-only); words that finished animating collapse back into a few text nodes, so a long answer stays a handful of DOM nodes. - Animation runs on transform, opacity and filter only, so no layout is read per word. - One timer drives the reveal; new chunks never restart it. ## Notes for AI - Pass the whole text received so far on every chunk, not the delta. If the text changes in the middle (a regenerate), the component rewinds to the shared prefix. - Set streaming to true while chunks arrive and false when the stream closes; the caret drops once the last word is shown. - Text between backticks renders as inline code; turn it off with inlineCode={false}. - Use pauseOnHover on long answers so a reader can stop the text under their mouse. - onRevealComplete fires once the last word is on screen, useful for showing follow-up actions after the answer, not before. ## Related - [Thinking state](https://pixilui.com/components/thinking-state/markdown): A quiet line that says what the agent is doing while it works, with a live timer, steps that unfold, and a fold into "Thought for 12s" when it is done. - [Tool call row](https://pixilui.com/components/tool-call-row/markdown): One line per tool call: what it did in plain words, the tool's name, a live timer, and a fold-out with the input and output as copyable JSON. ToolCallRowGroup sums several calls into one line. - [Run timeline](https://pixilui.com/components/run-timeline/markdown): The steps of one agent run as a vertical timeline: a connector that fills as steps finish, a live timer on the active step, and a waiting step that holds an approval. # Thinking state A quiet line that says what the agent is doing while it works, with a live timer, steps that unfold, and a fold into "Thought for 12s" when it is done. Tier: free. Type: pattern. Category: ai. Tags: agent, run, streaming, motion. ## Install ```bash npx shadcn@latest add @pixilui/thinking-state ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/thinking-state.tsx`. npm: `motion`. ## Preview Live preview: https://pixilui.com/components/thinking-state Knobs: - `state`: `play`, `working`, `done` - `steps`: `with steps`, `line only` Signature: The shimmer runs across the line while the timer digits roll, then the steps fold away and the line becomes "Thought for 4s". ## Code `components/pixilui/thinking-state.tsx` ```tsx "use client"; import { forwardRef, useCallback, useEffect, useId, useRef, useState, useSyncExternalStore, type ComponentPropsWithoutRef, type ReactNode, } from "react"; import { AnimatePresence, motion, useReducedMotion, type Variants } from "motion/react"; import { cn } from "./lib/utils"; import { useMorphSize } from "./lib/use-morph-size"; import { motionTokens, reducedTransition } from "./motion-tokens"; const noSubscription = () => () => {}; /** * useReducedMotion, held at false until hydration finishes. The server cannot know the * preference, so reading it on the first client render would change the markup and break * hydration; the reduced branch takes over on the next render instead. */ function useReducedMotionAfterHydration() { const hydrated = useSyncExternalStore(noSubscription, () => true, () => false); const reduced = useReducedMotion(); return hydrated && (reduced ?? false); } export type ThinkingStateStepStatus = "pending" | "active" | "done"; export type ThinkingStateStep = { /** Stable key for the step. */ id: string; /** What the agent is doing or did, in plain words: "Reading the incident timeline". */ text: string; /** Pending steps are muted, the active one reads in full colour, done steps get a drawn check. */ status: ThinkingStateStepStatus; }; export type ThinkingStateProps = Omit, "children"> & { /** What the agent is doing right now. Changing it crossfades the line. */ label?: string; /** The steps behind the line, shown when expanded. Leave it out for a single quiet line. */ steps?: ThinkingStateStep[]; /** When the work started (epoch ms). Drives a live timer that stops when done. */ startedAt?: number; /** Elapsed time you track yourself (ms). Wins over startedAt; pass it for a finished run you render later. */ elapsedMs?: number; /** Controlled: whether the steps are unfolded. */ expanded?: boolean; /** Starting fold when uncontrolled. */ defaultExpanded?: boolean; /** Called when the person toggles the steps, and with false when the work finishes. */ onExpandedChange?: (expanded: boolean) => void; /** The work is finished: the shimmer stops, the timer freezes and the line folds into "Thought for 12s". */ done?: boolean; /** The finished line. A function receives the elapsed time in ms (null when there is no timer). */ doneLabel?: string | ((elapsedMs: number | null) => string); /** Show the live timer beside the label. */ showTimer?: boolean; /** The agent's mark, shown small before the label. */ icon?: ReactNode; }; /** One pass of the shimmer across the label: 1.92s, linear. */ const SWEEP = motionTokens.duration.considered * 4; const TICK_MS = 250; /** "12s", "1m 04s". */ function formatThinkingTime(ms: number) { const s = Math.floor(ms / 1000); if (s < 60) return `${s}s`; return `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`; } const defaultDoneLabel = (ms: number | null) => (ms === null ? "Thought it through" : `Thought for ${formatThinkingTime(Math.max(ms, 1000))}`); function useElapsed(startedAt: number | undefined, running: boolean) { const [now, setNow] = useState(null); useEffect(() => { if (startedAt === undefined || !running) return; const tick = () => setNow(Date.now()); tick(); const id = setInterval(tick, TICK_MS); return () => clearInterval(id); }, [startedAt, running]); return startedAt === undefined || now === null ? null : Math.max(0, now - startedAt); } /** Digits keyed by place that roll up as the time grows. */ function ThinkingStateTicker({ value, reduced }: { value: string; reduced: boolean }) { const chars = value.split(""); return ( {chars.map((char, index) => { const place = chars.length - index; if (reduced || !/\d/.test(char)) { return ( ); } return ( ); })} ); } function ThinkingStateGlyph({ status, reduced }: { status: ThinkingStateStepStatus; reduced: boolean }) { if (status === "done") { return ( ); } return ( ); } export const ThinkingState = forwardRef(function ThinkingState( { label = "Thinking", steps = [], startedAt, elapsedMs, expanded: expandedProp, defaultExpanded = false, onExpandedChange, done = false, doneLabel = defaultDoneLabel, showTimer = true, icon, className, ...rest }, forwardedRef, ) { const reduced = useReducedMotionAfterHydration(); const stepsId = useId(); const [innerExpanded, setInnerExpanded] = useState(defaultExpanded); const expanded = expandedProp ?? innerExpanded; const hasSteps = steps.length > 0; const open = expanded && hasSteps; const live = useElapsed(startedAt, !done); const elapsed = elapsedMs ?? live; const finished = typeof doneLabel === "function" ? doneLabel(elapsed) : doneLabel; const line = done ? finished : label; // Finishing folds the steps away, once, when done turns true. const [foldedFor, setFoldedFor] = useState(done); if (done !== foldedFor) { setFoldedFor(done); if (done && expandedProp === undefined) setInnerExpanded(false); } const last = useRef({ done, expanded }); useEffect(() => { if (done && !last.current.done && last.current.expanded) onExpandedChange?.(false); last.current = { done, expanded }; }, [done, expanded, onExpandedChange]); const toggle = () => { const next = !expanded; if (expandedProp === undefined) setInnerExpanded(next); onExpandedChange?.(next); }; const { containerRef, measureRef } = useMorphSize("height", `${open}:${steps.length}:${done}`); const setRef = useCallback( (node: HTMLDivElement | null) => { containerRef.current = node; if (typeof forwardedRef === "function") forwardedRef(node); else if (forwardedRef) forwardedRef.current = node; }, [forwardedRef, containerRef], ); const shimmer = !done && !reduced; const swap = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: reducedTransition } : { initial: { opacity: 0, y: "0.3em", filter: `blur(${motionTokens.blur.soft}px)` }, animate: { opacity: 1, y: 0, filter: "blur(0px)" }, exit: { opacity: 0, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.instant, ease: motionTokens.ease.exit } }, transition: { duration: motionTokens.duration.fast, ease: motionTokens.ease.enter }, }; const listVariants: Variants = { hidden: {}, shown: { transition: { staggerChildren: reduced ? 0 : motionTokens.stagger.item } } }; const stepVariants: Variants = reduced ? { hidden: { opacity: 0 }, shown: { opacity: 1, transition: reducedTransition } } : { hidden: { opacity: 0, y: motionTokens.distance.micro, filter: `blur(${motionTokens.blur.subtle}px)` }, shown: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: motionTokens.duration.fast, ease: motionTokens.ease.enter } }, }; const headerContent = ( <> {icon ? {icon} : null} {shimmer ? ( {line} ) : ( {line} )} {showTimer && !done && elapsed !== null ? : null} {hasSteps ? ( ) : null} ); const headerClass = "flex max-w-full min-w-0 items-center gap-2 rounded-control py-1 text-left"; return (

{hasSteps ? ( ) : (

{headerContent}

)} {open ? ( {steps.map((step) => ( {step.text} {step.status === "done" ? ", done" : step.status === "active" ? ", in progress" : ", up next"} ))} ) : null}

{line}

); }); ``` ## Usage When to use: - A model or agent is working before it answers and the person needs to know it is alive and what it is on. - You want to show the reasoning steps on demand without pushing them into the answer. When not to use: - A run with tool calls, durations and approvals to audit: use run-timeline. - A single tool call: use tool-call-row. - Page or data loading with no agent behind it: use a skeleton. ```tsx import { useEffect, useState, useSyncExternalStore } from "react"; import { useReducedMotion } from "motion/react"; import { Activity, RotateCcw } from "lucide-react"; import { Button } from "@/components/pixilui/button"; import { ThinkingState, type ThinkingStateStep } from "@/components/pixilui/thinking-state"; const noSubscription = () => () => {}; /** * useReducedMotion, held at false until hydration finishes. The server cannot know the * preference, so reading it on the first client render would change the markup and break * hydration; the reduced branch takes over on the next render instead. */ function useReducedMotionAfterHydration() { const hydrated = useSyncExternalStore(noSubscription, () => true, () => false); const reduced = useReducedMotion(); return hydrated && (reduced ?? false); } // The first option of each knob is the demo's default; the docs preview starts there. export const knobs = { state: ["play", "working", "done"], steps: ["with steps", "line only"], } as const; const STEP_TEXT = [ "Reading INC-2291 and the deploy log for checkout-api", "Comparing p95 latency before and after deploy 4f3a9c1", "Counting merchants that saw 502s between 09:42 and 09:58", "Drafting the summary for #ops-incidents", ]; const stepsAt = (active: number): ThinkingStateStep[] => STEP_TEXT.slice(0, active + 1).map((text, index) => ({ id: `s${index}`, text, status: index < active ? "done" : "active", })); const allDone: ThinkingStateStep[] = STEP_TEXT.map((text, index) => ({ id: `s${index}`, text, status: "done" })); // One step every 0.9s, then the fold. const STEP_MS = 900; type Frame = { steps: ThinkingStateStep[]; done: boolean; expanded: boolean }; export default function ThinkingStateDemo({ state = "play", steps = "with steps" }: KnobValues) { const reduced = useReducedMotionAfterHydration(); const [run, setRun] = useState(0); const [startedAt, setStartedAt] = useState(undefined); const [frame, setFrame] = useState({ steps: [], done: false, expanded: true }); const playing = state === "play" && !reduced; useEffect(() => { if (!playing) return; const timers = [ setTimeout(() => { setStartedAt(Date.now()); setFrame({ steps: [], done: false, expanded: true }); }, 0), ...STEP_TEXT.map((_, index) => setTimeout(() => setFrame({ steps: stepsAt(index), done: false, expanded: true }), 300 + index * STEP_MS)), setTimeout(() => setFrame({ steps: allDone, done: false, expanded: true }), 300 + STEP_TEXT.length * STEP_MS), setTimeout(() => setFrame({ steps: allDone, done: true, expanded: false }), 700 + STEP_TEXT.length * STEP_MS), ]; return () => timers.forEach(clearTimeout); }, [playing, run]); // The working state still ticks: it started six seconds before the preview opened. useEffect(() => { if (state !== "working") return; const id = setTimeout(() => setStartedAt(Date.now() - 6000), 0); return () => clearTimeout(id); }, [state]); const shown: Frame & { elapsedMs?: number; startedAt?: number } = playing ? { ...frame, startedAt } : state === "working" ? { steps: stepsAt(2), done: false, expanded: true, startedAt } : { steps: allDone, done: true, expanded: false, elapsedMs: 4300 }; return (

Why did checkout errors spike this morning?

} steps={steps === "with steps" ? shown.steps : undefined} startedAt={shown.startedAt} elapsedMs={shown.elapsedMs} defaultExpanded={shown.expanded} done={shown.done} />

{playing && shown.done ? ( ) : null}

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `label` | `string` | `"Thinking"` | What the agent is doing right now. Changing it crossfades the line. | | `steps` | `ThinkingStateStep[]` | `[]` | The steps behind the line, shown when expanded. Leave it out for a single quiet line. | | `startedAt` | `number` | | When the work started (epoch ms). Drives a live timer that stops when done. | | `elapsedMs` | `number` | | Elapsed time you track yourself (ms). Wins over startedAt; pass it for a finished run you render later. | | `expanded` | `boolean` | | Controlled: whether the steps are unfolded. | | `defaultExpanded` | `boolean` | `false` | Starting fold when uncontrolled. | | `onExpandedChange` | `(expanded: boolean) => void` | | Called when the person toggles the steps, and with false when the work finishes. | | `done` | `boolean` | `false` | The work is finished: the shimmer stops, the timer freezes and the line folds into "Thought for 12s". | | `doneLabel` | `string \| ((elapsedMs: number \| null) => string)` | `defaultDoneLabel` | The finished line. A function receives the elapsed time in ms (null when there is no timer). | | `showTimer` | `boolean` | `true` | Show the live timer beside the label. | | `icon` | `ReactNode` | | The agent's mark, shown small before the label. | Also accepts every native `

` attribute, and a ref to it. ## Keyboard - `Tab`: Focuses the line when it has steps. - `Enter`: Unfolds or folds the steps. - `Space`: Unfolds or folds the steps. ## Accessibility - The line is a real button with aria-expanded and aria-controls pointing at the step list; with no steps it is plain text. - The root sets aria-busy while working. A polite live region announces the label and the finished line, never the ticking timer. - The timer has role timer, so screen readers do not read every tick. - Each step carries its status in text (done, in progress, up next) after the words, so meaning never rests on the glyph. ## Motion - A soft shimmer sweeps across the label on linear easing, one pass every 1.92s, and stops when the work is done. - Timer digits are keyed by place and roll up on the snappy spring. - Steps arrive in reading order 35ms apart, rising 4px out of a 2px blur; a step that finishes draws its check. - Finishing folds the steps away on the smooth spring while the label crossfades into "Thought for 12s". Unfolding grows on the morph spring. - Reduced motion: no shimmer, no rolling digits, instant fold, short fades. ## Responsive - Fills its container; the label truncates on one line and the steps wrap. - No surface of its own, so it sits inside a message list or a card without doubling borders. ## Performance - One ResizeObserver drives the fold. The timer re-renders four times a second only while working. - The shimmer animates background-position on one span; no layout work per frame. ## Notes for AI - Pass startedAt when the run begins and done when the first answer token arrives; the timer freezes and the line folds itself. - For a run rendered later from history, pass elapsedMs with done so the line reads the real duration. - Keep label to what the agent is doing in plain words ("Looking into the checkout errors"); put the steps in steps, newest last, with one active. - Pass the agent's mark as icon. Never a sparkle; the component bakes in no icon. - doneLabel can be a function of elapsed milliseconds for translation: (ms) => `Pensó durante ${Math.round(ms / 1000)} s`. ## Related - [Streaming text](https://pixilui.com/components/streaming-text/markdown): Renders a model's answer as it streams: only new words rise into place at reading speed, a caret holds the end, and half-arrived words wait until they are whole. - [Run timeline](https://pixilui.com/components/run-timeline/markdown): The steps of one agent run as a vertical timeline: a connector that fills as steps finish, a live timer on the active step, and a waiting step that holds an approval. - [Tool call row](https://pixilui.com/components/tool-call-row/markdown): One line per tool call: what it did in plain words, the tool's name, a live timer, and a fold-out with the input and output as copyable JSON. ToolCallRowGroup sums several calls into one line. # Tool call row One line per tool call: what it did in plain words, the tool's name, a live timer, and a fold-out with the input and output as copyable JSON. ToolCallRowGroup sums several calls into one line. Tier: free. Type: pattern. Category: ai. Tags: agent, trace, run, keyboard, motion. ## Install ```bash npx shadcn@latest add @pixilui/tool-call-row ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/tool-call-row.tsx`. npm: `motion`. ## Preview Live preview: https://pixilui.com/components/tool-call-row Knobs: - `state`: `play`, `running`, `error`, `done` - `layout`: `group`, `rows` Signature: Calls land one by one under a single summary line that counts them, each with a sliding bar while it runs and rolling digits on its timer. ## Code `components/pixilui/tool-call-row.tsx` ```tsx "use client"; import { Children, forwardRef, isValidElement, useCallback, useEffect, useId, useRef, useState, useSyncExternalStore, type ComponentPropsWithoutRef, type KeyboardEvent, type ReactElement, type ReactNode, } from "react"; import { AnimatePresence, motion, useReducedMotion } from "motion/react"; import { cn } from "./lib/utils"; import { useMorphSize } from "./lib/use-morph-size"; import { motionTokens, reducedTransition } from "./motion-tokens"; import { Button } from "./button"; const noSubscription = () => () => {}; /** * useReducedMotion, held at false until hydration finishes. The server cannot know the * preference, so reading it on the first client render would change the markup and break * hydration; the reduced branch takes over on the next render instead. */ function useReducedMotionAfterHydration() { const hydrated = useSyncExternalStore(noSubscription, () => true, () => false); const reduced = useReducedMotion(); return hydrated && (reduced ?? false); } export type ToolCallRowStatus = "running" | "done" | "error"; /** A JSON value: what tools take and return. Strings render as text, everything else as formatted JSON. */ export type ToolCallRowValue = string | number | boolean | null | ToolCallRowValue[] | { [key: string]: ToolCallRowValue }; export type ToolCallRowLabels = { input: string; output: string; copy: string; copied: string; retry: string; retrying: string; failed: string; running: string; }; const defaultLabels: ToolCallRowLabels = { input: "Input", output: "Output", copy: "Copy", copied: "Copied", retry: "Retry", retrying: "Retrying", failed: "Failed", running: "Running", }; export type ToolCallRowProps = Omit, "children"> & { /** The tool, as its code name: "zendesk.search_tickets". Set in mono. */ name: string; /** What the call did, in plain words and past tense once done: "Searched 14 tickets". */ summary?: ReactNode; /** Running shows a thin indeterminate bar; error shows the message and Retry. */ status: ToolCallRowStatus; /** The tool's mark, shown in a small tile. */ icon?: ReactNode; /** How long the call took (ms). Shown once it finishes. */ durationMs?: number; /** When the call started (epoch ms). Drives a live timer while running. */ startedAt?: number; /** What the agent sent. Objects are formatted as JSON. */ input?: ToolCallRowValue; /** What the tool returned. Objects are formatted as JSON. */ output?: ToolCallRowValue; /** Why it failed, in a sentence. Shown under the summary on error. */ error?: ReactNode; /** Controlled: whether the input and output are unfolded. */ expanded?: boolean; /** Starting fold when uncontrolled. */ defaultExpanded?: boolean; /** Called when the person folds or unfolds the row. */ onExpandedChange?: (expanded: boolean) => void; /** Shows Retry on error. Return a promise and the button shows its own pending state. */ onRetry?: () => void | Promise; /** Copy overrides, for translation. */ labels?: Partial; }; /** One pass of the indeterminate bar: 1.44s, linear. */ const SWEEP = motionTokens.duration.considered * 3; const TICK_MS = 250; const COPIED_MS = 1600; /** "820ms", "1.4s", "1m 04s". */ function formatDuration(ms: number) { if (ms < 1000) return `${Math.round(ms)}ms`; if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`; const s = Math.round(ms / 1000); return `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`; } function formatLive(ms: number) { const s = Math.floor(ms / 1000); return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`; } function useElapsed(startedAt: number | undefined, running: boolean) { const [now, setNow] = useState(null); useEffect(() => { if (startedAt === undefined || !running) return; const tick = () => setNow(Date.now()); tick(); const id = setInterval(tick, TICK_MS); return () => clearInterval(id); }, [startedAt, running]); return startedAt === undefined || now === null ? null : Math.max(0, now - startedAt); } /** Digits keyed by place that roll up as the time grows. */ function Ticker({ value, reduced }: { value: string; reduced: boolean }) { const chars = value.split(""); return ( {chars.map((char, index) => { const place = chars.length - index; if (reduced || !/\d/.test(char)) { return ( ); } return ( ); })} ); } /** A thin bar with a segment sliding across on linear easing. Still under reduced motion. */ function IndeterminateBar({ reduced, className }: { reduced: boolean; className?: string }) { return ( ); } function Chevron({ open }: { open: boolean }) { return ( ); } const JSON_TOKEN = /("(?:\\.|[^"\\])*")(\s*:)?|\b(?:true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g; /** Formatted JSON with keys a step quieter than values. Plain strings stay as written. */ function Payload({ value }: { value: ToolCallRowValue }) { if (typeof value === "string") return <>{value}; const text = JSON.stringify(value, null, 2); const parts: ReactNode[] = []; let last = 0; for (const match of text.matchAll(JSON_TOKEN)) { const index = match.index!; if (index > last) parts.push(text.slice(last, index)); if (match[2] !== undefined) { parts.push( {match[1]} , match[2], ); } else { parts.push( {match[0]} , ); } last = index + match[0].length; } parts.push(text.slice(last)); return <>{parts}; } function payloadText(value: ToolCallRowValue) { return typeof value === "string" ? value : JSON.stringify(value, null, 2); } function PayloadBlock({ label, value, labels, reduced }: { label: string; value: ToolCallRowValue; labels: ToolCallRowLabels; reduced: boolean }) { const [copied, setCopied] = useState(false); const timer = useRef | null>(null); useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []); const copy = async () => { try { await navigator.clipboard.writeText(payloadText(value)); setCopied(true); if (timer.current) clearTimeout(timer.current); timer.current = setTimeout(() => setCopied(false), COPIED_MS); } catch { // Clipboard blocked (insecure context, denied permission): nothing to undo. } }; const swap = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: reducedTransition } : { initial: { opacity: 0, filter: `blur(${motionTokens.blur.subtle}px)` }, animate: { opacity: 1, filter: "blur(0px)" }, exit: { opacity: 0, filter: `blur(${motionTokens.blur.subtle}px)` }, transition: { duration: motionTokens.duration.quick, ease: motionTokens.ease.swap }, }; return (

{label}

); } export const ToolCallRow = forwardRef(function ToolCallRow( { name, summary, status, icon, durationMs, startedAt, input, output, error, expanded: expandedProp, defaultExpanded = false, onExpandedChange, onRetry, labels: labelsProp, className, ...rest }, forwardedRef, ) { const labels = { ...defaultLabels, ...labelsProp }; const reduced = useReducedMotionAfterHydration(); const foldId = useId(); const [innerExpanded, setInnerExpanded] = useState(defaultExpanded); const [retrying, setRetrying] = useState(false); const expandable = input !== undefined || output !== undefined; const open = (expandedProp ?? innerExpanded) && expandable; const live = useElapsed(startedAt, status === "running"); const { containerRef, measureRef } = useMorphSize("height", `${open}:${status}`); const setRef = useCallback( (node: HTMLDivElement | null) => { containerRef.current = node; if (typeof forwardedRef === "function") forwardedRef(node); else if (forwardedRef) forwardedRef.current = node; }, [forwardedRef, containerRef], ); const toggle = () => { const next = !open; if (expandedProp === undefined) setInnerExpanded(next); onExpandedChange?.(next); }; const retry = async () => { if (!onRetry || retrying) return; setRetrying(true); try { await onRetry(); } finally { setRetrying(false); } }; const time = status === "running" ? ( live !== null ? ( ) : null ) : status === "done" && durationMs !== undefined ? ( {formatDuration(durationMs)} ) : null; const headerContent = ( <> {icon} {summary ?? name} {summary ? {name} : null} {status === "error" && error ? {error} : null} {status === "error" ? {labels.failed} : null} {status === "running" ? {labels.running} : null} {time} {expandable ? : null} ); const headerClass = "relative flex min-w-0 flex-1 items-center gap-3 rounded-control px-2 py-1.5 text-left"; return (

{expandable ? ( ) : (

{headerContent}

)} {status === "error" && onRetry ? ( ) : null} {status === "running" ? : null}

{open ? ( {input !== undefined ? : null} {output !== undefined ? : null} ) : null}

); }); export type ToolCallRowGroupCounts = { total: number; running: number; done: number; error: number; /** Sum of the finished calls' durations (ms). */ durationMs: number; }; export type ToolCallRowGroupProps = Omit, "children"> & { /** ToolCallRow elements. The group reads their status, duration and icon to write its summary. */ children: ReactNode; /** The summary line. A function receives the counts; the default reads "Used 4 tools" or "2 of 4 tools done". */ summary?: ReactNode | ((counts: ToolCallRowGroupCounts) => ReactNode); /** Controlled: whether the rows are unfolded. */ expanded?: boolean; /** Starting fold when uncontrolled. */ defaultExpanded?: boolean; /** Called when the person folds or unfolds the group. */ onExpandedChange?: (expanded: boolean) => void; }; const defaultSummary = (c: ToolCallRowGroupCounts) => { const noun = c.total === 1 ? "tool" : "tools"; if (c.running > 0) return `${c.done + c.error} of ${c.total} ${noun} done`; if (c.error > 0) return `Used ${c.total} ${noun}, ${c.error} failed`; return `Used ${c.total} ${noun}`; }; export const ToolCallRowGroup = forwardRef(function ToolCallRowGroup( { children, summary = defaultSummary, expanded: expandedProp, defaultExpanded = false, onExpandedChange, className, ...rest }, forwardedRef, ) { const reduced = useReducedMotionAfterHydration(); const listId = useId(); const [innerExpanded, setInnerExpanded] = useState(defaultExpanded); const open = expandedProp ?? innerExpanded; const rows = Children.toArray(children).filter(isValidElement) as ReactElement>[]; const counts: ToolCallRowGroupCounts = { total: rows.length, running: 0, done: 0, error: 0, durationMs: 0 }; for (const row of rows) { const s = row.props.status; if (s === "running") counts.running++; else if (s === "error") counts.error++; else if (s === "done") counts.done++; if (s !== "running" && typeof row.props.durationMs === "number") counts.durationMs += row.props.durationMs; } const icons = rows.map((row) => row.props.icon).filter(Boolean).slice(0, 3); const status: ToolCallRowStatus = counts.running > 0 ? "running" : counts.error > 0 ? "error" : "done"; const line = typeof summary === "function" ? summary(counts) : summary; const { containerRef, measureRef } = useMorphSize("height", `${open}:${rows.length}`); const setRef = useCallback( (node: HTMLDivElement | null) => { containerRef.current = node; if (typeof forwardedRef === "function") forwardedRef(node); else if (forwardedRef) forwardedRef.current = node; }, [forwardedRef, containerRef], ); const toggle = () => { if (expandedProp === undefined) setInnerExpanded(!open); onExpandedChange?.(!open); }; // Up and Down walk the row triggers, Home and End jump to the ends. const handleListKeys = (event: KeyboardEvent) => { if (!["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) return; const triggers = Array.from(event.currentTarget.querySelectorAll('[data-slot="tool-call-row-trigger"]')); const current = triggers.indexOf(event.target as HTMLElement); if (current === -1) return; event.preventDefault(); const next = event.key === "Home" ? 0 : event.key === "End" ? triggers.length - 1 : Math.min(triggers.length - 1, Math.max(0, current + (event.key === "ArrowDown" ? 1 : -1))); triggers[next]?.focus(); }; const enter = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: reducedTransition } : { initial: { opacity: 0, y: motionTokens.distance.small, filter: `blur(${motionTokens.blur.subtle}px)` }, animate: { opacity: 1, y: 0, filter: "blur(0px)" }, transition: { duration: motionTokens.duration.fast, ease: motionTokens.ease.enter }, }; return (

0} className={cn("relative w-full min-w-0 overflow-hidden rounded-panel bg-surface font-body text-14 text-foreground shadow-resting hairline", className)} {...rest} >

{open ? ( {rows.map((row, index) => ( {row} ))} ) : null}

); }); ``` ## Usage When to use: - Showing the tools an agent called inside a chat message or a run, with evidence a person can open. - Debug and audit views where people copy a call's arguments or result. When not to use: - The steps of a whole run with approvals: use run-timeline (it can hold tool rows as children). - A long log of hundreds of calls: use a virtualised table. - Status while a model is thinking with no tools involved: use thinking-state. ```tsx import { useEffect, useState, useSyncExternalStore, type ReactNode } from "react"; import { motion, useReducedMotion } from "motion/react"; import { CreditCard, Database, RotateCcw, SquareKanban, Ticket } from "lucide-react"; import { motionTokens } from "@/components/pixilui/motion-tokens"; import { Button } from "@/components/pixilui/button"; import { ToolCallRow, ToolCallRowGroup, type ToolCallRowStatus, type ToolCallRowValue } from "@/components/pixilui/tool-call-row"; const noSubscription = () => () => {}; /** * useReducedMotion, held at false until hydration finishes. The server cannot know the * preference, so reading it on the first client render would change the markup and break * hydration; the reduced branch takes over on the next render instead. */ function useReducedMotionAfterHydration() { const hydrated = useSyncExternalStore(noSubscription, () => true, () => false); const reduced = useReducedMotion(); return hydrated && (reduced ?? false); } // The first option of each knob is the demo's default; the docs preview starts there. export const knobs = { state: ["play", "running", "error", "done"], layout: ["group", "rows"], } as const; type Call = { id: string; name: string; icon: ReactNode; running: string; done: string; durationMs: number; input: ToolCallRowValue; output: ToolCallRowValue; }; const CALLS: Call[] = [ { id: "zendesk", name: "zendesk.search_tickets", icon: , running: "Searching tickets about refund delays", done: "Searched 14 tickets about refund delays", durationMs: 1240, input: { query: "refund status:open created>72hours", limit: 25 }, output: { count: 14, tickets: [ { id: "ZD-88412", subject: "Refund still pending after 5 days", requester: "maya.okafor@lumenhaus.com" }, { id: "ZD-88397", subject: "Where is my money back?", requester: "j.lindqvist@fjordlight.se" }, { id: "ZD-88351", subject: "Charged twice, refund promised", requester: "dev@parcelpine.io" }, ], }, }, { id: "stripe", name: "stripe.refunds.list", icon: , running: "Checking refunds in Stripe", done: "Found 9 refunds stuck in pending", durationMs: 830, input: { status: "pending", created: { lt: "2026-10-22T00:00:00Z" }, limit: 100 }, output: { data: [ { id: "re_3QxT2bL8kZ", amount: 4900, currency: "usd", status: "pending" }, { id: "re_3QxR9mC1aP", amount: 12900, currency: "usd", status: "pending" }, ], has_more: false, total_count: 9, }, }, { id: "postgres", name: "postgres.query", icon: , running: "Matching refunds to accounts", done: "Matched 9 refunds to 7 accounts", durationMs: 2310, input: "select a.id, a.name, r.refund_id\nfrom refunds r\njoin accounts a on a.id = r.account_id\nwhere r.refund_id = any($1);", output: { rows: 9, accounts: 7, duplicates_merged: 2 }, }, { id: "linear", name: "linear.create_issue", icon: , running: "Opening an issue for the payout webhook", done: "Opened ENG-4127 for the payout webhook", durationMs: 960, input: { team: "ENG", title: "Payout webhook drops refund.updated events", priority: 2 }, output: { id: "ENG-4127", url: "https://linear.app/northwind/issue/ENG-4127" }, }, ]; type CallState = { status: ToolCallRowStatus; startedAt?: number }; type Frame = { calls: Record; open: string[]; groupOpen: boolean }; const ERROR_TEXT = "Query timed out after 30s on replica db-read-2"; const done = (ids: string[]): Record => Object.fromEntries(ids.map((id) => [id, { status: "done" as const }])); const FINAL: Frame = { calls: done(CALLS.map((c) => c.id)), open: ["postgres"], groupOpen: true }; const EMPTY: Frame = { calls: {}, open: [], groupOpen: true }; export default function ToolCallRowDemo({ state = "play", layout = "group" }: KnobValues) { const reduced = useReducedMotionAfterHydration(); const [run, setRun] = useState(0); const [frame, setFrame] = useState(EMPTY); const [finished, setFinished] = useState(false); const playing = state === "play" && !reduced; // A knob change resets the frame to that state. const combo = `${state}-${layout}-${reduced}`; const [seen, setSeen] = useState(null); if (seen !== combo) { setSeen(combo); setFinished(false); setFrame( playing ? EMPTY : state === "play" || state === "done" ? { ...FINAL, groupOpen: state === "play" } : state === "running" ? { calls: { ...done(["zendesk", "stripe"]), postgres: { status: "running" } }, open: [], groupOpen: true } : { calls: { ...done(["zendesk", "stripe"]), postgres: { status: "error" } }, open: [], groupOpen: true }, ); } useEffect(() => { if (!playing) return; const set = (id: string, call: CallState) => setFrame((f) => ({ ...f, calls: { ...f.calls, [id]: call } })); const start = (id: string) => () => set(id, { status: "running", startedAt: Date.now() }); const finish = (id: string) => () => set(id, { status: "done" }); const steps: [number, () => void][] = [ [300, start("zendesk")], [1300, finish("zendesk")], [1480, start("stripe")], [2280, finish("stripe")], [2460, start("postgres")], [3300, () => set("postgres", { status: "error" })], [4300, start("postgres")], [5100, finish("postgres")], [5280, start("linear")], [6100, finish("linear")], [6800, () => setFrame((f) => ({ ...f, open: ["postgres"] }))], [7400, () => setFinished(true)], ]; const timers = steps.map(([at, fn]) => setTimeout(fn, at)); return () => timers.forEach(clearTimeout); }, [playing, run]); // The running state keeps a live timer. useEffect(() => { if (state !== "running" || reduced) return; const id = setTimeout(() => setFrame((f) => ({ ...f, calls: { ...f.calls, postgres: { status: "running", startedAt: Date.now() - 1400 } } })), 0); return () => clearTimeout(id); }, [state, reduced, run]); const retry = async () => { setFrame((f) => ({ ...f, calls: { ...f.calls, postgres: { status: "running", startedAt: Date.now() } } })); await new Promise((resolve) => setTimeout(resolve, 1100)); setFrame((f) => ({ ...f, calls: { ...f.calls, postgres: { status: "done" } } })); }; const rows = CALLS.filter((call) => frame.calls[call.id]).map((call) => { const { status, startedAt } = frame.calls[call.id]!; return ( setFrame((f) => ({ ...f, open: open ? [...f.open, call.id] : f.open.filter((id) => id !== call.id) }))} onRetry={state === "error" ? retry : undefined} /> ); }); return (

{rows.length === 0 ? null : layout === "group" ? ( setFrame((f) => ({ ...f, groupOpen: open }))}> {rows} ) : (

{rows}

)}

{playing && finished ? ( ) : null}

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | The tool, as its code name: "zendesk.search_tickets". Set in mono. | | `summary` | `ReactNode` | | What the call did, in plain words and past tense once done: "Searched 14 tickets". | | `status` (required) | `"running" \| "done" \| "error"` | | Running shows a thin indeterminate bar; error shows the message and Retry. | | `icon` | `ReactNode` | | The tool's mark, shown in a small tile. | | `durationMs` | `number` | | How long the call took (ms). Shown once it finishes. | | `startedAt` | `number` | | When the call started (epoch ms). Drives a live timer while running. | | `input` | `ToolCallRowValue` | | What the agent sent. Objects are formatted as JSON. | | `output` | `ToolCallRowValue` | | What the tool returned. Objects are formatted as JSON. | | `error` | `ReactNode` | | Why it failed, in a sentence. Shown under the summary on error. | | `expanded` | `boolean` | | Controlled: whether the input and output are unfolded. | | `defaultExpanded` | `boolean` | `false` | Starting fold when uncontrolled. | | `onExpandedChange` | `(expanded: boolean) => void` | | Called when the person folds or unfolds the row. | | `onRetry` | `() => void \| Promise` | | Shows Retry on error. Return a promise and the button shows its own pending state. | | `labels` | `Partial` | | Copy overrides, for translation. | Also accepts every native `

` attribute, and a ref to it. ## Keyboard - `Tab`: Moves to a row's trigger, then its copy buttons and output blocks when open, then Retry on a failed call. - `Enter`: Folds or unfolds the row, or the group from its summary line. - `Space`: Folds or unfolds the row, or the group from its summary line. - `ArrowDown` + `ArrowUp`: Inside a group, moves between row triggers. - `Home` + `End`: Inside a group, jumps to the first or last row. ## Accessibility - Each row trigger is a button with aria-expanded and aria-controls; rows with nothing to show are plain text. - Running rows set aria-busy and carry the word Running in text; failed rows show Failed in text, not only in colour. - The input and output blocks are focusable and labelled, so keyboard users can scroll them; copy buttons say what they copy. - Retry uses aria-busy while the retry runs, never disabled, so focus stays on it. - The group's rows are a labelled group named by the summary line. ## Motion - Running shows a thin bar under the row with a segment sliding across on linear easing, not a spinner. Reduced motion keeps the track still. - The live timer's digits are keyed by place and roll up on the snappy spring. - Unfolding grows the row on the morph spring and folding shrinks it on the smooth spring; the payload fades up out of a 2px blur. - Rows added to an open group rise in from 6px out of a 2px blur while the group grows to fit. - Copy swaps to a check and Copied with a 150ms blur crossfade. - Reduced motion: instant folds, short fades, no sliding bar. ## Responsive - Fills its container. The summary truncates first; the tool name hides under 640px so the summary and timing keep their room. - Input and output blocks wrap long lines and scroll past 192px tall. ## Performance - One ResizeObserver per row and per group drives the folds; nothing animates on first render. - Payloads are formatted only while a row is open. ## Notes for AI - Write summary in past tense with a number once done ("Searched 14 tickets") and in the present while running ("Searching tickets"). - Pass input and output as plain JSON values or strings (SQL, shell commands); objects are pretty-printed with keys a step quieter. - Pass startedAt while running for a live timer and durationMs once done. - Wrap rows in ToolCallRowGroup to sum them; it reads each row's status, duration and icon, so keep the rows as direct children with stable keys. - Return a promise from onRetry and the button shows its own pending state; update status to running from your store when the retry starts. - Pass the tool's logo as icon; the component never imports an icon library. ## Related - [Run timeline](https://pixilui.com/components/run-timeline/markdown): The steps of one agent run as a vertical timeline: a connector that fills as steps finish, a live timer on the active step, and a waiting step that holds an approval. - [Thinking state](https://pixilui.com/components/thinking-state/markdown): A quiet line that says what the agent is doing while it works, with a live timer, steps that unfold, and a fold into "Thought for 12s" when it is done. - [Approval card](https://pixilui.com/components/approval-card/markdown): An agent asks before it acts: what it will do, the rows that matter, the risk, and approve or reject with a note. - [Streaming text](https://pixilui.com/components/streaming-text/markdown): Renders a model's answer as it streams: only new words rise into place at reading speed, a caret holds the end, and half-arrived words wait until they are whole. # Tooltip A short text label for an icon button, with its keyboard shortcut, that waits 400ms and then opens neighbours instantly while you scan a toolbar. Tier: free. Type: component. Category: overlays. Tags: keyboard, motion. ## Install ```bash npx shadcn@latest add @pixilui/tooltip ``` One-time setup: add the registry to `components.json`: ```json { "registries": { "@pixilui": "https://pixilui.com/r/{name}.json" } } ``` Files: `components/pixilui/tooltip.tsx`. npm: `@base-ui/react`, `motion`. ## Preview Live preview: https://pixilui.com/components/tooltip Knobs: - `side`: `top`, `bottom` - `state`: `open`, `closed` Signature: Run the pointer along a toolbar: the first label waits 400ms, then every neighbour appears instantly, like one label sliding along. ## Code `components/pixilui/tooltip.tsx` ```tsx "use client"; import { cloneElement, createContext, forwardRef, useCallback, useContext, useId, useState, useSyncExternalStore, type ComponentPropsWithoutRef, type ReactElement, type ReactNode, } from "react"; import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip"; import { AnimatePresence, motion, useReducedMotion, type HTMLMotionProps } from "motion/react"; import { cn } from "./lib/utils"; import { instantTransition, motionTokens, reducedTransition } from "./motion-tokens"; export type TooltipSide = "top" | "bottom" | "left" | "right"; export type TooltipAlign = "start" | "center" | "end"; export type TooltipProps = Omit, "children"> & { /** The element the tooltip describes, usually an icon Button. Give it its own aria-label; the tooltip is a visual label. */ children: ReactElement<{ "aria-describedby"?: string; "aria-label"?: string }>; /** The text. Plain text by design: a tooltip never holds links or buttons. */ label: string; /** A keyboard shortcut shown after the label in mono, such as "⌘K". */ shortcut?: string; /** Preferred side of the trigger. It flips when there is no room. */ side?: TooltipSide; /** Alignment along that side. */ align?: TooltipAlign; /** Gap between the trigger and the tooltip, in px. */ offset?: number; /** Controlled open state, for tours and tests. Pair with onOpenChange. */ open?: boolean; /** Starting open state when uncontrolled. */ defaultOpen?: boolean; /** Runs whenever the tooltip opens or closes. */ onOpenChange?: (open: boolean) => void; /** Where the tooltip portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. */ container?: HTMLElement | null; }; /** Hover this long before a tooltip opens. */ const OPEN_DELAY = 400; /** A neighbour opened within this long of the last close opens at once. */ const GROUP_TIMEOUT = 300; const TooltipGroupContext = createContext(false); export type TooltipProviderProps = { /** The tooltips that share the instant re-open, such as one toolbar. */ children?: ReactNode; }; /** * Groups tooltips: after one closes, moving to a neighbour within 300ms opens it at once * instead of waiting 400ms again. A lone Tooltip groups itself. */ export function TooltipProvider({ children }: TooltipProviderProps) { return ( {children} ); } const coarseQuery = "(pointer: coarse)"; const subscribeCoarse = (onChange: () => void) => { const list = window.matchMedia(coarseQuery); list.addEventListener("change", onChange); return () => list.removeEventListener("change", onChange); }; const readCoarse = () => window.matchMedia(coarseQuery).matches; const readCoarseOnServer = () => false; export const Tooltip = forwardRef(function Tooltip( { children, label, shortcut, side = "top", align = "center", offset = 6, open: openProp, defaultOpen = false, onOpenChange, container, className, ...rest }, forwardedRef, ) { const reduced = useReducedMotion() ?? false; const coarse = useSyncExternalStore(subscribeCoarse, readCoarse, readCoarseOnServer); const grouped = useContext(TooltipGroupContext); const [innerOpen, setInnerOpen] = useState(defaultOpen); const open = (openProp ?? innerOpen) && !coarse; const descriptionId = useId(); const setOpen = useCallback( (next: boolean) => { setInnerOpen(next); onOpenChange?.(next); }, [onOpenChange], ); // Base UI leaves tooltips out of the accessibility tree, so the text is also wired to the // trigger as a description, unless it would only repeat the trigger's own name. const text = shortcut ? `${label} (${shortcut})` : label; const ownName = children.props["aria-label"]; const describe = ownName !== label && ownName !== text; const describedBy = describe ? [children.props["aria-describedby"], descriptionId].filter(Boolean).join(" ") : children.props["aria-describedby"]; const description = describe ? ( ) : null; // Touch screens never hover, so render the trigger alone. The description stays for screen readers. if (coarse) { return ( <> {cloneElement(children, { "aria-describedby": describedBy })} {description} ); } const enter = reduced ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } } : { initial: { opacity: 0, scale: motionTokens.scale.enterFrom }, animate: { opacity: 1, scale: 1 }, exit: { opacity: 0, transition: { duration: motionTokens.duration.instant, ease: motionTokens.ease.exit } }, }; const tooltip = ( setOpen(next)}> {open ? ( ( )} {...enter} // A grouped re-open is instant, like the first tooltip never closed. transition={ state.instant ? instantTransition : reduced ? reducedTransition : { duration: motionTokens.duration.quick, ease: motionTokens.ease.enter } } /> )} {...rest} > {label} {shortcut ? ( {shortcut} ) : null} ) : null} ); return ( <> {grouped ? tooltip : {tooltip}} {description} ); }); ``` ## Usage When to use: - Naming icon buttons in a composer, a toolbar or a table row: Attach files, Dictate, Retry run. - Teaching the keyboard shortcut for an action people repeat. When not to use: - Anything a person must read to proceed: write it on the page, because touch screens never show tooltips. - Rich content, links or buttons: use a popover. - Validation or status: use the field's error or a toast. ```tsx import { useState } from "react"; import { ArrowUp, AtSign, Mic, Paperclip } from "lucide-react"; import { Button } from "@/components/pixilui/button"; import { Tooltip, TooltipProvider } from "@/components/pixilui/tooltip"; // The first option of each knob is the demo's default; the docs preview starts there. export const knobs = { side: ["top", "bottom"], state: ["open", "closed"], } as const; const tools = [ { label: "Attach files", shortcut: "⌘U", icon: }, { label: "Mention a teammate", shortcut: "@", icon: }, { label: "Dictate", icon: }, ]; export default function TooltipDemo({ side = "top", state = "open" }: KnobValues) { // Tooltips portal into this stage, so they keep the preview's theme and accent. const [stage, setStage] = useState(null); return (

Ask the support agent about ticket 2291

{tools.map((tool, index) => (

); } ``` ## Examples None. ## API | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` (required) | `ReactElement<{ "aria-describedby"?: string; "aria-label"?: string }>` | | The element the tooltip describes, usually an icon Button. Give it its own aria-label; the tooltip is a visual label. | | `label` (required) | `string` | | The text. Plain text by design: a tooltip never holds links or buttons. | | `shortcut` | `string` | | A keyboard shortcut shown after the label in mono, such as "⌘K". | | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Preferred side of the trigger. It flips when there is no room. | | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along that side. | | `offset` | `number` | `6` | Gap between the trigger and the tooltip, in px. | | `open` | `boolean` | | Controlled open state, for tours and tests. Pair with onOpenChange. | | `defaultOpen` | `boolean` | `false` | Starting open state when uncontrolled. | | `onOpenChange` | `(open: boolean) => void` | | Runs whenever the tooltip opens or closes. | | `container` | `HTMLElement \| null` | | Where the tooltip portals to. Defaults to document.body. Pass an element (from a callback ref kept in state) to keep it inside a region; null waits for it. | Also accepts every native `

` attribute, and a ref to it. ## Keyboard - `Tab`: Focusing the trigger with the keyboard opens its tooltip; moving on closes it. - `Esc`: Closes the tooltip and leaves focus on the trigger. ## Accessibility - The tooltip is a visual label; the trigger keeps its own aria-label, which should match the tooltip text. - Base UI leaves tooltips out of the accessibility tree, so the component wires the text (and shortcut) to the trigger with aria-describedby, and skips it when it would only repeat the trigger's name. - On coarse pointers it renders nothing: touch has no hover, so the label must never be the only place information lives. - Text only by design, so nothing focusable is ever trapped inside it. ## Motion - Opens after 400ms of hover, scaling from 0.96 out of the trigger in 150ms on the enter ease, with transform-origin following its side. - Within 300ms of one tooltip closing, the next opens at once with no animation, so scanning a toolbar feels like one label moving. - Closes in 120ms. Reduced motion: fade only. ## Responsive - Wraps past 256px; keep labels to a few words. - Flips to the other side when there is no room. - Absent on touch screens by design. ## Performance - Nothing is mounted until a tooltip opens; one Base UI provider per group shares the timers. ## Notes for AI - Wrap the trigger: