@kitnai/chat 0.7.0 → 0.8.1

package/src/components/image.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Image } from './image';
+import { componentDescription } from '../stories/docs/element-controls';
 
 // Compact SVG chat typing icon as base64
 const chatIconBase64 =
@@ -13,14 +14,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'Renders an image from a `base64` string or a `uint8Array`, building a data URL or object URL automatically; shows a pulsing placeholder until a source is available.',
-          '**When to use:** to display model-generated or attached images supplied as raw bytes / base64 (the `GeneratedImageLike` shape) rather than a remote URL.',
-          '**How to use:** pass `base64` + `mediaType` (or `uint8Array` + `mediaType`) and an `alt` description; size and style via `class`.',
-          '**Placement:** inside assistant messages, attachment previews, or anywhere a generated image needs to be shown.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'Renders an image from a `base64` string or a `uint8Array`, building a data URL or object URL automatically; shows a pulsing placeholder until a source is available.',
+        '**When to use:** to display model-generated or attached images supplied as raw bytes / base64 (the `GeneratedImageLike` shape) rather than a remote URL.',
+        '**How to use:** pass `base64` + `mediaType` (or `uint8Array` + `mediaType`) and an `alt` description; size and style via `class`.',
+        '**Placement:** inside assistant messages, attachment previews, or anywhere a generated image needs to be shown.',
+      ]),
     },
   },
   argTypes: {

package/src/components/link-card.tsx

@@ -0,0 +1,194 @@
+import {
+  type JSX,
+  splitProps,
+  createSignal,
+  createEffect,
+  createMemo,
+  on,
+  onMount,
+  onCleanup,
+  Show,
+} from 'solid-js';
+import { cn } from '../utils/cn';
+import { Link as LinkIcon } from 'lucide-solid';
+import type { CardEvent } from '../primitives/card-contract';
+import {
+  type LinkCardData,
+  deriveDomain,
+  isRenderableLink,
+  hasLinkPreviewFetcher,
+  resolveLinkMetadata,
+} from '../primitives/link-preview';
+
+export interface LinkCardProps {
+  /** The card id correlating every emitted event. */
+  cardId: string;
+  /** The link payload (data-down). */
+  data: LinkCardData;
+  /** Emit a contract CardEvent up (host routes it). */
+  onEmit?: (event: CardEvent) => void;
+  /** Extra classes for the card root. */
+  class?: string;
+}
+
+/** True when the payload already carries renderable metadata (the pure path). */
+function hasMetadata(data: LinkCardData): boolean {
+  return Boolean(data.title || data.description || data.image);
+}
+
+/**
+ * `LinkCard` — a pure, themed, accessible rich link / OG preview. Renders from the
+ * supplied metadata; it never fetches the network itself. When the payload is a
+ * bare `{ url }` and an app has registered a `configureLinkPreview` fetcher, it
+ * shows a skeleton, calls the hook, merges the result, and renders. Activating the
+ * card (click / Enter / Space) emits the contract `open` verb (`target:'tab'`); the
+ * host policy performs the navigation so it can veto/redirect.
+ */
+export function LinkCard(props: LinkCardProps): JSX.Element {
+  const [local] = splitProps(props, ['cardId', 'data', 'onEmit', 'class']);
+
+  const emit = (event: CardEvent) => local.onEmit?.(event);
+
+  // Bare-URL resolution state (only used when the payload lacks metadata + a fetcher exists).
+  const [fetched, setFetched] = createSignal<Partial<LinkCardData> | undefined>();
+  const [loading, setLoading] = createSignal(false);
+  const [imageBroken, setImageBroken] = createSignal(false);
+
+  const url = () => local.data.url;
+  const valid = createMemo(() => isRenderableLink(url()));
+
+  // The effective payload = supplied data merged with any fetched metadata.
+  const effective = createMemo<LinkCardData>(() => ({ ...local.data, ...fetched() }));
+
+  // Lifecycle `ready` once on mount.
+  onMount(() => emit({ kind: 'ready', cardId: local.cardId }));
+
+  // Invalid URL → emit a single `error` (belt-and-suspenders; host also rejects bad schemes on open).
+  createEffect(
+    on(valid, (ok) => {
+      if (!ok) emit({ kind: 'error', cardId: local.cardId, message: `Invalid link url: ${url()}` });
+    }),
+  );
+
+  // Bare-URL path: when there's no metadata AND a fetcher is configured, resolve once.
+  createEffect(
+    on(
+      () => [local.data, valid()] as const,
+      ([data, ok]) => {
+        setImageBroken(false);
+        if (!ok || hasMetadata(data) || !hasLinkPreviewFetcher()) return;
+        let cancelled = false;
+        // Cancel a stale in-flight fetch if `data` changes before it resolves.
+        onCleanup(() => {
+          cancelled = true;
+        });
+        setLoading(true);
+        resolveLinkMetadata(data.url)
+          .then((meta) => {
+            if (!cancelled) setFetched(meta);
+          })
+          .catch(() => {
+            // Reject → fall back to the bare link chip; the URL itself is still usable.
+            if (!cancelled) setFetched({});
+          })
+          .finally(() => {
+            if (!cancelled) setLoading(false);
+          });
+      },
+    ),
+  );
+
+  const domain = createMemo(() => effective().domain ?? deriveDomain(url()) ?? url());
+  const heading = createMemo(() => effective().siteName ?? domain());
+  const titleText = createMemo(() => effective().title ?? domain());
+  const showImage = createMemo(() => Boolean(effective().image) && !imageBroken());
+
+  const activate = () => {
+    if (!valid()) return;
+    emit({ kind: 'open', cardId: local.cardId, url: url(), target: 'tab' });
+  };
+
+  const onClick = (e: MouseEvent) => {
+    // Intercept the anchor's default navigation so it routes through host policy.
+    // (Middle-click / cmd-click still open the real href in a new tab — acceptable + safe.)
+    e.preventDefault();
+    activate();
+  };
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      activate();
+    }
+  };
+
+  // --- Invalid-link error chip ------------------------------------------
+  return (
+    <Show
+      when={valid()}
+      fallback={
+        <div
+          role="img"
+          aria-label="Invalid link"
+          class={cn(
+            'flex items-center gap-2 rounded-xl border border-destructive/40 bg-destructive/10 px-3 py-2 text-sm text-destructive dark:border-red-400/50 dark:bg-destructive/20 dark:text-red-400',
+            local.class,
+          )}
+        >
+          <LinkIcon size={16} aria-hidden="true" />
+          <span class="truncate">Invalid link</span>
+        </div>
+      }
+    >
+      <a
+        href={url()}
+        rel="noopener noreferrer"
+        aria-label={`Open ${titleText()} on ${domain()}`}
+        class={cn(
+          'group block overflow-hidden rounded-xl border border-border bg-card text-card-foreground no-underline outline-none transition-shadow',
+          'cursor-pointer hover:shadow-md focus-visible:ring-2 focus-visible:ring-ring',
+          local.class,
+        )}
+        onClick={onClick}
+        onKeyDown={onKeyDown}
+      >
+        <Show when={loading()}>
+          {/* Skeleton while the bare-URL fetcher resolves. */}
+          <div class="aspect-[16/9] w-full animate-pulse bg-muted" />
+          <div class="space-y-2 p-3">
+            <div class="h-3 w-1/3 animate-pulse rounded bg-muted" />
+            <div class="h-4 w-2/3 animate-pulse rounded bg-muted" />
+            <div class="h-3 w-full animate-pulse rounded bg-muted" />
+          </div>
+        </Show>
+        <Show when={!loading()}>
+          <Show when={showImage()}>
+            <img
+              src={effective().image}
+              alt={effective().imageAlt ?? ''}
+              role="img"
+              class="aspect-[16/9] w-full object-cover"
+              onError={() => setImageBroken(true)}
+            />
+          </Show>
+          <div class="space-y-1 p-3">
+            <div class="flex items-center gap-1.5 text-xs text-muted-foreground">
+              <Show
+                when={effective().favicon}
+                fallback={<LinkIcon size={12} class="shrink-0 opacity-70" aria-hidden="true" />}
+              >
+                <img src={effective().favicon} alt="" class="h-3.5 w-3.5 shrink-0 rounded-sm" />
+              </Show>
+              <span class="truncate">{heading()}</span>
+            </div>
+            <div class="line-clamp-2 text-sm font-semibold text-foreground">{titleText()}</div>
+            <Show when={effective().description}>
+              <div class="line-clamp-3 text-xs text-muted-foreground">{effective().description}</div>
+            </Show>
+          </div>
+        </Show>
+      </a>
+    </Show>
+  );
+}
+
+export type { LinkCardData } from '../primitives/link-preview';

package/src/components/loader.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { For } from 'solid-js';
 import { Loader, type LoaderVariant, type LoaderSize } from './loader';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/Loader',
@@ -10,14 +11,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A loading indicator with twelve animated **variants** (spinners, dots, bars, terminal, and text-based) in three **sizes**.',
-          '**When to use:** while waiting on an async operation — a streaming response, a tool call, or any pending state.',
-          '**How to use:** pick a `variant` and `size`. Text variants (`text-blink`, `text-shimmer`, `loading-dots`) display the `text` prop (defaults to "Thinking").',
-          '**Placement:** inside assistant message bubbles, send-button states, empty states, or anywhere an in-progress signal is needed.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A loading indicator with twelve animated **variants** (spinners, dots, bars, terminal, and text-based) in three **sizes**.',
+        '**When to use:** while waiting on an async operation — a streaming response, a tool call, or any pending state.',
+        '**How to use:** pick a `variant` and `size`. Text variants (`text-blink`, `text-shimmer`, `loading-dots`) display the `text` prop (defaults to "Thinking").',
+        '**Placement:** inside assistant message bubbles, send-button states, empty states, or anywhere an in-progress signal is needed.',
+      ]),
     },
   },
   argTypes: {

package/src/components/markdown.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Markdown } from './markdown';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/Markdown',
@@ -9,14 +10,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'Renders a Markdown string to styled HTML (GFM enabled — tables, lists, blockquotes), splitting fenced code into highlighted `CodeBlock`s.',
-          '**When to use:** to display assistant message content, documentation, or any rich text authored in Markdown.',
-          '**How to use:** pass the Markdown string as `content`; optionally set `codeTheme` for code fences and `class` for the prose container. Prose sizing follows the surrounding `ChatConfig`.',
-          '**Placement:** inside `MessageContent`, response panels, or anywhere formatted text is shown.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'Renders a Markdown string to styled HTML (GFM enabled — tables, lists, blockquotes), splitting fenced code into highlighted `CodeBlock`s.',
+        '**When to use:** to display assistant message content, documentation, or any rich text authored in Markdown.',
+        '**How to use:** pass the Markdown string as `content`; optionally set `codeTheme` for code fences and `class` for the prose container. Prose sizing follows the surrounding `ChatConfig`.',
+        '**Placement:** inside `MessageContent`, response panels, or anywhere formatted text is shown.',
+      ]),
     },
   },
   argTypes: {

package/src/components/message-narrow.stories.tsx

@@ -3,6 +3,7 @@ import { Message, MessageAvatar, MessageContent } from './message';
 import { ChatContainer } from './chat-container';
 import { ChatConfig } from '../primitives/chat-config';
 import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../ui/resizable';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/Message/Narrow Panel',
@@ -12,14 +13,12 @@ const meta = {
     layout: 'centered',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'Layout stress-tests for `Message` inside narrow chat panels (300–380px) and resizable side panels, verifying text wraps and the 32px avatar stays fixed.',
-          '**When to use:** as a reference when embedding the chat in a constrained column — a browser-extension side panel, a docked drawer, or a resizable split view.',
-          '**How to use:** wrap messages in a fixed/min-width container (and usually `ChatConfig proseSize="sm"`), keeping `min-w-0` on flex children so long text wraps instead of overflowing.',
-          '**Placement:** these are full-composition showcases, not control-driven; use them to copy the surrounding panel structure.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'Layout stress-tests for `Message` inside narrow chat panels (300–380px) and resizable side panels, verifying text wraps and the 32px avatar stays fixed.',
+        '**When to use:** as a reference when embedding the chat in a constrained column — a browser-extension side panel, a docked drawer, or a resizable split view.',
+        '**How to use:** wrap messages in a fixed/min-width container (and usually `ChatConfig proseSize="sm"`), keeping `min-w-0` on flex children so long text wraps instead of overflowing.',
+        '**Placement:** these are full-composition showcases, not control-driven; use them to copy the surrounding panel structure.',
+      ]),
     },
   },
   argTypes: {
@@ -191,11 +190,11 @@ export const FullExtensionLayout: Story = {
     <ChatConfig proseSize="sm">
       <div class="flex h-screen bg-background relative" style={{ height: '600px' }}>
         <div class="flex-shrink-0 w-[300px] bg-[#161618] p-4 overflow-y-auto">
-          <div class="text-sm text-muted-foreground">Left Nav</div>
+          <div class="text-sm text-white/70">Left Nav</div>
           <div class="mt-2 space-y-1">
             <div class="text-sky-400 text-sm px-2 py-1 bg-sky-400/10 rounded">Content</div>
-            <div class="text-muted-foreground text-sm px-2 py-1">Summary</div>
-            <div class="text-muted-foreground text-sm px-2 py-1">Key Points</div>
+            <div class="text-white/70 text-sm px-2 py-1">Summary</div>
+            <div class="text-white/70 text-sm px-2 py-1">Key Points</div>
           </div>
         </div>
 
@@ -239,7 +238,7 @@ export const FullExtensionLayout: Story = {
                     </div>
                   </ChatContainer>
                   <div class="px-3 pb-3 pt-1 flex-shrink-0">
-                    <div class="bg-muted/40 rounded-lg px-3 py-2.5 text-sm text-muted-foreground/40">
+                    <div class="bg-muted/40 rounded-lg px-3 py-2.5 text-sm text-foreground/75">
                       Ask about this page...
                     </div>
                   </div>
@@ -304,7 +303,7 @@ export const InsideResizablePanel: Story = {
                 </ChatContainer>
 
                 <div class="px-3 pb-3 pt-1 flex-shrink-0">
-                  <div class="bg-muted/40 rounded-lg px-3 py-2.5 text-sm text-muted-foreground/40">
+                  <div class="bg-muted/40 rounded-lg px-3 py-2.5 text-sm text-foreground/75">
                     Ask about this page...
                   </div>
                 </div>

package/src/components/message-skills.stories.tsx

@@ -3,6 +3,7 @@ import { MessageSkills } from "./message-skills";
 import { Message, MessageContent, MessageActions } from "./message";
 import { ChatConfig } from "../primitives/chat-config";
 import { Copy, ThumbsUp, ThumbsDown } from "lucide-solid";
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: "Components/MessageSkills",
@@ -12,14 +13,12 @@ const meta = {
     layout: "padded",
     docs: {
       controls: { exclude: ["use:eventListener"] },
-      description: {
-        component: [
-          "A row of small badges that label which **skills** were active when a message was generated.",
-          "**When to use:** above an assistant message whose response was shaped by one or more skills (e.g. `Concise`, `ELI5`). Renders nothing when the `skills` array is empty.",
-          "**How to use:** pass a `skills` array of `{ id, name }`; each `name` is shown as a badge. Add `class` (e.g. `mb-1`) to space it from the message body.",
-          "**Placement:** directly above `MessageContent` inside an assistant `Message`.",
-        ].join("\n\n"),
-      },
+      description: componentDescription([
+        "A row of small badges that label which **skills** were active when a message was generated.",
+        "**When to use:** above an assistant message whose response was shaped by one or more skills (e.g. `Concise`, `ELI5`). Renders nothing when the `skills` array is empty.",
+        "**How to use:** pass a `skills` array of `{ id, name }`; each `name` is shown as a badge. Add `class` (e.g. `mb-1`) to space it from the message body.",
+        "**Placement:** directly above `MessageContent` inside an assistant `Message`.",
+      ]),
     },
   },
   argTypes: {
@@ -94,13 +93,13 @@ export const InAssistantMessage: Story = {
             {"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix: update comparison operator in `validateToken()`."}
           </MessageContent>
           <MessageActions class="[&>button]:p-1 [&>button]:rounded [&>button]:text-foreground/60 [&>button]:hover:text-foreground [&>button]:transition-colors">
-            <button>
+            <button aria-label="Copy message">
               <Copy size={14} />
             </button>
-            <button>
+            <button aria-label="Good response">
               <ThumbsUp size={14} />
             </button>
-            <button>
+            <button aria-label="Bad response">
               <ThumbsDown size={14} />
             </button>
           </MessageActions>
@@ -113,13 +112,13 @@ export const InAssistantMessage: Story = {
             causes tokens to be accepted even when they've just expired.
           </MessageContent>
           <MessageActions class="[&>button]:p-1 [&>button]:rounded [&>button]:text-foreground/60 [&>button]:hover:text-foreground [&>button]:transition-colors">
-            <button>
+            <button aria-label="Copy message">
               <Copy size={14} />
             </button>
-            <button>
+            <button aria-label="Good response">
               <ThumbsUp size={14} />
             </button>
-            <button>
+            <button aria-label="Bad response">
               <ThumbsDown size={14} />
             </button>
           </MessageActions>
@@ -153,7 +152,7 @@ export const InConversation: Story = {
             components, render props, and custom hooks for state management.
           </MessageContent>
           <MessageActions class="[&>button]:p-1 [&>button]:rounded [&>button]:text-foreground/60 [&>button]:hover:text-foreground [&>button]:transition-colors">
-            <button><Copy size={14} /></button>
+            <button aria-label="Copy message"><Copy size={14} /></button>
           </MessageActions>
         </Message>
 
@@ -171,7 +170,7 @@ export const InConversation: Story = {
             it easier to share pieces between different builds.
           </MessageContent>
           <MessageActions class="[&>button]:p-1 [&>button]:rounded [&>button]:text-foreground/60 [&>button]:hover:text-foreground [&>button]:transition-colors">
-            <button><Copy size={14} /></button>
+            <button aria-label="Copy message"><Copy size={14} /></button>
           </MessageActions>
         </Message>
 
@@ -197,7 +196,7 @@ export const InConversation: Story = {
 **Custom Hooks**: Extract stateful logic into reusable functions prefixed with \`use\`.`}
           </MessageContent>
           <MessageActions class="[&>button]:p-1 [&>button]:rounded [&>button]:text-foreground/60 [&>button]:hover:text-foreground [&>button]:transition-colors">
-            <button><Copy size={14} /></button>
+            <button aria-label="Copy message"><Copy size={14} /></button>
           </MessageActions>
         </Message>
       </div>

package/src/components/message.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Message, MessageAvatar, MessageContent, MessageActions } from './message';
 import { Button } from '../ui/button';
 import { Copy, ThumbsUp, ThumbsDown, RefreshCw, Pencil } from 'lucide-solid';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/Message',
@@ -11,14 +12,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A horizontal message row that composes an optional `MessageAvatar`, a `MessageContent` body (plain or markdown), and an optional `MessageActions` toolbar.',
-          '**When to use:** rendering any chat turn — user or assistant. Use a bubble + right alignment for user turns, and an avatar + transparent content for assistant turns.',
-          '**How to use:** wrap the parts in `<Message>`. Add `MessageAvatar` for the speaker, `MessageContent` for the text (set `markdown` to render markdown), and `MessageActions` for hover actions. Layout (alignment, bubble) is controlled via `class`.',
-          '**Placement:** inside a `ChatContainer`/scroll region, stacked vertically as the conversation transcript.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A horizontal message row that composes an optional `MessageAvatar`, a `MessageContent` body (plain or markdown), and an optional `MessageActions` toolbar.',
+        '**When to use:** rendering any chat turn — user or assistant. Use a bubble + right alignment for user turns, and an avatar + transparent content for assistant turns.',
+        '**How to use:** wrap the parts in `<Message>`. Add `MessageAvatar` for the speaker, `MessageContent` for the text (set `markdown` to render markdown), and `MessageActions` for hover actions. Layout (alignment, bubble) is controlled via `class`.',
+        '**Placement:** inside a `ChatContainer`/scroll region, stacked vertically as the conversation transcript.',
+      ]),
     },
   },
   argTypes: {
@@ -132,10 +131,10 @@ export const UserAlignedRight: Story = {
             Can you explain how SolidJS reactivity differs from React hooks?
           </MessageContent>
           <MessageActions class="flex gap-0 opacity-0 transition-opacity duration-150 group-hover:opacity-100">
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Edit message">
               <Pencil class="size-3.5" />
             </Button>
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Copy message">
               <Copy class="size-3.5" />
             </Button>
           </MessageActions>
@@ -198,16 +197,16 @@ export const WithActions: Story = {
             Here is a response with hover actions below it.
           </MessageContent>
           <MessageActions class="-ml-2.5 flex gap-0 opacity-0 transition-opacity duration-150 group-hover:opacity-100">
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Copy message">
               <Copy class="size-3.5" />
             </Button>
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Good response">
               <ThumbsUp class="size-3.5" />
             </Button>
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Bad response">
               <ThumbsDown class="size-3.5" />
             </Button>
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Regenerate response">
               <RefreshCw class="size-3.5" />
             </Button>
           </MessageActions>
@@ -251,16 +250,16 @@ Key benefits:
 - Makes large codebases more maintainable`}
           </MessageContent>
           <MessageActions class="-ml-2.5 flex gap-0 opacity-0 transition-opacity duration-150 group-hover:opacity-100">
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Copy message">
               <Copy class="size-3.5" />
             </Button>
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Good response">
               <ThumbsUp class="size-3.5" />
             </Button>
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Bad response">
               <ThumbsDown class="size-3.5" />
             </Button>
-            <Button variant="ghost" size="icon-sm" class="rounded-full">
+            <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Regenerate response">
               <RefreshCw class="size-3.5" />
             </Button>
           </MessageActions>

package/src/components/model-switcher.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { ModelSwitcher } from './model-switcher';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const multipleModels = [
   { id: 'claude-sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
@@ -17,14 +18,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A compact dropdown that shows the active model and lets the user switch between the available **models** (grouped by optional `provider` label).',
-          '**When to use:** when a chat surface offers more than one model. It renders nothing when fewer than two models are provided, so it is safe to mount unconditionally.',
-          '**How to use:** pass the `models` list and the `currentModelId`, then handle `onModelChange` to update your selected-model state.',
-          '**Placement:** the prompt input action bar, a chat header, or a settings/toolbar row near the composer.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A compact dropdown that shows the active model and lets the user switch between the available **models** (grouped by optional `provider` label).',
+        '**When to use:** when a chat surface offers more than one model. It renders nothing when fewer than two models are provided, so it is safe to mount unconditionally.',
+        '**How to use:** pass the `models` list and the `currentModelId`, then handle `onModelChange` to update your selected-model state.',
+        '**Placement:** the prompt input action bar, a chat header, or a settings/toolbar row near the composer.',
+      ]),
     },
   },
   argTypes: {

package/src/components/prompt-input.stories.tsx

@@ -3,6 +3,7 @@ import { fn } from 'storybook/test';
 import { createSignal } from 'solid-js';
 import { PromptInput, PromptInputTextarea, PromptInputActions } from './prompt-input';
 import { Button } from '../ui/button';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/PromptInput',
@@ -12,14 +13,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A composer shell that hosts an auto-resizing `PromptInputTextarea` and a `PromptInputActions` toolbar, with controlled or uncontrolled value, loading, and disabled states.',
-          '**When to use:** as the message input at the bottom of any chat surface, wherever the user types and submits a prompt.',
-          '**How to use:** control text via `value` + `onValueChange` (or leave uncontrolled), wire `onSubmit` (also fired on Enter without Shift), and place your send/stop controls inside `PromptInputActions`. Toggle `isLoading` / `disabled` for in-flight and read-only states.',
-          '**Placement:** pinned at the bottom of the chat column, below the message transcript.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A composer shell that hosts an auto-resizing `PromptInputTextarea` and a `PromptInputActions` toolbar, with controlled or uncontrolled value, loading, and disabled states.',
+        '**When to use:** as the message input at the bottom of any chat surface, wherever the user types and submits a prompt.',
+        '**How to use:** control text via `value` + `onValueChange` (or leave uncontrolled), wire `onSubmit` (also fired on Enter without Shift), and place your send/stop controls inside `PromptInputActions`. Toggle `isLoading` / `disabled` for in-flight and read-only states.',
+        '**Placement:** pinned at the bottom of the chat column, below the message transcript.',
+      ]),
     },
   },
   argTypes: {
@@ -199,7 +198,7 @@ export const WithMultipleActions: Story = {
           <PromptInputTextarea placeholder="Ask anything..." />
           <PromptInputActions class="justify-between w-full px-2 pb-1">
             <div class="flex items-center gap-1">
-              <Button variant="ghost" size="icon-sm">
+              <Button variant="ghost" size="icon-sm" aria-label="Attach file">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
                   <path d="M21.44 11.05l-9.19 9.19a6 6 0 01-8.49-8.49l9.19-9.19a4 4 0 015.66 5.66l-9.2 9.19a2 2 0 01-2.83-2.83l8.49-8.48" />
                 </svg>

package/src/components/prompt-suggestion.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { PromptSuggestion } from './prompt-suggestion';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/PromptSuggestion',
@@ -9,14 +10,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A clickable suggestion chip built on `Button` — renders as a rounded pill, a full-width list row (`block`), or a search-style row that highlights a matching substring (`highlight`).',
-          '**When to use:** offer the user ready-made prompts to send — empty-state starter questions, follow-up suggestions, or a filtered list of matching prompts as they type.',
-          '**How to use:** pass the prompt text as children and wire `onClick` to submit it. Use `block` for stacked, left-aligned list rows; pass `highlight` to emphasize a matched substring (forces list-row layout). Override `variant`/`size` to restyle.',
-          '**Placement:** chat empty states, below the prompt input as follow-ups, or in a suggestion dropdown.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A clickable suggestion chip built on `Button` — renders as a rounded pill, a full-width list row (`block`), or a search-style row that highlights a matching substring (`highlight`).',
+        '**When to use:** offer the user ready-made prompts to send — empty-state starter questions, follow-up suggestions, or a filtered list of matching prompts as they type.',
+        '**How to use:** pass the prompt text as children and wire `onClick` to submit it. Use `block` for stacked, left-aligned list rows; pass `highlight` to emphasize a matched substring (forces list-row layout). Override `variant`/`size` to restyle.',
+        '**Placement:** chat empty states, below the prompt input as follow-ups, or in a suggestion dropdown.',
+      ]),
       controls: { exclude: ['use:eventListener'] },
     },
   },