@elabs-ai/components-ai 4.0.0

package/src/package-info.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import { Badge } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { ArrowRightIcon, MinusIcon, PackageIcon, PlusIcon } from "lucide-react";
+import type { HTMLAttributes } from "react";
+import { createContext, useContext, useMemo } from "react";
+
+type ChangeType = "major" | "minor" | "patch" | "added" | "removed";
+
+interface PackageInfoContextType {
+  name: string;
+  currentVersion?: string;
+  newVersion?: string;
+  changeType?: ChangeType;
+}
+
+const PackageInfoContext = createContext<PackageInfoContextType>({
+  name: "",
+});
+
+export type PackageInfoHeaderProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoHeader = ({ className, children, ...props }: PackageInfoHeaderProps) => (
+  <div className={cn("flex items-center justify-between gap-2", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type PackageInfoNameProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoName = ({ className, children, ...props }: PackageInfoNameProps) => {
+  const { name } = useContext(PackageInfoContext);
+
+  return (
+    <div className={cn("flex items-center gap-2", className)} {...props}>
+      <PackageIcon className="size-4 text-muted-foreground" />
+      <span className="font-medium font-mono text-sm">{children ?? name}</span>
+    </div>
+  );
+};
+
+const changeTypeStyles: Record<ChangeType, string> = {
+  added: "bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400",
+  major: "bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400",
+  minor: "bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400",
+  patch: "bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400",
+  removed: "bg-gray-100 text-gray-700 dark:bg-gray-900/30 dark:text-gray-400",
+};
+
+const changeTypeIcons: Record<ChangeType, React.ReactNode> = {
+  added: <PlusIcon className="size-3" />,
+  major: <ArrowRightIcon className="size-3" />,
+  minor: <ArrowRightIcon className="size-3" />,
+  patch: <ArrowRightIcon className="size-3" />,
+  removed: <MinusIcon className="size-3" />,
+};
+
+export type PackageInfoChangeTypeProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoChangeType = ({
+  className,
+  children,
+  ...props
+}: PackageInfoChangeTypeProps) => {
+  const { changeType } = useContext(PackageInfoContext);
+
+  if (!changeType) {
+    return null;
+  }
+
+  return (
+    <Badge
+      className={cn("gap-1 text-xs capitalize", changeTypeStyles[changeType], className)}
+      variant="secondary"
+      {...props}
+    >
+      {changeTypeIcons[changeType]}
+      {children ?? changeType}
+    </Badge>
+  );
+};
+
+export type PackageInfoVersionProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoVersion = ({ className, children, ...props }: PackageInfoVersionProps) => {
+  const { currentVersion, newVersion } = useContext(PackageInfoContext);
+
+  if (!(currentVersion || newVersion)) {
+    return null;
+  }
+
+  return (
+    <div
+      className={cn(
+        "mt-2 flex items-center gap-2 font-mono text-muted-foreground text-sm",
+        className,
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          {currentVersion && <span>{currentVersion}</span>}
+          {currentVersion && newVersion && <ArrowRightIcon className="size-3" />}
+          {newVersion && <span className="font-medium text-foreground">{newVersion}</span>}
+        </>
+      )}
+    </div>
+  );
+};
+
+export type PackageInfoProps = HTMLAttributes<HTMLDivElement> & {
+  name: string;
+  currentVersion?: string;
+  newVersion?: string;
+  changeType?: ChangeType;
+};
+
+export const PackageInfo = ({
+  name,
+  currentVersion,
+  newVersion,
+  changeType,
+  className,
+  children,
+  ...props
+}: PackageInfoProps) => {
+  const contextValue = useMemo(
+    () => ({ changeType, currentVersion, name, newVersion }),
+    [changeType, currentVersion, name, newVersion],
+  );
+
+  return (
+    <PackageInfoContext.Provider value={contextValue}>
+      <div className={cn("rounded-lg border bg-background p-4", className)} {...props}>
+        {children ?? (
+          <>
+            <PackageInfoHeader>
+              <PackageInfoName />
+              {changeType && <PackageInfoChangeType />}
+            </PackageInfoHeader>
+            {(currentVersion || newVersion) && <PackageInfoVersion />}
+          </>
+        )}
+      </div>
+    </PackageInfoContext.Provider>
+  );
+};
+
+export type PackageInfoDescriptionProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const PackageInfoDescription = ({
+  className,
+  children,
+  ...props
+}: PackageInfoDescriptionProps) => (
+  <p className={cn("mt-2 text-muted-foreground text-sm", className)} {...props}>
+    {children}
+  </p>
+);
+
+export type PackageInfoContentProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoContent = ({ className, children, ...props }: PackageInfoContentProps) => (
+  <div className={cn("mt-3 border-t pt-3", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type PackageInfoDependenciesProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoDependencies = ({
+  className,
+  children,
+  ...props
+}: PackageInfoDependenciesProps) => (
+  <div className={cn("space-y-2", className)} {...props}>
+    <span className="font-medium text-muted-foreground text-xs uppercase tracking-wide">
+      Dependencies
+    </span>
+    <div className="space-y-1">{children}</div>
+  </div>
+);
+
+export type PackageInfoDependencyProps = HTMLAttributes<HTMLDivElement> & {
+  name: string;
+  version?: string;
+};
+
+export const PackageInfoDependency = ({
+  name,
+  version,
+  className,
+  children,
+  ...props
+}: PackageInfoDependencyProps) => (
+  <div className={cn("flex items-center justify-between text-sm", className)} {...props}>
+    {children ?? (
+      <>
+        <span className="font-mono text-muted-foreground">{name}</span>
+        {version && <span className="font-mono text-xs">{version}</span>}
+      </>
+    )}
+  </div>
+);

package/src/panel.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import type { Panel as PanelPrimitive } from "@xyflow/react";
+import type { ComponentProps } from "react";
+import { Suspense } from "react";
+
+import { lazyFlowPart } from "./_flow-lazy";
+
+export type PanelProps = ComponentProps<typeof PanelPrimitive>;
+
+/** React Flow lives behind a dynamic import — see `_flow-lazy.ts` and ADR 0019. */
+const PanelImpl = lazyFlowPart<PanelProps>((m) => m.Panel);
+
+export const Panel = (props: PanelProps) => (
+  // An overlay inside an already-loaded `<Canvas>`, so there is no box to
+  // reserve — the engine chunk it needs is the one the canvas already fetched.
+  <Suspense fallback={null}>
+    <PanelImpl {...props} />
+  </Suspense>
+);

package/src/part-groups.ts

@@ -0,0 +1,258 @@
+/**
+ * part-groups.ts — Pure, framework-free part-grouping engine.
+ *
+ * Derives collapsible reasoning/tool traces from an ordered list of message
+ * parts. This is a CLIENT-SIDE VIEW TRANSFORM — never a model output format.
+ * Adapted from assistant-ui's grouping design onto this library's idiom.
+ *
+ * `groupBy(part, context)` maps each part to a group-key path (`group-…`);
+ * ADJACENT parts sharing a key path coalesce into synthetic group nodes
+ * (`{ type: "group-…", status, indices }`); multi-element paths nest. The
+ * `group-` namespace is reserved so a group key can never collide with a real
+ * part `type`.
+ */
+
+/** A reserved group-key. The `group-` prefix can't collide with real part types. */
+export type GroupKey = `group-${string}`;
+
+/** Rolled-up status of a group (any member running → the group is running). */
+export type GroupStatus = "pending" | "running" | "complete" | "error";
+
+/** The minimum a groupable part must expose. */
+export interface GroupablePart {
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Context passed to `groupBy` for each part. */
+export interface GroupByContext<T extends GroupablePart> {
+  index: number;
+  parts: readonly T[];
+}
+
+/** Maps a part to its group-key path (`[]` = not grouped, a top-level leaf). */
+export type GroupBy<T extends GroupablePart> = (
+  part: T,
+  context: GroupByContext<T>,
+) => readonly GroupKey[];
+
+/** Extract a part's status; return `undefined` to fall back to the default. */
+export type GetPartStatus<T extends GroupablePart> = (part: T) => GroupStatus | undefined;
+
+/** The synthetic node produced for a coalesced group. */
+export interface PartGroupNode {
+  type: GroupKey;
+  status: GroupStatus;
+  /** Original indices of every leaf part under this group (recursive). */
+  indices: number[];
+}
+
+/** One node in the grouped tree — a leaf part or a synthetic group. */
+export type GroupedNode<T extends GroupablePart> =
+  | { kind: "leaf"; key: string; index: number; part: T }
+  | { kind: "group"; key: string; group: PartGroupNode; children: GroupedNode<T>[] };
+
+// ---------------------------------------------------------------------------
+// Default status extraction
+// ---------------------------------------------------------------------------
+
+const RUNNING_STATES = new Set([
+  "input-streaming",
+  "input-available",
+  "approval-requested",
+  "approval-responded",
+  "calling",
+  "streaming",
+  "in-progress",
+]);
+const ERROR_STATES = new Set(["output-error", "error", "failed"]);
+const COMPLETE_STATES = new Set(["output-available", "output-denied", "done", "complete"]);
+
+/**
+ * Best-effort status from common AI-SDK part shapes (tool `state`, reasoning
+ * `state`, `isStreaming`). Overridable via `getStatus`.
+ */
+export function defaultPartStatus(part: GroupablePart): GroupStatus {
+  if (part.isStreaming === true) return "running";
+  const state = typeof part.state === "string" ? part.state : undefined;
+  if (state) {
+    if (ERROR_STATES.has(state)) return "error";
+    if (RUNNING_STATES.has(state)) return "running";
+    if (COMPLETE_STATES.has(state)) return "complete";
+  }
+  if (part.errorText || part.error) return "error";
+  return "complete";
+}
+
+/** Roll several member statuses up into one group status. */
+export function rollupStatus(statuses: readonly GroupStatus[]): GroupStatus {
+  if (statuses.some((s) => s === "running")) return "running";
+  if (statuses.some((s) => s === "error")) return "error";
+  if (statuses.some((s) => s === "pending")) return "pending";
+  return "complete";
+}
+
+// ---------------------------------------------------------------------------
+// Stable identity keys
+// ---------------------------------------------------------------------------
+
+/** Stable leaf key so streaming rows don't remount (prefers a part id). */
+function leafKey(part: GroupablePart, index: number): string {
+  const id =
+    (typeof part.id === "string" && part.id) ||
+    (typeof part.toolCallId === "string" && part.toolCallId) ||
+    null;
+  return id ?? `${part.type}#${index}`;
+}
+
+// ---------------------------------------------------------------------------
+// Tree building
+// ---------------------------------------------------------------------------
+
+interface Entry<T extends GroupablePart> {
+  part: T;
+  index: number;
+  path: readonly GroupKey[];
+}
+
+function buildLevel<T extends GroupablePart>(
+  entries: Entry<T>[],
+  statusOf: (part: T) => GroupStatus,
+): GroupedNode<T>[] {
+  const out: GroupedNode<T>[] = [];
+  let i = 0;
+  while (i < entries.length) {
+    const entry = entries[i]!;
+    if (entry.path.length === 0) {
+      out.push({
+        kind: "leaf",
+        key: leafKey(entry.part, entry.index),
+        index: entry.index,
+        part: entry.part,
+      });
+      i += 1;
+      continue;
+    }
+
+    // Coalesce the adjacent run of entries sharing this level's key.
+    const key0 = entry.path[0]!;
+    const run: Entry<T>[] = [];
+    let j = i;
+    while (j < entries.length && entries[j]!.path.length > 0 && entries[j]!.path[0] === key0) {
+      run.push(entries[j]!);
+      j += 1;
+    }
+
+    // Recurse with each member's path shifted one level down (nesting).
+    const childEntries: Entry<T>[] = run.map((r) => ({
+      part: r.part,
+      index: r.index,
+      path: r.path.slice(1),
+    }));
+    const children = buildLevel(childEntries, statusOf);
+    const indices = run.map((r) => r.index);
+    const status = rollupStatus(run.map((r) => statusOf(r.part)));
+
+    out.push({
+      kind: "group",
+      // First member index keeps the group key stable across append-only streams.
+      key: `${key0}@${run[0]!.index}`,
+      group: { type: key0, status, indices },
+      children,
+    });
+    i = j;
+  }
+  return out;
+}
+
+/**
+ * Build the grouped tree from an ordered part list. Pure + deterministic —
+ * never throws. Adjacent parts with a shared group-key path coalesce; multi-key
+ * paths nest; ungrouped parts (path `[]`) stay as top-level leaves.
+ */
+export function buildPartGroups<T extends GroupablePart>(
+  parts: readonly T[],
+  groupBy: GroupBy<T>,
+  getStatus?: GetPartStatus<T>,
+): GroupedNode<T>[] {
+  const statusOf = (part: T): GroupStatus => getStatus?.(part) ?? defaultPartStatus(part);
+  const entries: Entry<T>[] = parts.map((part, index) => {
+    let path: readonly GroupKey[] = [];
+    try {
+      path = groupBy(part, { index, parts }) ?? [];
+    } catch {
+      path = []; // a throwing groupBy must not break the transcript
+    }
+    return { part, index, path };
+  });
+  return buildLevel(entries, statusOf);
+}
+
+/**
+ * A cheap fingerprint of the parts' identity + type + status. Feed it to a
+ * `useMemo` so the grouped tree only rebuilds when something structural
+ * changed — streaming token updates that don't change status won't churn it.
+ */
+export function partsFingerprint<T extends GroupablePart>(
+  parts: readonly T[],
+  getStatus?: GetPartStatus<T>,
+): string {
+  return parts
+    .map((part, index) => {
+      const status = getStatus?.(part) ?? defaultPartStatus(part);
+      return `${leafKey(part, index)}:${part.type}:${status}`;
+    })
+    .join("|");
+}
+
+// ---------------------------------------------------------------------------
+// groupPartByType — the default grouping strategy + classification hint
+// ---------------------------------------------------------------------------
+
+/** Whether a part folds into a trace (`inline`) or always stands alone. */
+export type PartDisplay = "inline" | "standalone";
+
+export interface GroupPartByTypeOptions<T extends GroupablePart> {
+  /** Group key for the collapsible trace. @default "group-work" */
+  groupKey?: GroupKey;
+  /** Part types folded into the trace. @default reasoning + tool-* + dynamic-tool + step-start */
+  inline?: (string | RegExp)[];
+  /** Part types forced standalone (never folded). @default approval / human / confirmation */
+  standalone?: (string | RegExp)[];
+  /** Explicit per-part classification; overrides the type lists. */
+  classify?: (part: T) => PartDisplay | undefined;
+}
+
+const DEFAULT_INLINE: (string | RegExp)[] = [/^reasoning$/, /^tool-/, "dynamic-tool", "step-start"];
+const DEFAULT_STANDALONE: (string | RegExp)[] = [/approval/i, /human/i, "confirmation"];
+
+function matchesAny(type: string, patterns: (string | RegExp)[]): boolean {
+  return patterns.some((p) => (typeof p === "string" ? p === type : p.test(type)));
+}
+
+/**
+ * Build a `groupBy` that folds reasoning/tool parts into ONE collapsible trace
+ * while forcing human/approval-style parts to stand alone — an interaction card
+ * must never fold into a thinking accordion. The classification maps to the
+ * `display: "inline" | "standalone"` hint.
+ */
+export function groupPartByType<T extends GroupablePart>(
+  options: GroupPartByTypeOptions<T> = {},
+): GroupBy<T> {
+  const groupKey = options.groupKey ?? "group-work";
+  const inline = options.inline ?? DEFAULT_INLINE;
+  const standalone = options.standalone ?? DEFAULT_STANDALONE;
+  return (part) => {
+    const explicit = options.classify?.(part);
+    if (explicit === "standalone") return [];
+    if (explicit === "inline") return [groupKey];
+    if (matchesAny(part.type, standalone)) return []; // forced standalone
+    if (matchesAny(part.type, inline)) return [groupKey];
+    return []; // ungrouped (text, sources, files, …) stays top-level
+  };
+}
+
+/** Type guard: is this render subject a synthetic group node? */
+export function isGroupNode(part: { type: string }): part is PartGroupNode {
+  return part.type.startsWith("group-");
+}

package/src/persona-sources.ts

@@ -0,0 +1,59 @@
+/**
+ * Persona artwork sources — a plain data module shared by `persona.tsx` (the
+ * public shell) and `_persona-rive.tsx` (the lazily-loaded Rive half), so
+ * neither has to import the other.
+ */
+
+export type PersonaState = "idle" | "listening" | "thinking" | "speaking" | "asleep";
+
+export interface PersonaSource {
+  /** The artwork exposes a colour view-model that follows the light/dark theme. */
+  dynamicColor: boolean;
+  /** The artwork has a Rive view-model (vs. a plain state machine). */
+  hasModel: boolean;
+  /** Absolute URL of the `.riv` artwork. */
+  source: string;
+}
+
+/**
+ * Where the shipped `.riv` artwork is fetched from.
+ *
+ * ⚠️ These are REMOTE origins fetched at runtime by the Rive runtime — a
+ * deployment with a restrictive `connect-src` blocks them, and the component
+ * falls back to a token-driven orb. Self-host the six files and pass
+ * `<Persona src={…}>` to point at your own copies. See `docs/CSP-AND-NETWORK.md`.
+ */
+export const PERSONA_SOURCES = {
+  command: {
+    dynamicColor: true,
+    hasModel: true,
+    source: "https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/command-2.0.riv",
+  },
+  glint: {
+    dynamicColor: true,
+    hasModel: true,
+    source: "https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/glint-2.0.riv",
+  },
+  halo: {
+    dynamicColor: true,
+    hasModel: true,
+    source: "https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/halo-2.0.riv",
+  },
+  mana: {
+    dynamicColor: false,
+    hasModel: true,
+    source: "https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/mana-2.0.riv",
+  },
+  obsidian: {
+    dynamicColor: true,
+    hasModel: true,
+    source: "https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/obsidian-2.0.riv",
+  },
+  opal: {
+    dynamicColor: false,
+    hasModel: false,
+    source: "https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/orb-1.2.riv",
+  },
+} as const satisfies Record<string, PersonaSource>;
+
+export type PersonaVariant = keyof typeof PERSONA_SOURCES;

package/src/persona.stories.tsx

@@ -0,0 +1,111 @@
+/**
+ * Persona — the animated agent presence.
+ *
+ * The artwork is a Rive `.riv` file fetched from a **remote origin** at runtime,
+ * and the WebGL2 runtime is loaded lazily (ADR 0019). Both facts matter for
+ * deployment: under a restrictive `connect-src` the fetch is blocked and the
+ * component falls back to a token-driven orb rather than an empty box. See
+ * `docs/CSP-AND-NETWORK.md`, and pass `src` to self-host the artwork.
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Persona, type PersonaState } from "./persona";
+
+/**
+ * The visible caption below mirrors the visually-hidden `role="status"` text
+ * `Persona` announces to assistive tech for each state (see `PersonaProps.statusLabel`).
+ */
+const STATUS_LABELS: Record<PersonaState, string> = {
+  idle: "Assistant idle",
+  listening: "Assistant listening",
+  thinking: "Assistant thinking…",
+  speaking: "Assistant speaking",
+  asleep: "Assistant asleep",
+};
+
+const meta = {
+  title: "AI/Persona",
+  component: Persona,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "The animated agent presence. Artwork is a remote Rive `.riv` file and the WebGL2 runtime loads lazily, so the first frame is the fallback orb. Pass `src` to self-host, `fallback` to replace the placeholder. Blocked/offline loads render the fallback instead of an empty box.",
+      },
+    },
+  },
+  args: { state: "idle" },
+  tags: ["autodocs"],
+} satisfies Meta<typeof Persona>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The offline / CSP-blocked state — and the default story on purpose.
+ *
+ * `src` points at a URL that cannot resolve, so this renders the fallback orb
+ * without reaching the network. Keeping the DEFAULT story offline means CI and
+ * the visual sweep never depend on a third-party origin being up.
+ */
+export const Default: Story = {
+  args: { src: "about:blank#persona-offline" },
+};
+
+/** An explicit custom fallback, for brands that want their own resting mark. */
+export const CustomFallback: Story = {
+  args: {
+    src: "about:blank#persona-offline",
+    fallback: (
+      <div className="grid size-16 place-items-center rounded-full border-2 border-primary/40 border-dashed">
+        <span className="text-meta text-muted-foreground">AI</span>
+      </div>
+    ),
+  },
+};
+
+/**
+ * Every conversational state, offline.
+ *
+ * With live artwork these animate; here they all show the fallback, which is
+ * exactly what a locked-down deployment sees. The caption under each orb is
+ * the SAME text `Persona` announces to assistive tech via its default
+ * `statusLabel` — shown visibly here purely for documentation.
+ */
+export const States: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-6">
+      {(["idle", "listening", "thinking", "speaking", "asleep"] as const).map((state) => (
+        <figure className="flex flex-col items-center gap-2" key={state}>
+          <Persona {...args} src="about:blank#persona-offline" state={state} />
+          <figcaption className="text-meta text-muted-foreground">
+            {state}
+            <br />
+            <span className="italic">{STATUS_LABELS[state]}</span>
+          </figcaption>
+        </figure>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * Opt out of the announcement with `statusLabel={null}` — for a surface that
+ * already renders its own `role="status"` line elsewhere (e.g. next to a
+ * chat composer) and doesn't want AT told twice.
+ */
+export const NoStatusAnnouncement: Story = {
+  args: { src: "about:blank#persona-offline", state: "thinking", statusLabel: null },
+};
+
+/**
+ * Live artwork from the default remote origin.
+ *
+ * ⚠️ This story REACHES THE NETWORK (`*.public.blob.vercel-storage.com`). It is
+ * the only one that does; it exists so the real animation can be reviewed, and
+ * it degrades to the fallback orb when the origin is unreachable.
+ */
+export const LiveRemoteArtwork: Story = {
+  args: { state: "thinking", variant: "obsidian" },
+};