@elabs-ai/components-ai 4.0.0

package/src/suggestion.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+import { StreamingSuggestions, Suggestion, Suggestions } from "./suggestion";
+const meta = {
+  title: "AI/Suggestion",
+  component: Suggestions,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Suggestions>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+// Default = the soft tinted pill (#194): borderless `bg-secondary rounded-full`.
+export const Default: Story = {
+  render: () => (
+    <Suggestions>
+      {["Summarize the deploys", "Explain the billing error", "Write a regression test"].map(
+        (s) => (
+          <Suggestion key={s} suggestion={s} onClick={() => {}} />
+        ),
+      )}
+    </Suggestions>
+  ),
+};
+// A caller can still opt into an outlined chip; reach for the quiet
+// `outline-subtle` rung. (Since the ADR 0010 Amendment, 2026-06-20, `--input` ==
+// `--border` so `outline`/`outline-subtle` render identically by default;
+// `outline-subtle` remains the semantically correct choice for a quiet chip.)
+export const OutlineSubtle: Story = {
+  render: () => (
+    <Suggestions>
+      {["Compare to last quarter", "Draft the follow-up email"].map((s) => (
+        <Suggestion key={s} suggestion={s} variant="outline-subtle" onClick={() => {}} />
+      ))}
+    </Suggestions>
+  ),
+};
+
+// Streaming trailing-loader — chips are present and a shimmering trailing chip
+// is shown while the generator is still producing suggestions.
+export const Streaming: Story = {
+  render: () => (
+    <StreamingSuggestions
+      loading
+      suggestions={["Summarize the deploys", "Explain the billing error"]}
+      onSuggestionClick={() => {}}
+    />
+  ),
+};
+
+// Live demo — suggestions appear progressively, then the trailing loader
+// disappears once the set settles.
+export const StreamingLive: Story = {
+  render: function StreamingLive() {
+    const all = [
+      "Summarize the deploys",
+      "Explain the billing error",
+      "Write a regression test",
+      "Draft the follow-up email",
+    ];
+    const [count, setCount] = useState(0);
+    const done = count >= all.length;
+    useEffect(() => {
+      if (done) return;
+      const t = setTimeout(() => setCount((c) => c + 1), 700);
+      return () => clearTimeout(t);
+    }, [count, done]);
+    return (
+      <StreamingSuggestions
+        loading={!done}
+        suggestions={all.slice(0, count)}
+        onSuggestionClick={() => {}}
+      />
+    );
+  },
+};

package/src/suggestion.test.tsx

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { StreamingSuggestions, Suggestion, SuggestionLoading } from "./suggestion";
+
+describe("Suggestion", () => {
+  it("renders the suggestion text and fires onClick with it", async () => {
+    const onClick = vi.fn();
+    render(<Suggestion suggestion="Summarize the deploy log" onClick={onClick} />);
+
+    const button = screen.getByRole("button", { name: "Summarize the deploy log" });
+    expect(button).toBeInTheDocument();
+
+    await userEvent.click(button);
+    expect(onClick).toHaveBeenCalledWith("Summarize the deploy log");
+  });
+
+  // #194 (research 02 §3a BTN-2): the default is the soft tinted pill —
+  // borderless `bg-secondary` + `rounded-full` — never the strong `--input`
+  // outline. A caller-supplied variant still wins.
+  it("defaults to the borderless secondary pill", () => {
+    render(<Suggestion suggestion="Soft pill" />);
+    const button = screen.getByRole("button", { name: "Soft pill" });
+    const classes = button.className.split(" ");
+    expect(classes).toContain("bg-secondary");
+    expect(classes).toContain("rounded-full");
+    expect(classes).not.toContain("border");
+    expect(classes).not.toContain("border-input");
+  });
+});
+
+describe("SuggestionLoading", () => {
+  it("renders a status chip with the shimmering label", () => {
+    render(<SuggestionLoading />);
+    const status = screen.getByRole("status");
+    expect(status).toHaveTextContent("Thinking…");
+  });
+
+  it("accepts a custom label", () => {
+    render(<SuggestionLoading label="Generating…" />);
+    expect(screen.getByRole("status")).toHaveTextContent("Generating…");
+  });
+});
+
+describe("StreamingSuggestions", () => {
+  it("renders chips and a trailing loader while loading", () => {
+    render(
+      <StreamingSuggestions
+        suggestions={["First", "Second"]}
+        loading
+        onSuggestionClick={vi.fn()}
+      />,
+    );
+    expect(screen.getByRole("button", { name: "First" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Second" })).toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveTextContent("Thinking…");
+  });
+
+  it("hides the trailing loader once the set settles", () => {
+    render(<StreamingSuggestions suggestions={["First", "Second"]} loading={false} />);
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+
+  it("fires onSuggestionClick with the chosen suggestion", async () => {
+    const onSuggestionClick = vi.fn();
+    render(
+      <StreamingSuggestions suggestions={["Pick me"]} onSuggestionClick={onSuggestionClick} />,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Pick me" }));
+    expect(onSuggestionClick).toHaveBeenCalledWith("Pick me");
+  });
+});

package/src/suggestion.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import { Button } from "@elabs-ai/components-ui";
+import { ScrollArea, ScrollBar } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { ComponentProps, HTMLAttributes } from "react";
+import { useCallback } from "react";
+
+import { Shimmer } from "./shimmer";
+
+export type SuggestionsProps = ComponentProps<typeof ScrollArea>;
+
+export const Suggestions = ({ className, children, ...props }: SuggestionsProps) => (
+  <ScrollArea className="w-full overflow-x-auto whitespace-nowrap" {...props}>
+    <div className={cn("flex w-max flex-nowrap items-center gap-2", className)}>{children}</div>
+    <ScrollBar className="hidden" orientation="horizontal" />
+  </ScrollArea>
+);
+
+export type SuggestionProps = Omit<ComponentProps<typeof Button>, "onClick"> & {
+  suggestion: string;
+  onClick?: (suggestion: string) => void;
+};
+
+export const Suggestion = ({
+  suggestion,
+  onClick,
+  className,
+  // The soft tinted pill (#194, research 02 §3a BTN-2 / 08 §C.1): `secondary`
+  // = borderless `bg-secondary` fill; the pill shape comes from `rounded-full`
+  // below. The harsh `outline` (strong `--input` boundary) is for form-adjacent
+  // controls, not chips.
+  variant = "secondary",
+  size = "sm",
+  children,
+  ...props
+}: SuggestionProps) => {
+  const handleClick = useCallback(() => {
+    onClick?.(suggestion);
+  }, [onClick, suggestion]);
+
+  return (
+    <Button
+      className={cn("cursor-pointer rounded-full px-4", className)}
+      onClick={handleClick}
+      size={size}
+      type="button"
+      variant={variant}
+      {...props}
+    >
+      {children || suggestion}
+    </Button>
+  );
+};
+
+export type SuggestionLoadingProps = HTMLAttributes<HTMLDivElement> & {
+  /** Shimmering label shown while the suggestion set is still generating. */
+  label?: string;
+};
+
+/**
+ * A non-interactive trailing chip that shimmers while suggestions stream in.
+ * Shaped like a `Suggestion` pill; composes `Shimmer` (motion-reduce aware) and
+ * announces via `role="status"`. Render it after the chips while loading.
+ */
+export const SuggestionLoading = ({
+  label = "Thinking…",
+  className,
+  ...props
+}: SuggestionLoadingProps) => (
+  <div
+    role="status"
+    aria-live="polite"
+    className={cn(
+      "inline-flex h-8 shrink-0 items-center rounded-full bg-secondary px-4 text-body",
+      className,
+    )}
+    {...props}
+  >
+    <Shimmer as="span" className="text-secondary-foreground">
+      {label}
+    </Shimmer>
+  </div>
+);
+
+export type StreamingSuggestionsProps = Omit<SuggestionsProps, "children"> & {
+  /** The suggestions to render. As this array grows, new chips appear in place. */
+  suggestions: string[];
+  /** While true, a shimmering trailing chip is shown until the set settles. */
+  loading?: boolean;
+  /** Click handler for a suggestion chip. */
+  onSuggestionClick?: (suggestion: string) => void;
+  /** Label for the trailing loading chip. @default "Thinking…" */
+  loadingLabel?: string;
+};
+
+/**
+ * Suggestions that appear progressively while a generator streams. Each chip
+ * fades in on mount (existing chips don't re-animate — keys are the suggestion
+ * text); a shimmering trailing chip shows until `loading` flips false.
+ */
+export const StreamingSuggestions = ({
+  suggestions,
+  loading = false,
+  onSuggestionClick,
+  loadingLabel,
+  ...props
+}: StreamingSuggestionsProps) => (
+  <Suggestions {...props}>
+    {suggestions.map((s) => (
+      <Suggestion
+        key={s}
+        suggestion={s}
+        onClick={onSuggestionClick}
+        className="animate-in fade-in-0 slide-in-from-bottom-1 duration-fast ease-entrance motion-reduce:animate-none"
+      />
+    ))}
+    {loading && <SuggestionLoading label={loadingLabel} />}
+  </Suggestions>
+);

package/src/task.stories.tsx

@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Task, TaskContent, TaskItem, TaskItemFile, TaskTrigger } from "./task";
+const meta = { title: "AI/Task", component: Task, parameters: { layout: "padded" } } satisfies Meta<
+  typeof Task
+>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+// Collapsed by default since #192; `defaultOpen` here only so the docs render
+// the body — the items ride the canonical AgentTimeline rail.
+export const Default: Story = {
+  render: () => (
+    <Task defaultOpen className="max-w-prose">
+      <TaskTrigger title="Searched the codebase" />
+      <TaskContent>
+        <TaskItem>
+          Read <TaskItemFile>app.tsx</TaskItemFile> and <TaskItemFile>router.ts</TaskItemFile>
+        </TaskItem>
+        <TaskItem>Found 3 matching call sites</TaskItem>
+      </TaskContent>
+    </Task>
+  ),
+};

package/src/task.test.tsx

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Task, TaskContent, TaskItem, TaskItemFile, TaskTrigger } from "./task";
+
+describe("Task (#192, research 10 §B.6)", () => {
+  it("is collapsed by default (defaultOpen flipped true → false)", () => {
+    render(
+      <Task>
+        <TaskTrigger title="Compiled the board note" />
+        <TaskContent>
+          <TaskItem>Reconciled 8 rows</TaskItem>
+        </TaskContent>
+      </Task>,
+    );
+    expect(screen.getByText("Compiled the board note")).toBeInTheDocument();
+    expect(screen.queryByText("Reconciled 8 rows")).not.toBeInTheDocument();
+  });
+
+  it("renders items on the canonical rail with unbordered file chips when open", () => {
+    render(
+      <Task defaultOpen>
+        <TaskTrigger title="Compiled the board note" />
+        <TaskContent>
+          <TaskItem>
+            Wrote <TaskItemFile data-testid="chip">board-note.md</TaskItemFile>
+          </TaskItem>
+        </TaskContent>
+      </Task>,
+    );
+    const li = screen.getByRole("listitem");
+    expect(li).toHaveAttribute("data-status", "complete");
+    const chip = screen.getByTestId("chip");
+    expect(chip.tagName).toBe("SPAN");
+    expect(chip.className.split(" ")).not.toContain("border");
+  });
+});

package/src/task.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+/**
+ * Task — a collapsed "what got done" run summary (#192, research 10 §B.6).
+ *
+ * The body rides the canonical execution-trace rail (`AgentTimeline` /
+ * `AgentStep`, research 10 §B.3) instead of the pre-#192 hand-rolled
+ * `border-s-2` content rail. Collapsed by default — in a settled transcript
+ * only the focal surfaces (the produced artifact + the final answer) stay
+ * open, not every trace.
+ */
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { ChevronDownIcon } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+
+import { AgentStep, AgentTimeline, type AgentStepProps } from "./agent-timeline";
+
+export type TaskItemFileProps = ComponentProps<"span">;
+
+/**
+ * A quiet inline file chip. Unbordered since #192 (the fill is the gesture;
+ * a border on a filled chip is the redundant-border anti-pattern). For a
+ * navigable list of produced files, prefer the asset-tree idiom (research 09).
+ */
+export const TaskItemFile = ({ children, className, ...props }: TaskItemFileProps) => (
+  <span
+    className={cn(
+      "inline-flex items-center gap-1 rounded-md bg-secondary px-1.5 py-0.5 text-meta text-secondary-foreground",
+      className,
+    )}
+    {...props}
+  >
+    {children}
+  </span>
+);
+
+export type TaskItemProps = Omit<AgentStepProps, "name" | "children"> & {
+  children?: ReactNode;
+};
+
+/**
+ * One line of the run summary — an `AgentStep` on the canonical rail.
+ * Defaults to `status="complete"` (the task reports finished work) with the
+ * badge hidden (the rail node carries the status; a badge per log line would
+ * shout).
+ */
+export const TaskItem = ({
+  children,
+  status = "complete",
+  hideBadge = true,
+  ...props
+}: TaskItemProps) => <AgentStep hideBadge={hideBadge} name={children} status={status} {...props} />;
+
+export type TaskProps = ComponentProps<typeof Collapsible>;
+
+/** Collapsed by default since #192 (`defaultOpen` flipped `true`→`false`). */
+export const Task = ({ className, ...props }: TaskProps) => (
+  <Collapsible className={cn(className)} {...props} />
+);
+
+export type TaskTriggerProps = ComponentProps<typeof CollapsibleTrigger> & {
+  title: string;
+};
+
+export const TaskTrigger = ({ children, className, title, ...props }: TaskTriggerProps) => (
+  <CollapsibleTrigger asChild className={cn("group", className)} {...props}>
+    {children ?? (
+      <div className="flex w-full cursor-pointer items-center gap-2 text-body text-muted-foreground transition-colors hover:text-foreground">
+        <p>{title}</p>
+        <ChevronDownIcon className="size-4 transition-transform group-data-[state=open]:rotate-180" />
+      </div>
+    )}
+  </CollapsibleTrigger>
+);
+
+export type TaskContentProps = ComponentProps<typeof CollapsibleContent>;
+
+export const TaskContent = ({ children, className, ...props }: TaskContentProps) => (
+  <CollapsibleContent
+    className={cn(
+      "data-[state=closed]:fade-out-0 data-[state=closed]:slide-out-to-top-2 data-[state=open]:slide-in-from-top-2 text-popover-foreground outline-none data-[state=closed]:animate-out data-[state=open]:animate-in data-[state=open]:[--tw-ease:var(--ease-entrance)] data-[state=closed]:[--tw-ease:var(--ease-exit)]",
+      className,
+    )}
+    {...props}
+  >
+    <AgentTimeline className="mt-4">{children}</AgentTimeline>
+  </CollapsibleContent>
+);

package/src/templates-ai-assistant.stories.tsx

@@ -0,0 +1,142 @@
+/**
+ * AI assistant template — the canonical full-screen AI assistant composition
+ * (app-shell + chat shell: Conversation + PromptInput). This story is the
+ * single source of truth: `pnpm gen:templates` derives the consumer template
+ * source (`docs/playbooks/templates/ai-assistant.tsx`) from it.
+ * Verify across both themes with globals=theme:<slug>.
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { AppIcon } from "@elabs-ai/components-icons";
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarHeader,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarTrigger,
+} from "@elabs-ai/components-ui";
+import {
+  Composer,
+  Conversation,
+  ConversationContent,
+  ConversationEmptyState,
+  ConversationScrollButton,
+  Message,
+  MessageContent,
+  MessageResponse,
+} from "./index";
+import { Bot, History, Home, Settings } from "lucide-react";
+
+interface ChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+}
+
+const nav = [
+  { id: "chat", label: "Chat", icon: Bot },
+  { id: "history", label: "History", icon: History },
+  { id: "home", label: "Home", icon: Home },
+  { id: "settings", label: "Settings", icon: Settings },
+];
+
+function AiAssistantTemplate() {
+  const [active, setActive] = useState("chat");
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [status, setStatus] = useState<"ready" | "submitted">("ready");
+
+  function send(text: string) {
+    setMessages((m) => [...m, { id: crypto.randomUUID(), role: "user", text }]);
+    setStatus("submitted");
+    const reply = "This is a placeholder response. Connect this to your model runtime.";
+    setMessages((m) => [...m, { id: crypto.randomUUID(), role: "assistant", text: reply }]);
+    setStatus("ready");
+  }
+
+  return (
+    <SidebarProvider>
+      <Sidebar collapsible="icon">
+        <SidebarHeader className="px-3 py-2">
+          <div className="flex items-center gap-2">
+            <AppIcon height={20} aria-hidden />
+            <span className="truncate font-semibold group-data-[collapsible=icon]:hidden">
+              Assistant
+            </span>
+          </div>
+        </SidebarHeader>
+        <SidebarContent>
+          <SidebarGroup>
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {nav.map((n) => (
+                  <SidebarMenuItem key={n.id}>
+                    <SidebarMenuButton
+                      isActive={active === n.id}
+                      tooltip={n.label}
+                      onClick={() => setActive(n.id)}
+                    >
+                      <n.icon aria-hidden="true" />
+                      <span>{n.label}</span>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                ))}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        </SidebarContent>
+      </Sidebar>
+      <SidebarInset className="flex flex-col overflow-hidden">
+        <header className="flex h-14 shrink-0 items-center gap-2 border-b px-4">
+          <SidebarTrigger />
+          <h1 className="text-body font-medium">AI Assistant</h1>
+        </header>
+        <div className="flex flex-1 flex-col overflow-hidden">
+          <Conversation className="flex-1">
+            <ConversationContent>
+              {messages.length === 0 ? (
+                <ConversationEmptyState
+                  title="Start the conversation"
+                  description="Ask anything to begin."
+                />
+              ) : (
+                messages.map((m) => (
+                  <Message from={m.role} key={m.id}>
+                    <MessageContent>
+                      <MessageResponse>{m.text}</MessageResponse>
+                    </MessageContent>
+                  </Message>
+                ))
+              )}
+            </ConversationContent>
+            <ConversationScrollButton />
+          </Conversation>
+          <Composer
+            placeholder="Send a message…"
+            status={status === "submitted" ? "Generating…" : "Awaiting your input"}
+            sendStatus={status}
+            onSubmit={(message) => {
+              const text = message.text?.trim();
+              if (text) send(text);
+            }}
+          />
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
+
+const meta = {
+  title: "Patterns/Templates/AI Assistant",
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+} satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { render: () => <AiAssistantTemplate /> };