motion-ui-skill 2.0.0

package/references/agents/message-scroller.md

@@ -0,0 +1,128 @@
+---
+title: "Message Scroller"
+description: "A reader-aware conversation viewport that follows streamed output at the live edge and releases control when the reader moves away."
+category: "AI Agents"
+publishedAt: "2026-08-02"
+updatedAt: "2026-08-02"
+documentation: "references/agents/message-scroller.md"
+markdown: "references/agents/message-scroller.md"
+license: "MIT"
+---
+
+# Message Scroller
+
+> A reader-aware conversation viewport that follows streamed output at the live edge and releases control when the reader moves away.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py message-scroller --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import {
+  ChatPreview,
+  type ChatPreviewMessage,
+} from "@/components/previews/agents/chat-preview";
+
+const MESSAGES: ChatPreviewMessage[] = [
+  {
+    id: "scope-question",
+    from: "user",
+    content: "What should the first release include?",
+  },
+  {
+    id: "scope-answer",
+    from: "assistant",
+    content: "Start with the smallest workflow that still feels complete.",
+  },
+  {
+    id: "states-question",
+    from: "user",
+    content: "Include streaming and recovery states too.",
+  },
+  {
+    id: "states-answer",
+    from: "assistant",
+    content: "Yes. Those states make the first version feel dependable.",
+  },
+  {
+    id: "evidence-question",
+    from: "user",
+    content: "How should we present tool results?",
+  },
+  {
+    id: "evidence-answer",
+    from: "assistant",
+    content: "Keep results close to the action that produced them.",
+  },
+  {
+    id: "approval-question",
+    from: "user",
+    content: "What about actions that need confirmation?",
+  },
+  {
+    id: "approval-answer",
+    from: "assistant",
+    content: "Pause the run, explain the impact, and ask before continuing.",
+  },
+  {
+    id: "summary-question",
+    from: "user",
+    content: "Can the transcript stay easy to navigate?",
+  },
+  {
+    id: "summary-answer",
+    from: "assistant",
+    content: "Use the rail to jump between turns without losing your place.",
+  },
+];
+
+export function MessageScrollerPreview() {
+  return (
+    <ChatPreview
+      initialMessages={MESSAGES}
+      showRail
+      reply="The viewport follows while you stay at the live edge. Scroll upward while this response streams and it will leave your reading position alone."
+      placeholder="Send another message…"
+    />
+  );
+}
+```
+
+## API Reference
+
+### MessageScroller
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `followOutput` | `boolean` | `true` | No | Keep streamed output pinned while the reader remains near the end. |
+| `followThreshold` | `number` | `56` | No | Distance from the end that still counts as following the output. |
+| `smooth` | `boolean` | `true` | No | Smoothly follow growing content. |
+| `onFollowChange` | `((following: boolean) => void)` | — | No | Reports when the reader leaves or returns to the live edge. |
+| `label` | `string` | `Conversation` | No | Accessible label for the scrollable transcript. |
+| `busy` | `boolean` | — | No | Marks the transcript as waiting for more streamed content. |
+| `navigation` | `"rail"` | — | No | Adds a compact rail for navigating between rendered Message rows. |
+| `navigationLabel` | `string` | `Message navigation` | No | Accessible label for the optional message navigation rail. |
+| `viewportClassName` | `string` | — | No | — |
+| `contentClassName` | `string` | — | No | — |
+| `railClassName` | `string` | — | No | — |
+| `viewportRef` | `Ref<HTMLElement>` | — | No | — |
+| `viewportProps` | `Omit<DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>, "ref" \| "className" \| "children">` | — | No | — |
+| `contentProps` | `Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref" \| "className" \| "children">` | — | No | — |
+| `className` | `string` | — | No | — |
+

package/references/agents/message.md

@@ -0,0 +1,162 @@
+---
+title: "Message"
+description: "Composable conversation primitives for message rows, grouped bubbles, avatars, metadata, live markers, and a mount-only trailing-edge pop-up for newly sent rows."
+category: "AI Agents"
+publishedAt: "2026-08-02"
+updatedAt: "2026-08-02"
+documentation: "references/agents/message.md"
+markdown: "references/agents/message.md"
+license: "MIT"
+---
+
+# Message
+
+> Composable conversation primitives for message rows, grouped bubbles, avatars, metadata, live markers, and a mount-only trailing-edge pop-up for newly sent rows.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py message --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ChatPreview } from "@/components/previews/agents/chat-preview";
+
+export function MessagePreview() {
+  return (
+    <ChatPreview
+      showAvatars
+      showMetadata
+      assistantVariant="ghost"
+      placeholder="Ask a follow-up…"
+    />
+  );
+}
+```
+
+## API Reference
+
+### Message
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `from` | `"user" \| "assistant"` | — | Yes | — |
+| `animateIn` | `boolean` | `false` | No | Plays a trailing-edge pop-up once when this message row mounts. |
+| `className` | `string` | — | No | — |
+
+### MessageGroup
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `spacing` | `"default" \| "compact"` | `compact` | No | — |
+| `className` | `string` | — | No | — |
+
+### MessageAvatar
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `placeholder` | `boolean` | `false` | No | Keep an empty avatar slot so grouped messages remain aligned. |
+| `className` | `string` | — | No | — |
+
+### MessageContent
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MessageHeader
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MessageFooter
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MessageMarker
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MessageTyping
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `string` | `Responding` | No | — |
+| `className` | `string` | — | No | — |
+
+### MessageBubble
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `"outline" \| "solid" \| "danger" \| "ghost" \| "soft" \| "tint"` | `soft` | No | — |
+| `align` | `"end" \| "start"` | — | No | Defaults to the surrounding Message alignment when omitted. |
+| `animateIn` | `boolean` | `false` | No | Plays the bubble entrance once when this component mounts. |
+| `className` | `string` | — | No | — |
+
+### MessageBubbleCollapsible
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | No | — |
+| `defaultOpen` | `boolean` | `false` | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `collapsedLines` | `2 \| 3 \| 4 \| 5 \| 6` | `4` | No | — |
+| `moreLabel` | `ReactNode` | `Show more` | No | — |
+| `lessLabel` | `ReactNode` | `Show less` | No | — |
+| `contentClassName` | `string` | — | No | — |
+| `triggerClassName` | `string` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### MessageBubbleContent
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | — | No | Replaces the content element while preserving bubble styling. |
+| `className` | `string` | — | No | — |
+
+### MessageBubbleGroup
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `spacing` | `"default" \| "compact"` | `compact` | No | — |
+| `className` | `string` | — | No | — |
+
+### MessageScroller
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `followOutput` | `boolean` | `true` | No | Keep streamed output pinned while the reader remains near the end. |
+| `followThreshold` | `number` | `56` | No | Distance from the end that still counts as following the output. |
+| `smooth` | `boolean` | `true` | No | Smoothly follow growing content. |
+| `onFollowChange` | `((following: boolean) => void)` | — | No | Reports when the reader leaves or returns to the live edge. |
+| `label` | `string` | `Conversation` | No | Accessible label for the scrollable transcript. |
+| `busy` | `boolean` | — | No | Marks the transcript as waiting for more streamed content. |
+| `navigation` | `"rail"` | — | No | Adds a compact rail for navigating between rendered Message rows. |
+| `navigationLabel` | `string` | `Message navigation` | No | Accessible label for the optional message navigation rail. |
+| `viewportClassName` | `string` | — | No | — |
+| `contentClassName` | `string` | — | No | — |
+| `railClassName` | `string` | — | No | — |
+| `viewportRef` | `Ref<HTMLElement>` | — | No | — |
+| `viewportProps` | `Omit<DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>, "ref" \| "className" \| "children">` | — | No | — |
+| `contentProps` | `Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref" \| "className" \| "children">` | — | No | — |
+| `className` | `string` | — | No | — |
+

package/references/agents/prompt-input.md

@@ -0,0 +1,204 @@
+---
+title: "Prompt Input"
+description: "An auto-growing agent composer with prompt actions, model selection, keyboard submission, and animated send and stop states."
+category: "AI Agents"
+publishedAt: "2026-08-02"
+updatedAt: "2026-08-02"
+documentation: "references/agents/prompt-input.md"
+markdown: "references/agents/prompt-input.md"
+license: "MIT"
+---
+
+# Prompt Input
+
+> An auto-growing agent composer with prompt actions, model selection, keyboard submission, and animated send and stop states.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py prompt-input --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import {
+  Bot,
+  FileText,
+  ImagePlus,
+  Puzzle,
+} from "lucide-react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { useEffect, useRef, useState } from "react";
+import { PromptInput } from "@/components/agents/prompt-input";
+import { EASE_OUT } from "@/lib/ease";
+import { useFavicon } from "@/lib/hooks/use-favicon";
+
+function ModelLogo({ url }: { url: string }) {
+  const favicon = useFavicon(url);
+
+  if (!favicon.src) return <Bot />;
+
+  return (
+    // biome-ignore lint/performance/noImgElement: Remote provider favicons keep the registry preview framework-agnostic.
+    <img
+      ref={favicon.ref}
+      src={favicon.src}
+      alt=""
+      width={16}
+      height={16}
+      referrerPolicy="no-referrer"
+      className="size-4 rounded-sm object-contain"
+    />
+  );
+}
+
+const MODELS = [
+  {
+    value: "gpt-5.2",
+    label: "GPT-5.2",
+    icon: <ModelLogo url="https://openai.com" />,
+  },
+  {
+    value: "claude-sonnet-4",
+    label: "Claude Sonnet 4",
+    icon: <ModelLogo url="https://www.anthropic.com" />,
+  },
+  {
+    value: "gemini-3.6-flash",
+    label: "Gemini 3.6 Flash",
+    // gemini.google.com has no /favicon.ico; Google DeepMind ships Gemini.
+    icon: <ModelLogo url="https://deepmind.google" />,
+  },
+  {
+    value: "grok-4.5",
+    label: "Grok 4.5",
+    icon: <ModelLogo url="https://x.ai" />,
+  },
+  {
+    value: "mistral-large-3",
+    label: "Mistral Large 3",
+    icon: <ModelLogo url="https://mistral.ai" />,
+  },
+];
+
+const ACTIONS = [
+  {
+    value: "image",
+    label: "Attach image",
+    description: "Add a screenshot or visual reference.",
+    icon: <ImagePlus />,
+  },
+  {
+    value: "skill",
+    label: "Use a skill",
+    description: "Give the agent a specialized workflow.",
+    icon: <Puzzle />,
+  },
+  {
+    value: "context",
+    label: "Add context",
+    description: "Include a file with supporting details.",
+    icon: <FileText />,
+  },
+];
+
+export function PromptInputPreview() {
+  const reduce = useReducedMotion() ?? false;
+  const timer = useRef<number | undefined>(undefined);
+  const [loading, setLoading] = useState(false);
+  const [sent, setSent] = useState<string>();
+  const [notice, setNotice] = useState<string>();
+
+  useEffect(
+    () => () => {
+      if (timer.current) window.clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const submit = (prompt: string) => {
+    setSent(undefined);
+    setNotice(undefined);
+    setLoading(true);
+    timer.current = window.setTimeout(() => {
+      setLoading(false);
+      setSent(prompt);
+    }, 900);
+  };
+
+  const stop = () => {
+    if (timer.current) window.clearTimeout(timer.current);
+    setLoading(false);
+  };
+
+  return (
+    <div className="flex h-[360px] w-full max-w-xl flex-col justify-center">
+      <PromptInput
+        models={MODELS}
+        actions={ACTIONS}
+        defaultModel="gpt-5.2"
+        defaultValue="Review the current implementation and suggest the next improvement."
+        loading={loading}
+        onSubmit={submit}
+        onStop={stop}
+        onAction={(action) => {
+          const selected = ACTIONS.find((item) => item.value === action);
+          setNotice(selected ? `${selected.label} selected.` : undefined);
+        }}
+      />
+      <div className="h-8 px-2 pt-2 text-xs text-muted-foreground">
+        <AnimatePresence mode="wait">
+          {sent || notice ? (
+            <motion.p
+              key={sent ?? notice}
+              initial={reduce ? { opacity: 1 } : { opacity: 0, y: 3 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0 }}
+              transition={{ duration: reduce ? 0 : 0.18, ease: EASE_OUT }}
+            >
+              {sent ? "Prompt sent to the selected model." : notice}
+            </motion.p>
+          ) : null}
+        </AnimatePresence>
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### PromptInput
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `onValueChange` | `((value: string) => void)` | — | No | — |
+| `models` | `PromptModel[]` | `[]` | No | — |
+| `model` | `string` | — | No | — |
+| `defaultModel` | `string` | — | No | — |
+| `onModelChange` | `((model: string) => void)` | — | No | — |
+| `actions` | `PromptAction[]` | `[]` | No | — |
+| `onAction` | `((action: string) => void)` | — | No | — |
+| `onSubmit` | `((value: string, model?: string) => void \| Promise<void>)` | — | No | — |
+| `loading` | `boolean` | `false` | No | — |
+| `onStop` | `(() => void)` | — | No | — |
+| `minRows` | `number` | `2` | No | — |
+| `maxRows` | `number` | `8` | No | — |
+| `leadingAction` | `ReactNode` | — | No | — |
+| `className` | `string` | — | No | — |
+

package/references/agents/streaming-response.md

@@ -0,0 +1,216 @@
+---
+title: "Streaming Response"
+description: "A stable response surface with completion actions, rendered content, and an expandable source summary."
+category: "AI Agents"
+publishedAt: "2026-08-01"
+updatedAt: "2026-08-02"
+documentation: "references/agents/streaming-response.md"
+markdown: "references/agents/streaming-response.md"
+license: "MIT"
+---
+
+# Streaming Response
+
+> A stable response surface with completion actions, rendered content, and an expandable source summary.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py streaming-response --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { RotateCcw } from "lucide-react";
+import { useReducedMotion } from "motion/react";
+import { useEffect, useState } from "react";
+import type { CitationItem } from "@/components/agents/citations";
+import { StreamingResponse } from "@/components/agents/streaming-response";
+
+const PIECES = [
+  "A streaming response can link directly to ",
+  "Motion's React guide",
+  " while the rest of the answer continues to arrive.",
+  "The same response can preserve useful structure:",
+  "Links stay interactive as nearby text streams",
+  "Lists keep their spacing and hierarchy",
+  "Code remains readable without shifting the response",
+  "Set ",
+  "aria-busy",
+  " while new content is still arriving.",
+  'const status = complete ? "ready" : "streaming";',
+] as const;
+
+const STARTS = PIECES.map((_, index) =>
+  PIECES.slice(0, index).reduce((total, piece) => total + piece.length, 0),
+);
+const RESPONSE_LENGTH = PIECES.reduce((total, piece) => total + piece.length, 0);
+const RESPONSE_MARKDOWN = `A streaming response can link directly to [Motion's React guide](https://motion.dev/docs/react) while the rest of the answer continues to arrive.
+
+The same response can preserve useful structure:
+
+- Links stay interactive as nearby text streams
+- Lists keep their spacing and hierarchy
+- Code remains readable without shifting the response
+
+Set \`aria-busy\` while new content is still arriving.
+
+\`\`\`tsx
+const status = complete ? "ready" : "streaming";
+\`\`\``;
+
+const CHARACTERS_PER_SECOND = 110;
+
+const RESPONSE_SOURCES: CitationItem[] = [
+  {
+    id: "motion-react",
+    title: "Motion for React",
+    domain: "motion.dev",
+    url: "https://motion.dev/docs/react",
+  },
+  {
+    id: "aria-busy",
+    title: "ARIA live regions",
+    domain: "developer.mozilla.org",
+    url: "https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy",
+  },
+  {
+    id: "react-rendering",
+    title: "Rendering elements",
+    domain: "react.dev",
+    url: "https://react.dev/learn/conditional-rendering",
+  },
+];
+
+function ResponseDemo({ onReplay }: { onReplay: () => void }) {
+  const reduce = useReducedMotion() ?? false;
+  const [cursor, setCursor] = useState(reduce ? RESPONSE_LENGTH : 0);
+  const [complete, setComplete] = useState(reduce);
+
+  const reveal = (index: number) =>
+    PIECES[index].slice(0, Math.max(0, cursor - STARTS[index]));
+  const started = (index: number) => cursor > STARTS[index];
+
+  useEffect(() => {
+    if (reduce) return;
+
+    const startedAt = performance.now();
+    let frame = 0;
+    let completionTimer: number | undefined;
+    const stream = (now: number) => {
+      const cursor = Math.min(
+        RESPONSE_LENGTH,
+        Math.floor(((now - startedAt) / 1000) * CHARACTERS_PER_SECOND),
+      );
+      setCursor(cursor);
+      if (cursor < RESPONSE_LENGTH) frame = requestAnimationFrame(stream);
+      else completionTimer = window.setTimeout(() => setComplete(true), 450);
+    };
+
+    frame = requestAnimationFrame(stream);
+    return () => {
+      cancelAnimationFrame(frame);
+      if (completionTimer) window.clearTimeout(completionTimer);
+    };
+  }, [reduce]);
+
+  return (
+    <StreamingResponse
+      status={complete ? "complete" : "streaming"}
+      copyText={RESPONSE_MARKDOWN}
+      onRetry={onReplay}
+      sources={RESPONSE_SOURCES}
+    >
+      <p>
+        {reveal(0)}
+        {started(1) ? (
+          <a
+            href="https://motion.dev/docs/react"
+            target="_blank"
+            rel="noreferrer noopener"
+          >
+            {reveal(1)}
+          </a>
+        ) : null}
+        {reveal(2)}
+      </p>
+      {started(3) ? <p>{reveal(3)}</p> : null}
+      {started(4) ? (
+        <ul>
+          <li>{reveal(4)}</li>
+          {started(5) ? <li>{reveal(5)}</li> : null}
+          {started(6) ? <li>{reveal(6)}</li> : null}
+        </ul>
+      ) : null}
+      {started(7) ? (
+        <p>
+          {reveal(7)}
+          {started(8) ? <code>{reveal(8)}</code> : null}
+          {reveal(9)}
+        </p>
+      ) : null}
+      {started(10) ? (
+        <pre>
+          <code>{reveal(10)}</code>
+        </pre>
+      ) : null}
+    </StreamingResponse>
+  );
+}
+
+export function StreamingResponsePreview() {
+  const [run, setRun] = useState(0);
+
+  return (
+    <div className="relative h-[500px] w-full max-w-xl">
+      <ResponseDemo key={run} onReplay={() => setRun((value) => value + 1)} />
+      <button
+        type="button"
+        onClick={() => setRun((value) => value + 1)}
+        className="absolute bottom-0 left-0 inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <RotateCcw className="size-3" />
+        Replay
+      </button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### StreamingResponse
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Yes | Rendered response content. Pass plain text or the output of a Markdown renderer. |
+| `status` | `"error" \| "streaming" \| "complete"` | `streaming` | No | — |
+| `copyText` | `string` | — | No | Plain-text value copied by the built-in copy action. |
+| `onCopy` | `(() => void \| Promise<void>)` | — | No | Overrides the built-in clipboard action. |
+| `onRetry` | `(() => void)` | — | No | — |
+| `sources` | `CitationItem[]` | `[]` | No | Optional sources shown as a compact footer disclosure after streaming. |
+| `sourcesOpen` | `boolean` | — | No | — |
+| `defaultSourcesOpen` | `boolean` | `false` | No | — |
+| `onSourcesOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `sourceIdPrefix` | `string` | — | No | — |
+| `feedback` | `StreamingResponseFeedback` | — | No | — |
+| `defaultFeedback` | `StreamingResponseFeedback` | `null` | No | — |
+| `onFeedbackChange` | `((feedback: StreamingResponseFeedback) => void)` | — | No | — |
+| `announce` | `boolean` | `true` | No | Set false when a surrounding conversation log announces streamed text. |
+| `showActions` | `boolean` | `true` | No | Hides the built-in completion actions without changing response status. |
+| `className` | `string` | — | No | — |
+| `contentClassName` | `string` | — | No | — |
+| `actionsClassName` | `string` | — | No | — |
+