@elabs-ai/components-ai 4.0.0

package/src/chat-greeting.stories.tsx

@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { ChatGreeting } from "./chat-greeting";
+import { Composer } from "./composer";
+
+const SUGGESTIONS = ["Summary", "Code", "Design", "Research"];
+
+const meta = {
+  title: "AI/ChatGreeting",
+  component: ChatGreeting,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The centered first-run greeting for an empty chat/composer scene — a display-scale headline with an accent phrase and an optional soft primary glow. Distinct from ConversationEmptyState (a generic 'No messages yet' message panel); pair ChatGreeting with <Composer /> for the standard empty/first-run chat state.",
+      },
+    },
+  },
+  args: {
+    title: "Good morning, Avery",
+    subtitle: "How can I",
+    accent: "assist you today?",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof ChatGreeting>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The standard greeting with its glow. */
+export const Default: Story = {
+  render: (args) => (
+    <div className="mx-auto max-w-2xl bg-background p-10">
+      <ChatGreeting {...args} />
+    </div>
+  ),
+};
+
+/** Dense/embedded use — no glow behind the headline. */
+export const NoOrb: Story = {
+  args: { orb: false },
+  render: (args) => (
+    <div className="mx-auto max-w-2xl bg-background p-10">
+      <ChatGreeting {...args} />
+    </div>
+  ),
+};
+
+/** A long name and a two-line accent phrase — `text-balance` keeps the headline readable. */
+export const LongContent: Story = {
+  args: {
+    title: "Good afternoon, Alexandra Christodoulopoulos",
+    subtitle: "What would you like help with",
+    accent: "today across your reports, dashboards, and data models?",
+  },
+  render: (args) => (
+    <div className="mx-auto max-w-2xl bg-background p-10">
+      <ChatGreeting {...args} />
+    </div>
+  ),
+};
+
+/** `accent` alone, with no `subtitle` line — the second line must not be dropped. */
+export const AccentOnly: Story = {
+  args: { title: "Hi Avery", subtitle: undefined, accent: "what are we building today?" },
+  render: (args) => (
+    <div className="mx-auto max-w-2xl bg-background p-10">
+      <ChatGreeting {...args} />
+    </div>
+  ),
+};
+
+/** A route that already owns the page's `<h1>` — pass `level={2}` to keep a single, hierarchical outline. */
+export const HeadingLevel2: Story = {
+  args: { level: 2 },
+  render: (args) => (
+    <div className="mx-auto max-w-2xl bg-background p-10">
+      <h1 className="sr-only">Assistant</h1>
+      <ChatGreeting {...args} />
+    </div>
+  ),
+};
+
+/** The real first-run chat state: greeting above the standard Composer. */
+export const WithComposer: Story = {
+  parameters: { layout: "fullscreen" },
+  render: (args) => (
+    <div className="grid min-h-[28rem] place-items-center bg-background px-4 py-10 text-foreground">
+      <div className="w-full max-w-2xl">
+        <ChatGreeting {...args} />
+        <Composer onSubmit={() => undefined} suggestions={SUGGESTIONS} />
+      </div>
+    </div>
+  ),
+};

package/src/chat-greeting.test.tsx

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { ChatGreeting } from "./chat-greeting";
+
+describe("ChatGreeting", () => {
+  it("renders the title and accent text", () => {
+    render(
+      <ChatGreeting title="Good morning, Avery" subtitle="How can I" accent="assist you today?" />,
+    );
+
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading).toHaveTextContent("Good morning, Avery");
+    expect(screen.getByText("assist you today?")).toBeInTheDocument();
+  });
+
+  // #254 follow-up: `accent` used to be nested inside the `subtitle` branch, so
+  // an accent-without-subtitle combination silently rendered nothing past the
+  // title. Both must be independently renderable.
+  it("renders accent even when subtitle is omitted", () => {
+    render(<ChatGreeting title="Hi Avery" accent="what are we building today?" />);
+
+    expect(screen.getByText("what are we building today?")).toBeInTheDocument();
+  });
+
+  // #254 follow-up: a monochrome theme's --primary can be a near-white "pen",
+  // ΔL/ΔC vs --foreground so small that `text-primary` alone is invisible as
+  // an accent there. The underline + bold weight are a NON-hue channel that
+  // must survive regardless of which theme resolves `text-primary`.
+  it("carries a non-hue emphasis (bold + underline) on the accent, not color alone", () => {
+    render(<ChatGreeting title="Hi Avery" accent="assist you today?" />);
+
+    const accent = screen.getByText("assist you today?");
+    const classes = accent.className.split(" ");
+    expect(classes).toContain("font-bold");
+    expect(classes).toContain("underline");
+  });
+
+  it("renders subtitle even when accent is omitted", () => {
+    render(<ChatGreeting title="Hi Avery" subtitle="Ready when you are" />);
+
+    // `subtitle` is a bare text node beside `title` inside the same heading (no
+    // wrapping element of its own, unlike `accent`), so assert via the
+    // heading's text content rather than `getByText` (which matches an
+    // element's OWN text, not a node it merely contains).
+    expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent("Ready when you are");
+  });
+
+  it("renders an aria-hidden orb by default and omits it when orb is false", () => {
+    const { container, rerender } = render(<ChatGreeting title="Hello" />);
+
+    const orb = container.querySelector('[aria-hidden="true"]');
+    expect(orb).not.toBeNull();
+
+    rerender(<ChatGreeting title="Hello" orb={false} />);
+    expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
+  });
+
+  // #254 root-cause: without `isolate`, the negative-z-index orb paints BELOW
+  // an opaque ancestor's own background (CSS painting order), so it's
+  // invisible in every shipped usage (all wrap ChatGreeting in a filled
+  // container). `isolate` gives ChatGreeting its own stacking context so the
+  // whole subtree — orb included — paints as one unit above the ancestor fill.
+  it("isolates its own stacking context so the orb can paint above an ancestor fill", () => {
+    const { container } = render(<ChatGreeting title="Hello" />);
+    const root = container.firstElementChild as HTMLElement;
+    expect(root.className.split(" ")).toContain("isolate");
+  });
+
+  it("defaults to a level-1 heading and honors an explicit level override", () => {
+    const { rerender } = render(<ChatGreeting title="Hello" />);
+    expect(screen.getByRole("heading", { level: 1 })).toBeInTheDocument();
+
+    rerender(<ChatGreeting title="Hello" level={2} />);
+    expect(screen.getByRole("heading", { level: 2 })).toBeInTheDocument();
+    expect(screen.queryByRole("heading", { level: 1 })).not.toBeInTheDocument();
+  });
+
+  // Reuse audit: the headline is the shared `Heading` primitive so it carries
+  // the `--font-display` brand seam, not a hand-rolled `<h1>`.
+  it("renders the title through the shared Heading primitive (font-display seam)", () => {
+    render(<ChatGreeting title="Hello" />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.className.split(" ")).toContain("font-display");
+  });
+
+  it("merges a custom className onto the root", () => {
+    const { container } = render(<ChatGreeting title="Hello" className="custom-class" />);
+
+    expect(container.firstElementChild).toHaveClass("custom-class");
+  });
+});

package/src/chat-greeting.tsx

@@ -0,0 +1,91 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import { forwardRef } from "react";
+import { cn, Heading, type HeadingLevel } from "@elabs-ai/components-ui";
+
+export interface ChatGreetingProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Primary line, e.g. "Good morning, Avery". */
+  title: ReactNode;
+  /**
+   * Second line, rendered under `title` inside the same heading. Independent
+   * of `accent` — either may be passed alone.
+   */
+  subtitle?: ReactNode;
+  /**
+   * Phrase rendered in `text-primary-text` with a bold underline, appended
+   * after `subtitle` (or alone). The underline + weight is a NON-hue channel
+   * deliberately layered on top of the color — a monochrome theme's `--primary`
+   * can be a near-white "pen" by design, in which case the accent colour alone
+   * is indistinguishable from the surrounding `--foreground` headline text. The
+   * underline/weight keep the phrase legible as an accent in EVERY theme,
+   * not only the two where hue alone would carry it.
+   */
+  accent?: ReactNode;
+  /** Soft primary glow behind the headline. Default `true`; `false` for dense/embedded use. */
+  orb?: boolean;
+  /**
+   * Semantic heading level for `title`. Default `1` (a chat empty state is
+   * typically the only heading on the page). Override to `2`+ when ChatGreeting
+   * sits inside a page or route that already renders its own `<h1>` —
+   * `Heading` decouples `level` from `size`, so the visual display-scale rung
+   * stays put regardless of the level chosen.
+   */
+  level?: HeadingLevel;
+}
+
+/**
+ * ChatGreeting — the centered first-run greeting for an empty chat/composer scene.
+ *
+ * A display-scale headline (`title`, then `subtitle` with an `accent` phrase
+ * in `text-primary-text` + a bold underline, so the accent reads in every theme,
+ * including a monochrome one whose `--primary` is otherwise the same
+ * near-white as the headline) over an optional soft primary glow. Pair it
+ * with `<Composer />` for the standard empty/first-run chat state.
+ *
+ * Distinct from `ConversationEmptyState` (a generic centered "No messages yet"
+ * message panel) — this is the display-scale greeting anatomy, not a status
+ * message.
+ */
+export const ChatGreeting = forwardRef<HTMLDivElement, ChatGreetingProps>(function ChatGreeting(
+  { title, subtitle, accent, orb = true, level = 1, className, ...props },
+  ref,
+) {
+  const hasSecondLine = subtitle != null || accent != null;
+
+  return (
+    <div
+      ref={ref}
+      data-slot="chat-greeting"
+      // `isolate` gives the root its own stacking context so the negative-
+      // z-index orb paints ABOVE an ancestor's own background instead of
+      // beneath it (CSS painting order step 2 vs step 3) — without it, any
+      // opaque wrapper (e.g. a `bg-background` scene container) occludes the
+      // glow entirely. See issue #254 root-cause.
+      className={cn("relative isolate mb-10 text-center", className)}
+      {...props}
+    >
+      {orb ? (
+        <div
+          aria-hidden="true"
+          data-slot="chat-greeting-orb"
+          className="pointer-events-none absolute start-1/2 top-0 -z-10 size-40 -translate-x-1/2 -translate-y-1/2 rounded-full bg-primary/15 blur-3xl"
+        />
+      ) : null}
+      <Heading data-slot="chat-greeting-title" level={level} size="display">
+        {title}
+        {hasSecondLine ? (
+          <>
+            <br />
+            {subtitle}
+            {subtitle != null && accent != null ? " " : null}
+            {accent != null ? (
+              // #399 — accent phrase inside a headline is TEXT: `-text` rung.
+              <span className="font-bold text-primary-text underline decoration-2 underline-offset-4">
+                {accent}
+              </span>
+            ) : null}
+          </>
+        ) : null}
+      </Heading>
+    </div>
+  );
+});

package/src/chat-shell.stories.tsx

@@ -0,0 +1,123 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { cn } from "@elabs-ai/components-ui";
+import { ChatShell } from "./chat-shell";
+import { Conversation, ConversationContent, ConversationScrollButton } from "./conversation";
+import { Message, MessageContent, MessageResponse } from "./message";
+import { Composer } from "./composer";
+import { Reasoning, ReasoningContent, ReasoningTrigger } from "./reasoning";
+import { Source, Sources, SourcesContent, SourcesTrigger } from "./sources";
+import { ContextPanelRail } from "./_chat-shell-rail";
+
+interface Msg {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  reasoning?: string;
+}
+
+const initial: Msg[] = [
+  { id: "1", role: "user", text: "What changed in last week's deploys?" },
+  {
+    id: "2",
+    role: "assistant",
+    text: "Three services shipped this week. **Billing** is currently degraded — elevated p95 latency after the last rollout.",
+    reasoning:
+      "Queried CI for the last 7 days, grouped by service, then flagged regressions from the rollback log.",
+  },
+];
+
+function ChatShellExample({ variant = "card" }: { variant?: "card" | "bare" }) {
+  const [messages, setMessages] = useState<Msg[]>(initial);
+  const [status, setStatus] = useState<"ready" | "submitted">("ready");
+
+  const send = (text: string) => {
+    setMessages((m) => [...m, { id: String(m.length + 1), role: "user", text }]);
+    setStatus("submitted");
+    setTimeout(() => {
+      setMessages((m) => [
+        ...m,
+        {
+          id: String(m.length + 1),
+          role: "assistant",
+          text: "Three services shipped; billing is degraded.",
+        },
+      ]);
+      setStatus("ready");
+    }, 600);
+  };
+
+  return (
+    // For `bare`, the wrapper is the bounded pane the immersive shell fills —
+    // exactly how a workspace `SidebarInset` already frames the region.
+    <div
+      className={cn(
+        "mx-auto h-[640px] max-w-4xl",
+        variant === "bare" && "overflow-hidden rounded-xl border bg-background",
+      )}
+    >
+      <ChatShell
+        variant={variant}
+        header={<span className="text-body font-semibold">Ops Assistant</span>}
+        aside={<ContextPanelRail />}
+        composer={
+          <Composer
+            placeholder="Ask about deploys…"
+            status={status === "submitted" ? "Generating…" : "Awaiting your input"}
+            sendStatus={status}
+            onSubmit={(message) => {
+              const text = message.text?.trim();
+              if (text) send(text);
+            }}
+          />
+        }
+      >
+        <Conversation className="flex-1">
+          <ConversationContent>
+            {messages.map((m) => (
+              <Message from={m.role} key={m.id}>
+                <MessageContent>
+                  {m.reasoning ? (
+                    <Reasoning>
+                      <ReasoningTrigger />
+                      <ReasoningContent>{m.reasoning}</ReasoningContent>
+                    </Reasoning>
+                  ) : null}
+                  <MessageResponse>{m.text}</MessageResponse>
+                  {m.role === "assistant" ? (
+                    <Sources>
+                      <SourcesTrigger count={2} />
+                      <SourcesContent>
+                        <Source href="https://example.com" title="Deploy log — wk 23" />
+                        <Source href="https://example.com" title="Billing runbook" />
+                      </SourcesContent>
+                    </Sources>
+                  ) : null}
+                </MessageContent>
+              </Message>
+            ))}
+          </ConversationContent>
+          <ConversationScrollButton />
+        </Conversation>
+      </ChatShell>
+    </div>
+  );
+}
+
+const meta = {
+  title: "AI/ChatShell",
+  component: ChatShellExample,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof ChatShellExample>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/**
+ * Frameless immersive layout: no card border, the transcript fades under the
+ * header and above the composer, and the composer floats on the pane ground.
+ * Use inside an already-bounded region (an AppShell pane, a full-page
+ * workspace) so the shell doesn't draw a redundant second frame.
+ */
+export const Bare: Story = { args: { variant: "bare" } };

package/src/chat-shell.test.tsx

@@ -0,0 +1,113 @@
+/**
+ * chat-shell.test.tsx — smoke + layout-contract lock for the chat frame (#59).
+ *
+ * ChatShell is the outermost container of every chat surface in the library, and
+ * until #59 it had no test at all — its only coverage was inside stories. The
+ * contract worth locking is structural: the four slots render where the caller
+ * expects them and in transcript order; an unsupplied slot is OMITTED rather
+ * than rendered empty (an empty header would still reserve its 3rem row); and
+ * the `bare` variant's edge scrims are inert — `aria-hidden` AND
+ * `pointer-events-none`, or an immersive pane would silently eat taps at the top
+ * and bottom of its own transcript.
+ *
+ * Nothing here is mocked: the assertions run against the real component as it
+ * ships (the #34/#46 lesson — a stand-in that happens to honour an aria
+ * attribute proves nothing about the shipped surface).
+ */
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { ChatShell } from "./chat-shell";
+
+describe("ChatShell — slots", () => {
+  it("renders the transcript children", () => {
+    render(
+      <ChatShell>
+        <p>transcript</p>
+      </ChatShell>,
+    );
+    expect(screen.getByText("transcript")).toBeInTheDocument();
+  });
+
+  it("renders header, transcript, composer and aside together", () => {
+    render(
+      <ChatShell
+        header={<h2>Assistant</h2>}
+        composer={<textarea aria-label="Message" />}
+        aside={<nav aria-label="Sources" />}
+      >
+        <p>transcript</p>
+      </ChatShell>,
+    );
+    expect(screen.getByRole("heading", { name: "Assistant" })).toBeInTheDocument();
+    expect(screen.getByText("transcript")).toBeInTheDocument();
+    expect(screen.getByRole("textbox", { name: "Message" })).toBeInTheDocument();
+    expect(screen.getByRole("navigation", { name: "Sources" })).toBeInTheDocument();
+  });
+
+  it("puts the composer AFTER the transcript in DOM order (tab order follows reading order)", () => {
+    render(
+      <ChatShell composer={<textarea aria-label="Message" />}>
+        <p>transcript</p>
+      </ChatShell>,
+    );
+    const transcript = screen.getByText("transcript");
+    const composer = screen.getByRole("textbox", { name: "Message" });
+    // Node.DOCUMENT_POSITION_FOLLOWING === 4
+    expect(transcript.compareDocumentPosition(composer) & 4).toBeTruthy();
+  });
+
+  it("omits the header row entirely when no header is supplied", () => {
+    const { container } = render(<ChatShell>t</ChatShell>);
+    // An empty header would still occupy its fixed h-12 row.
+    expect(container.querySelector(".h-12")).toBeNull();
+  });
+
+  it("omits the aside rail entirely when no aside is supplied", () => {
+    const { container } = render(<ChatShell>t</ChatShell>);
+    expect(container.querySelector(".w-80")).toBeNull();
+  });
+});
+
+describe("ChatShell — variants", () => {
+  it("frames itself as a card by default", () => {
+    const { container } = render(<ChatShell>t</ChatShell>);
+    expect(container.firstChild).toHaveClass("rounded-xl");
+    expect(container.firstChild).toHaveClass("border");
+  });
+
+  it("drops the frame in the bare variant (no second box inside a bounded region)", () => {
+    const { container } = render(<ChatShell variant="bare">t</ChatShell>);
+    expect(container.firstChild).not.toHaveClass("rounded-xl");
+    expect(container.firstChild).not.toHaveClass("border");
+  });
+
+  it("drops the header/composer dividers in the bare variant", () => {
+    const { container } = render(
+      <ChatShell variant="bare" header={<span>h</span>} composer={<span>c</span>}>
+        t
+      </ChatShell>,
+    );
+    expect(container.querySelector(".border-b")).toBeNull();
+    expect(container.querySelector(".border-t")).toBeNull();
+  });
+
+  it("makes the bare variant's edge scrims inert (aria-hidden AND pointer-events-none)", () => {
+    const { container } = render(<ChatShell variant="bare">t</ChatShell>);
+    const scrims = container.querySelectorAll("[aria-hidden='true']");
+    expect(scrims).toHaveLength(2);
+    for (const scrim of scrims) expect(scrim).toHaveClass("pointer-events-none");
+  });
+
+  it("renders no scrims in the card variant (there is a real divider instead)", () => {
+    const { container } = render(<ChatShell>t</ChatShell>);
+    expect(container.querySelectorAll("[aria-hidden='true']")).toHaveLength(0);
+  });
+});
+
+describe("ChatShell — composability", () => {
+  it("merges a caller className without dropping the fill-parent layout", () => {
+    const { container } = render(<ChatShell className="extra">t</ChatShell>);
+    expect(container.firstChild).toHaveClass("extra");
+    expect(container.firstChild).toHaveClass("h-full");
+  });
+});

package/src/chat-shell.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export interface ChatShellProps {
+  /** Scrollable transcript — typically a <Conversation>. */
+  children: ReactNode;
+  /** Sticky composer — typically a <Composer> (the standard chat input). */
+  composer?: ReactNode;
+  /** Optional header row (title, model picker, actions). */
+  header?: ReactNode;
+  /** Optional right-side context rail (sources, files, memory). */
+  aside?: ReactNode;
+  /**
+   * Layout treatment:
+   * - `"card"` (default) — a self-contained rounded, bordered chat card. Use
+   *   when the shell sits on a page among other content and needs its own frame.
+   * - `"bare"` — an immersive pane that fills its container with NO frame: the
+   *   transcript fades under the header and above the composer (a token-driven
+   *   top/bottom scrim) and the composer floats on the pane background instead
+   *   of a hard bordered bar. Use when the shell already lives inside a bounded
+   *   region (an AppShell `SidebarInset`, a full-page workspace) so it doesn't
+   *   draw a redundant second frame.
+   */
+  variant?: "card" | "bare";
+  className?: string;
+}
+
+/**
+ * Layout shell for an AI chat built from the AI Elements: a header, a scrollable
+ * transcript (give it a <Conversation>, which is `flex-1`), a sticky composer
+ * (a <Composer>, the standard chat input), and an optional context rail. Fills
+ * its parent's height.
+ *
+ * Two layout modes (`variant`): a framed `"card"` for in-page use, and a
+ * frameless `"bare"` immersive pane for when the shell already sits inside a
+ * bounded region and a second frame would just read as boxy.
+ */
+export function ChatShell({
+  children,
+  composer,
+  header,
+  aside,
+  variant = "card",
+  className,
+}: ChatShellProps) {
+  const bare = variant === "bare";
+  return (
+    <div
+      className={cn(
+        "flex h-full min-h-0 w-full overflow-hidden bg-background",
+        bare ? null : "rounded-xl border",
+        className,
+      )}
+    >
+      <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+        {header ? (
+          <div className={cn("flex h-12 shrink-0 items-center px-4", bare ? null : "border-b")}>
+            {header}
+          </div>
+        ) : null}
+
+        {bare ? (
+          // Immersive transcript: the scroll area fades at both edges so content
+          // dissolves under the header and above the composer instead of hitting
+          // a hard bordered bar. The overlays are token-driven (`from-background`)
+          // so they fade to the shell's own ground in every theme, and inert
+          // (`pointer-events-none` + `aria-hidden`) so they never block scroll,
+          // steal a tap, or get announced.
+          <div className="relative flex min-h-0 flex-1 flex-col">
+            {children}
+            <div
+              aria-hidden
+              className="pointer-events-none absolute inset-x-0 top-0 z-10 h-8 bg-gradient-to-b from-background to-transparent"
+            />
+            <div
+              aria-hidden
+              className="pointer-events-none absolute inset-x-0 bottom-0 z-10 h-12 bg-gradient-to-t from-background to-transparent"
+            />
+          </div>
+        ) : (
+          <div className="flex min-h-0 flex-1 flex-col">{children}</div>
+        )}
+
+        {composer ? (
+          // Bare: the composer floats on the pane ground (transparent, no
+          // divider) above the fade; card: the classic bordered footer.
+          <div className={cn("shrink-0", bare ? "relative z-20 px-4 pb-4" : "border-t p-3")}>
+            {composer}
+          </div>
+        ) : null}
+      </div>
+      {aside ? <div className="hidden w-80 shrink-0 border-s lg:block">{aside}</div> : null}
+    </div>
+  );
+}