@elabs-ai/components-ai 4.0.0

package/src/persona.test.tsx

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+import { PERSONA_SOURCES, Persona } from "./persona";
+
+describe("Persona — remote artwork escape hatches", () => {
+  it("renders a fallback rather than an empty box before the Rive chunk loads", () => {
+    // The Rive runtime is behind `lazy()`, so the first frame is always the
+    // Suspense fallback. Previously a blocked `.riv` left a bare 64px void.
+    const { container } = render(<Persona state="idle" src="about:blank#offline" />);
+    expect(container.firstElementChild).not.toBeNull();
+    // The visually-hidden status announcement is the only text content now.
+    expect(container.textContent).toBe("Assistant idle");
+    expect(container.querySelector('[aria-hidden="true"]')).not.toBeNull();
+  });
+
+  it("renders a caller-supplied fallback", () => {
+    render(<Persona state="idle" src="about:blank#offline" fallback={<span>resting</span>} />);
+    expect(screen.getByText("resting")).toBeInTheDocument();
+  });
+
+  it("throws on an unknown variant, as before", () => {
+    expect(() =>
+      // @ts-expect-error — deliberately invalid variant
+      render(<Persona state="idle" variant="nope" />),
+    ).toThrow(/Invalid variant/);
+  });
+});
+
+describe("Persona — state announced to assistive tech", () => {
+  it("announces a localized status for the current state", () => {
+    render(<Persona state="thinking" src="about:blank#offline" />);
+    expect(screen.getByRole("status")).toHaveTextContent("Assistant thinking…");
+  });
+
+  it("updates the SAME live region rather than remounting it when state changes", () => {
+    const { rerender } = render(<Persona state="thinking" src="about:blank#offline" />);
+    const region = screen.getByRole("status");
+    expect(region).toHaveTextContent("Assistant thinking…");
+
+    rerender(<Persona state="speaking" src="about:blank#offline" />);
+    expect(screen.getByRole("status")).toBe(region);
+    expect(region).toHaveTextContent("Assistant speaking");
+  });
+
+  it("renders no status region when statusLabel is explicitly null", () => {
+    render(<Persona state="thinking" src="about:blank#offline" statusLabel={null} />);
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+
+  it("renders a caller-supplied statusLabel instead of the default", () => {
+    render(
+      <Persona state="thinking" src="about:blank#offline" statusLabel={<span>Working</span>} />,
+    );
+    expect(screen.getByRole("status")).toHaveTextContent("Working");
+  });
+});
+
+describe("PERSONA_SOURCES", () => {
+  it("is exported so consumers can self-host every artwork file", () => {
+    const variants = Object.keys(PERSONA_SOURCES);
+    expect(variants).toHaveLength(6);
+    for (const source of Object.values(PERSONA_SOURCES)) {
+      expect(source.source).toMatch(/^https:\/\/.*\.riv$/);
+    }
+  });
+});

package/src/persona.tsx

@@ -0,0 +1,148 @@
+"use client";
+
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useLocale } from "@elabs-ai/components-ui";
+import type { RiveParameters } from "@rive-app/react-webgl2";
+import type { FC, ReactNode } from "react";
+import { lazy, memo, Suspense, useCallback, useState } from "react";
+
+import { PERSONA_SOURCES, type PersonaState, type PersonaVariant } from "./persona-sources";
+
+export { PERSONA_SOURCES };
+export type { PersonaState, PersonaVariant };
+
+/**
+ * The Rive runtime lives behind a dynamic import — `@rive-app/react-webgl2`
+ * declares no `sideEffects`, so a static import would put the whole WebGL2
+ * runtime and its `.wasm` in every consumer's entry chunk, `Persona` rendered or
+ * not. `RiveParameters` above is a TYPE import and erases. See ADR 0019.
+ */
+const PersonaRive = lazy(() => import("./_persona-rive"));
+
+/**
+ * Localized status announced when `state` changes, one key per `PersonaState`.
+ * Typed as a `Record` (not a bare template string) so a `PersonaState` value
+ * added later without a matching key here fails to typecheck.
+ */
+const PERSONA_STATE_KEYS: Record<PersonaState, string> = {
+  idle: "ai.persona.idle",
+  listening: "ai.persona.listening",
+  thinking: "ai.persona.thinking",
+  speaking: "ai.persona.speaking",
+  asleep: "ai.persona.asleep",
+};
+
+export interface PersonaProps {
+  className?: string;
+  /**
+   * Rendered while the artwork loads, and permanently if it fails (blocked by a
+   * `connect-src` CSP, offline, or a bad `src`). Defaults to a token-driven orb,
+   * so a blocked fetch never leaves an empty box.
+   */
+  fallback?: ReactNode;
+  onLoad?: RiveParameters["onLoad"];
+  onLoadError?: RiveParameters["onLoadError"];
+  onPause?: RiveParameters["onPause"];
+  onPlay?: RiveParameters["onPlay"];
+  onReady?: () => void;
+  onStop?: RiveParameters["onStop"];
+  /**
+   * Override the `.riv` artwork URL — point at a self-hosted copy when a CSP
+   * blocks the default origin. Defaults to `PERSONA_SOURCES[variant].source`.
+   * Mirrors the `mapStyle` override on `MapCanvas`.
+   */
+  src?: string;
+  state: PersonaState;
+  /**
+   * Visually-hidden text announced when `state` changes. Defaults to a
+   * localized label for the current `state`; pass `null` when the consuming
+   * surface already renders its own `role="status"` line, so AT is not told
+   * twice.
+   */
+  statusLabel?: ReactNode | null;
+  variant?: PersonaVariant;
+}
+
+/**
+ * The offline/blocked stand-in: a token-driven orb.
+ *
+ * Opacity-only pulse (no transform), neutralised under reduced motion.
+ */
+const PersonaFallback = ({ className }: { className?: string }) => (
+  <div
+    aria-hidden="true"
+    className={cn("grid size-16 shrink-0 place-items-center rounded-full bg-primary/10", className)}
+  >
+    <span className="size-6 animate-pulse rounded-full bg-primary/40 motion-reduce:animate-none" />
+  </div>
+);
+
+export const Persona: FC<PersonaProps> = memo(
+  ({
+    className,
+    fallback,
+    onLoad,
+    onLoadError,
+    onPause,
+    onPlay,
+    onReady,
+    onStop,
+    src,
+    state = "idle",
+    statusLabel,
+    variant = "obsidian",
+  }) => {
+    const source = PERSONA_SOURCES[variant];
+
+    if (!source) {
+      throw new Error(`Invalid variant: ${variant}`);
+    }
+
+    const { t } = useLocale();
+    const [failed, setFailed] = useState(false);
+
+    const handleLoadError = useCallback<NonNullable<RiveParameters["onLoadError"]>>(
+      (event) => {
+        setFailed(true);
+        onLoadError?.(event);
+      },
+      [onLoadError],
+    );
+
+    const placeholder = fallback ?? <PersonaFallback className={className} />;
+
+    const label = statusLabel === null ? null : (statusLabel ?? t(PERSONA_STATE_KEYS[state]));
+
+    const visual = failed ? (
+      placeholder
+    ) : (
+      <Suspense fallback={placeholder}>
+        <PersonaRive
+          className={className}
+          onLoad={onLoad}
+          onLoadError={handleLoadError}
+          onPause={onPause}
+          onPlay={onPlay}
+          onReady={onReady}
+          onStop={onStop}
+          source={source}
+          src={src ?? source.source}
+          state={state}
+        />
+      </Suspense>
+    );
+
+    return (
+      <>
+        {visual}
+        {label !== null && (
+          <span className="sr-only" role="status" aria-live="polite">
+            {label}
+          </span>
+        )}
+      </>
+    );
+  },
+);
+
+Persona.displayName = "Persona";

package/src/plan.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { Button } from "@elabs-ai/components-ui";
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "@elabs-ai/components-ui";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { ChevronsUpDownIcon } from "lucide-react";
+import type { ComponentProps } from "react";
+import { createContext, useContext, useMemo } from "react";
+
+import { Shimmer } from "./shimmer";
+
+interface PlanContextValue {
+  isStreaming: boolean;
+}
+
+const PlanContext = createContext<PlanContextValue | null>(null);
+
+const usePlan = () => {
+  const context = useContext(PlanContext);
+  if (!context) {
+    throw new Error("Plan components must be used within Plan");
+  }
+  return context;
+};
+
+export type PlanProps = ComponentProps<typeof Collapsible> & {
+  isStreaming?: boolean;
+};
+
+export const Plan = ({ className, isStreaming = false, children, ...props }: PlanProps) => {
+  const contextValue = useMemo(() => ({ isStreaming }), [isStreaming]);
+
+  return (
+    <PlanContext.Provider value={contextValue}>
+      <Collapsible asChild data-slot="plan" {...props}>
+        <Card className={cn("shadow-none", className)}>{children}</Card>
+      </Collapsible>
+    </PlanContext.Provider>
+  );
+};
+
+export type PlanHeaderProps = ComponentProps<typeof CardHeader>;
+
+export const PlanHeader = ({ className, ...props }: PlanHeaderProps) => (
+  <CardHeader
+    className={cn("flex items-start justify-between", className)}
+    data-slot="plan-header"
+    {...props}
+  />
+);
+
+export type PlanTitleProps = Omit<ComponentProps<typeof CardTitle>, "children"> & {
+  children: string;
+};
+
+export const PlanTitle = ({ children, ...props }: PlanTitleProps) => {
+  const { isStreaming } = usePlan();
+
+  return (
+    <CardTitle data-slot="plan-title" {...props}>
+      {isStreaming ? <Shimmer>{children}</Shimmer> : children}
+    </CardTitle>
+  );
+};
+
+export type PlanDescriptionProps = Omit<ComponentProps<typeof CardDescription>, "children"> & {
+  children: string;
+};
+
+export const PlanDescription = ({ className, children, ...props }: PlanDescriptionProps) => {
+  const { isStreaming } = usePlan();
+
+  return (
+    <CardDescription
+      className={cn("text-balance", className)}
+      data-slot="plan-description"
+      {...props}
+    >
+      {isStreaming ? <Shimmer>{children}</Shimmer> : children}
+    </CardDescription>
+  );
+};
+
+export type PlanActionProps = ComponentProps<typeof CardAction>;
+
+export const PlanAction = (props: PlanActionProps) => (
+  <CardAction data-slot="plan-action" {...props} />
+);
+
+export type PlanContentProps = ComponentProps<typeof CardContent>;
+
+export const PlanContent = ({ className, ...props }: PlanContentProps) => (
+  <CollapsibleContent asChild>
+    <CardContent
+      className={cn(
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=open]:slide-in-from-top-2 data-[state=closed]:slide-out-to-top-2 data-[state=closed]:fade-out-0 data-[state=open]:[--tw-ease:var(--ease-entrance)] data-[state=closed]:[--tw-ease:var(--ease-exit)] outline-none",
+        className,
+      )}
+      data-slot="plan-content"
+      {...props}
+    />
+  </CollapsibleContent>
+);
+
+export type PlanFooterProps = ComponentProps<"div">;
+
+export const PlanFooter = (props: PlanFooterProps) => (
+  <CardFooter data-slot="plan-footer" {...props} />
+);
+
+export type PlanTriggerProps = ComponentProps<typeof CollapsibleTrigger>;
+
+export const PlanTrigger = ({ className, ...props }: PlanTriggerProps) => (
+  <CollapsibleTrigger asChild>
+    <Button
+      className={cn("size-8", className)}
+      data-slot="plan-trigger"
+      size="icon"
+      variant="ghost"
+      {...props}
+    >
+      <ChevronsUpDownIcon className="size-4" />
+      <span className="sr-only">Toggle plan</span>
+    </Button>
+  </CollapsibleTrigger>
+);

package/src/prompt-input.stories.tsx

@@ -0,0 +1,261 @@
+/**
+ * PromptInput — the raw composer FORM primitive `Composer` is built on.
+ *
+ * Compose `PromptInputBody` / `PromptInputTextarea` / `PromptInputFooter` /
+ * `PromptInputTools` / `PromptInputSubmit` yourself when you need a bespoke
+ * shell; reach for `<Composer />` for the standard chat input.
+ *
+ * `tone` picks the inner well's fill: `"surface"` (default, muted — the look
+ * every existing usage keeps) or `"card"`, letting the well nest inside an
+ * already-tinted outer frame — the "double card" (#254) that `PromptInput`
+ * could not express before this prop existed. The `card` well's fill is
+ * theme-driven, not universally "white" — raised (lighter than the outer
+ * frame) on light themes, recessed (darker) on dark; see the
+ * `tone` prop doc.
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, waitFor } from "storybook/test";
+
+import {
+  PromptInput,
+  PromptInputBody,
+  PromptInputFooter,
+  PromptInputProvider,
+  PromptInputStop,
+  PromptInputSubmit,
+  PromptInputTextarea,
+  PromptInputTools,
+} from "./prompt-input";
+
+const meta = {
+  title: "AI/PromptInput",
+  component: PromptInput,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The raw composer FORM primitive Composer is built on. `tone` picks the inner well's fill — `surface` (default, muted) or `card` — so it can nest inside an already-tinted outer frame (the double card, #254). The `card` fill is theme-driven, not universally white: raised on light themes, recessed on dark — still a distinct, legible tone against the outer frame in every theme.",
+      },
+    },
+  },
+  args: {
+    onSubmit: () => undefined,
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof PromptInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The default `surface` (muted) inner well — the look every existing usage keeps. */
+export const Default: Story = {
+  render: (args) => (
+    <div className="mx-auto max-w-2xl">
+      <PromptInput {...args}>
+        <PromptInputBody>
+          <PromptInputTextarea />
+        </PromptInputBody>
+        <PromptInputFooter>
+          <PromptInputTools />
+          <PromptInputSubmit />
+        </PromptInputFooter>
+      </PromptInput>
+    </div>
+  ),
+};
+
+/**
+ * The "double card" (#254): a tinted `bg-surface-muted` outer frame around a
+ * `tone="card"` well. Raised (lighter than the frame) on light themes,
+ * recessed (darker) on dark — check both themes here, not
+ * just the light default.
+ */
+export const DoubleCardToned: Story = {
+  render: (args) => (
+    <div className="mx-auto max-w-2xl rounded-xl bg-surface-muted p-1.5">
+      <PromptInput {...args} tone="card">
+        <PromptInputBody>
+          <PromptInputTextarea />
+        </PromptInputBody>
+        <PromptInputFooter>
+          <PromptInputTools />
+          <PromptInputSubmit />
+        </PromptInputFooter>
+      </PromptInput>
+    </div>
+  ),
+};
+
+/* -------------------------------------------------------------------------- */
+/*  PromptInputSubmit — the merged primary-action contract (#351)             */
+/*                                                                            */
+/*  1. ready/undefined/error       -> Send (unchanged)                       */
+/*  2. running + composer EMPTY    -> Stop (unchanged)                       */
+/*  3. running + composer NON-EMPTY -> Send (the fix — a follow-up can       */
+/*     always be composed and submitted mid-turn; brand-ui never asserts     */
+/*     what the app's onSubmit does with it — that's the app's call, D5)     */
+/*  4. a PromptInputStop mounted alongside -> this control is ALWAYS Send    */
+/* -------------------------------------------------------------------------- */
+
+/** At rest: Send, disabled until there is text or an attachment. */
+export const Idle: Story = {
+  args: { onSubmit: fn() },
+  render: (args) => (
+    <div className="mx-auto max-w-2xl">
+      <PromptInput {...args}>
+        <PromptInputBody>
+          <PromptInputTextarea />
+        </PromptInputBody>
+        <PromptInputFooter>
+          <PromptInputTools />
+          <PromptInputSubmit />
+        </PromptInputFooter>
+      </PromptInput>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const send = await canvas.findByRole("button", { name: "Submit" });
+    // `aria-disabled`, not the native `disabled` attribute — see the comment
+    // on PromptInputSubmit (prompt-input.tsx) and the "Nothing to submit"
+    // exception in .claude/rules/interaction-guidelines.md: a natively
+    // disabled control is dropped from the focus order and strands keyboard
+    // users right after a keyboard-initiated send.
+    await expect(send).toHaveAttribute("aria-disabled", "true");
+  },
+};
+
+// `onStop` isn't a `PromptInput` prop, so it can't live in typed `args` —
+// each story below keeps its own module-scoped mock, set in `render` and
+// read back in `play`.
+let runningEmptyOnStop: ReturnType<typeof fn>;
+
+/** Running, composer empty — the control IS the Stop affordance (unchanged). */
+export const RunningEmpty: Story = {
+  args: { onSubmit: fn() },
+  render: (args) => {
+    runningEmptyOnStop = fn();
+    return (
+      <div className="mx-auto max-w-2xl">
+        <PromptInput {...args}>
+          <PromptInputBody>
+            <PromptInputTextarea />
+          </PromptInputBody>
+          <PromptInputFooter>
+            <PromptInputTools />
+            <PromptInputSubmit status="streaming" onStop={runningEmptyOnStop} />
+          </PromptInputFooter>
+        </PromptInput>
+      </div>
+    );
+  },
+  play: async ({ canvas, args }) => {
+    const stop = await canvas.findByRole("button", { name: "Stop" });
+    await expect(stop).toHaveAttribute("data-action", "stop");
+    await stop.click();
+    await waitFor(() => expect(runningEmptyOnStop).toHaveBeenCalledTimes(1));
+    await expect(args.onSubmit).not.toHaveBeenCalled();
+  },
+};
+
+let runningWithDraftOnStop: ReturnType<typeof fn>;
+
+/**
+ * Running, but the user has typed a follow-up — the P0 fix. The control flips
+ * back to Send so the draft can always be submitted mid-turn; brand-ui never
+ * asserts what `onSubmit` does with it (queue, interleave — the app decides).
+ */
+export const RunningWithDraft: Story = {
+  args: { onSubmit: fn() },
+  render: (args) => {
+    runningWithDraftOnStop = fn();
+    return (
+      <div className="mx-auto max-w-2xl">
+        <PromptInputProvider initialInput="What about the edge cases?">
+          <PromptInput {...args}>
+            <PromptInputBody>
+              <PromptInputTextarea />
+            </PromptInputBody>
+            <PromptInputFooter>
+              <PromptInputTools />
+              <PromptInputSubmit status="streaming" onStop={runningWithDraftOnStop} />
+            </PromptInputFooter>
+          </PromptInput>
+        </PromptInputProvider>
+      </div>
+    );
+  },
+  play: async ({ canvas, args }) => {
+    const send = await canvas.findByRole("button", { name: "Submit" });
+    await expect(send).toHaveAttribute("data-action", "send");
+    await expect(send).not.toHaveAttribute("data-generating");
+    await send.click();
+    await waitFor(() => expect(args.onSubmit).toHaveBeenCalledTimes(1));
+    await expect(runningWithDraftOnStop).not.toHaveBeenCalled();
+  },
+};
+
+/** Failed — an X that stays clickable so the user can retry. */
+export const ErrorState: Story = {
+  args: { onSubmit: fn() },
+  render: (args) => (
+    <div className="mx-auto max-w-2xl">
+      <PromptInput {...args}>
+        <PromptInputBody>
+          <PromptInputTextarea />
+        </PromptInputBody>
+        <PromptInputFooter>
+          <PromptInputTools />
+          <PromptInputSubmit status="error" />
+        </PromptInputFooter>
+      </PromptInput>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const send = await canvas.findByRole("button", { name: "Submit" });
+    await expect(send).toBeEnabled();
+  },
+};
+
+let separateStopControlOnStop: ReturnType<typeof fn>;
+
+/**
+ * The composed "separate" arrangement: a dedicated `PromptInputStop` beside
+ * `PromptInputSubmit`. Never a `mode` prop (component-api.md bans behavioural
+ * modes) — compose the two controls instead. While `PromptInputStop` is
+ * mounted, `PromptInputSubmit` stays Send in every state; the dedicated
+ * control owns stopping.
+ */
+export const SeparateStopControl: Story = {
+  args: { onSubmit: fn() },
+  render: (args) => {
+    separateStopControlOnStop = fn();
+    return (
+      <div className="mx-auto max-w-2xl">
+        <PromptInput {...args}>
+          <PromptInputBody>
+            <PromptInputTextarea />
+          </PromptInputBody>
+          <PromptInputFooter>
+            <PromptInputTools />
+            <div className="flex items-center gap-1">
+              <PromptInputStop status="streaming" onStop={separateStopControlOnStop} />
+              <PromptInputSubmit status="streaming" onStop={separateStopControlOnStop} />
+            </div>
+          </PromptInputFooter>
+        </PromptInput>
+      </div>
+    );
+  },
+  play: async ({ canvas }) => {
+    const submit = await canvas.findByRole("button", { name: "Submit" });
+    await expect(submit).toHaveAttribute("data-action", "send");
+    // `aria-disabled`, not the native `disabled` attribute — see the Idle
+    // story above and prompt-input.tsx's PromptInputSubmit comment.
+    await expect(submit).toHaveAttribute("aria-disabled", "true");
+
+    const stop = await canvas.findByRole("button", { name: "Stop" });
+    await stop.click();
+    await waitFor(() => expect(separateStopControlOnStop).toHaveBeenCalledTimes(1));
+  },
+};