@elabs-ai/components-ai 4.0.0

package/src/context.tsx

@@ -0,0 +1,363 @@
+"use client";
+
+import { Button } from "@elabs-ai/components-ui";
+import { HoverCard, HoverCardContent, HoverCardTrigger } from "@elabs-ai/components-ui";
+import { Progress } from "@elabs-ai/components-ui";
+import { useLocale } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { LanguageModelUsage } from "ai";
+import type { ComponentProps } from "react";
+import { createContext, useContext, useMemo } from "react";
+import { getUsage } from "tokenlens";
+
+const PERCENT_MAX = 100;
+const ICON_RADIUS = 10;
+const ICON_VIEWBOX = 24;
+const ICON_CENTER = 12;
+const ICON_STROKE_WIDTH = 2;
+
+type ModelId = string;
+
+interface ContextSchema {
+  usedTokens: number;
+  maxTokens: number;
+  usage?: LanguageModelUsage;
+  modelId?: ModelId;
+}
+
+const ContextContext = createContext<ContextSchema | null>(null);
+
+const useContextValue = () => {
+  const context = useContext(ContextContext);
+
+  if (!context) {
+    throw new Error("Context components must be used within Context");
+  }
+
+  return context;
+};
+
+export type ContextProps = ComponentProps<typeof HoverCard> & ContextSchema;
+
+export const Context = ({ usedTokens, maxTokens, usage, modelId, ...props }: ContextProps) => {
+  const contextValue = useMemo(
+    () => ({ maxTokens, modelId, usage, usedTokens }),
+    [maxTokens, modelId, usage, usedTokens],
+  );
+
+  return (
+    <ContextContext.Provider value={contextValue}>
+      <HoverCard closeDelay={0} openDelay={0} {...props} />
+    </ContextContext.Provider>
+  );
+};
+
+const ContextIcon = () => {
+  const { t } = useLocale();
+  const { usedTokens, maxTokens } = useContextValue();
+  const circumference = 2 * Math.PI * ICON_RADIUS;
+  const usedPercent = usedTokens / maxTokens;
+  const dashOffset = circumference * (1 - usedPercent);
+
+  return (
+    <svg
+      aria-label={t("ai.context.usage")}
+      height="20"
+      role="img"
+      style={{ color: "currentcolor" }}
+      viewBox={`0 0 ${ICON_VIEWBOX} ${ICON_VIEWBOX}`}
+      width="20"
+    >
+      <circle
+        cx={ICON_CENTER}
+        cy={ICON_CENTER}
+        fill="none"
+        opacity="0.25"
+        r={ICON_RADIUS}
+        stroke="currentColor"
+        strokeWidth={ICON_STROKE_WIDTH}
+      />
+      <circle
+        cx={ICON_CENTER}
+        cy={ICON_CENTER}
+        fill="none"
+        opacity="0.7"
+        r={ICON_RADIUS}
+        stroke="currentColor"
+        strokeDasharray={`${circumference} ${circumference}`}
+        strokeDashoffset={dashOffset}
+        strokeLinecap="round"
+        strokeWidth={ICON_STROKE_WIDTH}
+        style={{ transform: "rotate(-90deg)", transformOrigin: "center" }}
+      />
+    </svg>
+  );
+};
+
+export type ContextTriggerProps = ComponentProps<typeof Button>;
+
+export const ContextTrigger = ({ children, ...props }: ContextTriggerProps) => {
+  const { formatNumber } = useLocale();
+  const { usedTokens, maxTokens } = useContextValue();
+  const usedPercent = usedTokens / maxTokens;
+  const renderedPercent = formatNumber(usedPercent, {
+    maximumFractionDigits: 1,
+    style: "percent",
+  });
+
+  return (
+    <HoverCardTrigger asChild>
+      {children ?? (
+        <Button type="button" variant="ghost" {...props}>
+          <span className="font-medium text-muted-foreground">{renderedPercent}</span>
+          <ContextIcon />
+        </Button>
+      )}
+    </HoverCardTrigger>
+  );
+};
+
+export type ContextContentProps = ComponentProps<typeof HoverCardContent>;
+
+export const ContextContent = ({ className, ...props }: ContextContentProps) => (
+  <HoverCardContent className={cn("min-w-60 divide-y overflow-hidden p-0", className)} {...props} />
+);
+
+export type ContextContentHeaderProps = ComponentProps<"div">;
+
+export const ContextContentHeader = ({
+  children,
+  className,
+  ...props
+}: ContextContentHeaderProps) => {
+  const { formatNumber } = useLocale();
+  const { usedTokens, maxTokens } = useContextValue();
+  const usedPercent = usedTokens / maxTokens;
+  const displayPct = formatNumber(usedPercent, {
+    maximumFractionDigits: 1,
+    style: "percent",
+  });
+  const used = formatNumber(usedTokens, {
+    notation: "compact",
+  });
+  const total = formatNumber(maxTokens, {
+    notation: "compact",
+  });
+
+  return (
+    <div className={cn("w-full space-y-2 p-3", className)} {...props}>
+      {children ?? (
+        <>
+          <div className="flex items-center justify-between gap-3 text-xs">
+            <p>{displayPct}</p>
+            <p className="font-mono text-muted-foreground">
+              {used} / {total}
+            </p>
+          </div>
+          <div className="space-y-2">
+            <Progress className="bg-muted" value={usedPercent * PERCENT_MAX} />
+          </div>
+        </>
+      )}
+    </div>
+  );
+};
+
+export type ContextContentBodyProps = ComponentProps<"div">;
+
+export const ContextContentBody = ({ children, className, ...props }: ContextContentBodyProps) => (
+  <div className={cn("w-full p-3", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type ContextContentFooterProps = ComponentProps<"div">;
+
+export const ContextContentFooter = ({
+  children,
+  className,
+  ...props
+}: ContextContentFooterProps) => {
+  const { formatNumber } = useLocale();
+  const { modelId, usage } = useContextValue();
+  const costUSD = modelId
+    ? getUsage({
+        modelId,
+        usage: {
+          input: usage?.inputTokens ?? 0,
+          output: usage?.outputTokens ?? 0,
+        },
+      }).costUSD?.totalUSD
+    : undefined;
+  const totalCost = formatNumber(costUSD ?? 0, {
+    currency: "USD",
+    style: "currency",
+  });
+
+  return (
+    <div
+      className={cn(
+        "flex w-full items-center justify-between gap-3 bg-secondary p-3 text-xs",
+        className,
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <span className="text-muted-foreground">Total cost</span>
+          <span>{totalCost}</span>
+        </>
+      )}
+    </div>
+  );
+};
+
+const TokensWithCost = ({ tokens, costText }: { tokens?: number; costText?: string }) => {
+  const { formatNumber } = useLocale();
+  return (
+    <span>
+      {tokens === undefined ? "—" : formatNumber(tokens, { notation: "compact" })}
+      {costText ? <span className="ms-2 text-muted-foreground">• {costText}</span> : null}
+    </span>
+  );
+};
+
+export type ContextInputUsageProps = ComponentProps<"div">;
+
+export const ContextInputUsage = ({ className, children, ...props }: ContextInputUsageProps) => {
+  const { formatNumber } = useLocale();
+  const { usage, modelId } = useContextValue();
+  const inputTokens = usage?.inputTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!inputTokens) {
+    return null;
+  }
+
+  const inputCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { input: inputTokens, output: 0 },
+      }).costUSD?.totalUSD
+    : undefined;
+  const inputCostText = formatNumber(inputCost ?? 0, {
+    currency: "USD",
+    style: "currency",
+  });
+
+  return (
+    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
+      <span className="text-muted-foreground">Input</span>
+      <TokensWithCost costText={inputCostText} tokens={inputTokens} />
+    </div>
+  );
+};
+
+export type ContextOutputUsageProps = ComponentProps<"div">;
+
+export const ContextOutputUsage = ({ className, children, ...props }: ContextOutputUsageProps) => {
+  const { formatNumber } = useLocale();
+  const { usage, modelId } = useContextValue();
+  const outputTokens = usage?.outputTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!outputTokens) {
+    return null;
+  }
+
+  const outputCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { input: 0, output: outputTokens },
+      }).costUSD?.totalUSD
+    : undefined;
+  const outputCostText = formatNumber(outputCost ?? 0, {
+    currency: "USD",
+    style: "currency",
+  });
+
+  return (
+    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
+      <span className="text-muted-foreground">Output</span>
+      <TokensWithCost costText={outputCostText} tokens={outputTokens} />
+    </div>
+  );
+};
+
+export type ContextReasoningUsageProps = ComponentProps<"div">;
+
+export const ContextReasoningUsage = ({
+  className,
+  children,
+  ...props
+}: ContextReasoningUsageProps) => {
+  const { formatNumber } = useLocale();
+  const { usage, modelId } = useContextValue();
+  const reasoningTokens = usage?.reasoningTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!reasoningTokens) {
+    return null;
+  }
+
+  const reasoningCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { reasoningTokens },
+      }).costUSD?.totalUSD
+    : undefined;
+  const reasoningCostText = formatNumber(reasoningCost ?? 0, {
+    currency: "USD",
+    style: "currency",
+  });
+
+  return (
+    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
+      <span className="text-muted-foreground">Reasoning</span>
+      <TokensWithCost costText={reasoningCostText} tokens={reasoningTokens} />
+    </div>
+  );
+};
+
+export type ContextCacheUsageProps = ComponentProps<"div">;
+
+export const ContextCacheUsage = ({ className, children, ...props }: ContextCacheUsageProps) => {
+  const { formatNumber } = useLocale();
+  const { usage, modelId } = useContextValue();
+  const cacheTokens = usage?.cachedInputTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!cacheTokens) {
+    return null;
+  }
+
+  const cacheCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { cacheReads: cacheTokens, input: 0, output: 0 },
+      }).costUSD?.totalUSD
+    : undefined;
+  const cacheCostText = formatNumber(cacheCost ?? 0, {
+    currency: "USD",
+    style: "currency",
+  });
+
+  return (
+    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
+      <span className="text-muted-foreground">Cache</span>
+      <TokensWithCost costText={cacheCostText} tokens={cacheTokens} />
+    </div>
+  );
+};

package/src/controls.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import type { Controls as ControlsPrimitive } from "@xyflow/react";
+import type { ComponentProps } from "react";
+import { Suspense } from "react";
+
+import { lazyFlowPart } from "./_flow-lazy";
+
+export type ControlsProps = ComponentProps<typeof ControlsPrimitive>;
+
+/** React Flow lives behind a dynamic import — see `_flow-lazy.ts` and ADR 0019. */
+const ControlsImpl = lazyFlowPart<ControlsProps>((m) => m.Controls);
+
+export const Controls = (props: ControlsProps) => (
+  // 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}>
+    <ControlsImpl {...props} />
+  </Suspense>
+);

package/src/conversation.stories.tsx

@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Conversation, ConversationContent } from "./conversation";
+import { Message, MessageContent } from "./message";
+const meta = {
+  title: "AI/Conversation",
+  component: Conversation,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Conversation>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <div className="flex h-72 flex-col rounded-lg border">
+      <Conversation>
+        <ConversationContent>
+          <Message from="user">
+            <MessageContent>Hello</MessageContent>
+          </Message>
+          <Message from="assistant">
+            <MessageContent>Hi! How can I help with your deploys today?</MessageContent>
+          </Message>
+        </ConversationContent>
+      </Conversation>
+    </div>
+  ),
+};

package/src/conversation.test.tsx

@@ -0,0 +1,123 @@
+/**
+ * conversation.test.tsx — smoke + a11y/serialization lock for the transcript (#59).
+ *
+ * `Conversation` is the scroll container every chat message renders into. Two
+ * things must not regress: the container keeps `role="log"` (an incrementally
+ * updated region — this is what makes a streaming transcript announceable at
+ * all), and `messagesToMarkdown` — the download path's serializer — flattens
+ * `UIMessage.parts` correctly, since a broken export silently ships an empty or
+ * mangled file rather than throwing.
+ *
+ * Nothing is mocked: the real `StickToBottom`-backed component is rendered.
+ */
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import type { UIMessage } from "ai";
+import {
+  Conversation,
+  ConversationContent,
+  ConversationEmptyState,
+  messagesToMarkdown,
+} from "./conversation";
+
+const messages: UIMessage[] = [
+  { id: "1", role: "user", parts: [{ type: "text", text: "What changed?" }] },
+  {
+    id: "2",
+    role: "assistant",
+    parts: [
+      { type: "text", text: "Three services shipped." },
+      { type: "text", text: " Billing is degraded." },
+    ],
+  },
+];
+
+describe("Conversation — transcript region", () => {
+  it('exposes the transcript as role="log" (an incrementally updated region)', () => {
+    render(
+      <Conversation>
+        <ConversationContent>
+          <p>hello</p>
+        </ConversationContent>
+      </Conversation>,
+    );
+    expect(screen.getByRole("log")).toBeInTheDocument();
+  });
+
+  it("renders its children inside the log, in order", () => {
+    render(
+      <Conversation>
+        <ConversationContent>
+          <p>first</p>
+          <p>second</p>
+        </ConversationContent>
+      </Conversation>,
+    );
+    const log = screen.getByRole("log");
+    expect(log).toHaveTextContent("first");
+    expect(log).toHaveTextContent("second");
+    const [first, second] = [screen.getByText("first"), screen.getByText("second")];
+    expect(first.compareDocumentPosition(second) & 4).toBeTruthy();
+  });
+
+  it("merges a caller className without dropping the flex-fill layout", () => {
+    render(
+      <Conversation className="extra">
+        <ConversationContent>x</ConversationContent>
+      </Conversation>,
+    );
+    expect(screen.getByRole("log")).toHaveClass("extra");
+    expect(screen.getByRole("log")).toHaveClass("flex-1");
+  });
+});
+
+describe("ConversationEmptyState", () => {
+  it("renders a real empty state by default, not a blank region", () => {
+    render(<ConversationEmptyState />);
+    expect(screen.getByRole("heading", { name: "No messages yet" })).toBeInTheDocument();
+    expect(screen.getByText("Start a conversation to see messages here")).toBeInTheDocument();
+  });
+
+  it("accepts an overriding title/description", () => {
+    render(<ConversationEmptyState title="Ask anything" description="Try a question." />);
+    expect(screen.getByRole("heading", { name: "Ask anything" })).toBeInTheDocument();
+    expect(screen.getByText("Try a question.")).toBeInTheDocument();
+  });
+
+  it("lets children replace the default anatomy entirely", () => {
+    render(
+      <ConversationEmptyState>
+        <p>custom</p>
+      </ConversationEmptyState>,
+    );
+    expect(screen.getByText("custom")).toBeInTheDocument();
+    expect(screen.queryByRole("heading", { name: "No messages yet" })).toBeNull();
+  });
+});
+
+describe("messagesToMarkdown — the download serializer", () => {
+  it("labels each message by role and joins every text part", () => {
+    expect(messagesToMarkdown(messages)).toBe(
+      "**User:** What changed?\n\n**Assistant:** Three services shipped. Billing is degraded.",
+    );
+  });
+
+  it("skips non-text parts rather than emitting [object Object]", () => {
+    const withTool: UIMessage[] = [
+      {
+        id: "1",
+        role: "assistant",
+        parts: [{ type: "step-start" }, { type: "text", text: "Done." }],
+      },
+    ];
+    expect(messagesToMarkdown(withTool)).toBe("**Assistant:** Done.");
+  });
+
+  it("honours a custom formatter", () => {
+    expect(messagesToMarkdown(messages, (m) => m.role)).toBe("user\n\nassistant");
+  });
+
+  it("returns an empty string for an empty transcript", () => {
+    expect(messagesToMarkdown([])).toBe("");
+  });
+});

package/src/conversation.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { Button, downloadBlob } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { UIMessage } from "ai";
+import { ArrowDownIcon, DownloadIcon } from "lucide-react";
+import type { ComponentProps } from "react";
+import { useCallback } from "react";
+import { StickToBottom, useStickToBottomContext } from "use-stick-to-bottom";
+
+export type ConversationProps = ComponentProps<typeof StickToBottom>;
+
+export const Conversation = ({ className, ...props }: ConversationProps) => (
+  <StickToBottom
+    className={cn("relative flex-1 overflow-y-hidden", className)}
+    initial="smooth"
+    resize="smooth"
+    role="log"
+    {...props}
+  />
+);
+
+export type ConversationContentProps = ComponentProps<typeof StickToBottom.Content>;
+
+export const ConversationContent = ({ className, ...props }: ConversationContentProps) => (
+  <StickToBottom.Content className={cn("flex flex-col gap-8 p-4", className)} {...props} />
+);
+
+export type ConversationEmptyStateProps = ComponentProps<"div"> & {
+  title?: string;
+  description?: string;
+  icon?: React.ReactNode;
+};
+
+export const ConversationEmptyState = ({
+  className,
+  title = "No messages yet",
+  description = "Start a conversation to see messages here",
+  icon,
+  children,
+  ...props
+}: ConversationEmptyStateProps) => (
+  <div
+    className={cn(
+      "flex size-full flex-col items-center justify-center gap-3 p-8 text-center",
+      className,
+    )}
+    {...props}
+  >
+    {children ?? (
+      <>
+        {icon && <div className="text-muted-foreground">{icon}</div>}
+        <div className="space-y-1">
+          <h3 className="font-medium text-sm">{title}</h3>
+          {description && <p className="text-muted-foreground text-sm">{description}</p>}
+        </div>
+      </>
+    )}
+  </div>
+);
+
+export type ConversationScrollButtonProps = ComponentProps<typeof Button>;
+
+export const ConversationScrollButton = ({
+  className,
+  ...props
+}: ConversationScrollButtonProps) => {
+  const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+
+  const handleScrollToBottom = useCallback(() => {
+    scrollToBottom();
+  }, [scrollToBottom]);
+
+  return (
+    !isAtBottom && (
+      <Button
+        className={cn(
+          "absolute bottom-4 left-[50%] translate-x-[-50%] rounded-full dark:bg-background dark:hover:bg-muted",
+          className,
+        )}
+        onClick={handleScrollToBottom}
+        size="icon"
+        type="button"
+        variant="outline"
+        {...props}
+      >
+        <ArrowDownIcon className="size-4" />
+      </Button>
+    )
+  );
+};
+
+const getMessageText = (message: UIMessage): string =>
+  message.parts
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("");
+
+export type ConversationDownloadProps = Omit<ComponentProps<typeof Button>, "onClick"> & {
+  messages: UIMessage[];
+  filename?: string;
+  formatMessage?: (message: UIMessage, index: number) => string;
+};
+
+const defaultFormatMessage = (message: UIMessage): string => {
+  const roleLabel = message.role.charAt(0).toUpperCase() + message.role.slice(1);
+  return `**${roleLabel}:** ${getMessageText(message)}`;
+};
+
+export const messagesToMarkdown = (
+  messages: UIMessage[],
+  formatMessage: (message: UIMessage, index: number) => string = defaultFormatMessage,
+): string => messages.map((msg, i) => formatMessage(msg, i)).join("\n\n");
+
+export const ConversationDownload = ({
+  messages,
+  filename = "conversation.md",
+  formatMessage = defaultFormatMessage,
+  className,
+  children,
+  ...props
+}: ConversationDownloadProps) => {
+  const handleDownload = useCallback(() => {
+    const markdown = messagesToMarkdown(messages, formatMessage);
+    downloadBlob(new Blob([markdown], { type: "text/markdown" }), filename);
+  }, [messages, filename, formatMessage]);
+
+  return (
+    <Button
+      className={cn(
+        "absolute top-4 end-4 rounded-full dark:bg-background dark:hover:bg-muted",
+        className,
+      )}
+      onClick={handleDownload}
+      size="icon"
+      type="button"
+      variant="outline"
+      {...props}
+    >
+      {children ?? <DownloadIcon className="size-4" />}
+    </Button>
+  );
+};