@elabs-ai/components-ai 4.0.0 → 4.1.0

package/src/{context.tsx → token-usage.tsx}

@@ -18,50 +18,56 @@ const ICON_STROKE_WIDTH = 2;
 
 type ModelId = string;
 
-interface ContextSchema {
+interface TokenUsageSchema {
   usedTokens: number;
   maxTokens: number;
   usage?: LanguageModelUsage;
   modelId?: ModelId;
 }
 
-const ContextContext = createContext<ContextSchema | null>(null);
+const TokenUsageContext = createContext<TokenUsageSchema | null>(null);
 
-const useContextValue = () => {
-  const context = useContext(ContextContext);
+const useTokenUsageValue = () => {
+  const context = useContext(TokenUsageContext);
 
   if (!context) {
-    throw new Error("Context components must be used within Context");
+    throw new Error("TokenUsage components must be used within TokenUsage");
   }
 
   return context;
 };
 
-export type ContextProps = ComponentProps<typeof HoverCard> & ContextSchema;
+export type TokenUsageProps = ComponentProps<typeof HoverCard> & TokenUsageSchema;
 
-export const Context = ({ usedTokens, maxTokens, usage, modelId, ...props }: ContextProps) => {
+export const TokenUsage = ({
+  usedTokens,
+  maxTokens,
+  usage,
+  modelId,
+  ...props
+}: TokenUsageProps) => {
   const contextValue = useMemo(
     () => ({ maxTokens, modelId, usage, usedTokens }),
     [maxTokens, modelId, usage, usedTokens],
   );
 
   return (
-    <ContextContext.Provider value={contextValue}>
+    <TokenUsageContext.Provider value={contextValue}>
       <HoverCard closeDelay={0} openDelay={0} {...props} />
-    </ContextContext.Provider>
+    </TokenUsageContext.Provider>
   );
 };
 
-const ContextIcon = () => {
+const TokenUsageIcon = () => {
   const { t } = useLocale();
-  const { usedTokens, maxTokens } = useContextValue();
+  const { usedTokens, maxTokens } = useTokenUsageValue();
   const circumference = 2 * Math.PI * ICON_RADIUS;
   const usedPercent = usedTokens / maxTokens;
   const dashOffset = circumference * (1 - usedPercent);
 
   return (
     <svg
-      aria-label={t("ai.context.usage")}
+      aria-label={t("ai.tokenUsage.usage")}
       height="20"
       role="img"
       style={{ color: "currentcolor" }}
@@ -94,11 +100,11 @@ const ContextIcon = () => {
   );
 };
 
-export type ContextTriggerProps = ComponentProps<typeof Button>;
+export type TokenUsageTriggerProps = ComponentProps<typeof Button>;
 
-export const ContextTrigger = ({ children, ...props }: ContextTriggerProps) => {
+export const TokenUsageTrigger = ({ children, ...props }: TokenUsageTriggerProps) => {
   const { formatNumber } = useLocale();
-  const { usedTokens, maxTokens } = useContextValue();
+  const { usedTokens, maxTokens } = useTokenUsageValue();
   const usedPercent = usedTokens / maxTokens;
   const renderedPercent = formatNumber(usedPercent, {
     maximumFractionDigits: 1,
@@ -110,28 +116,28 @@ export const ContextTrigger = ({ children, ...props }: ContextTriggerProps) => {
       {children ?? (
         <Button type="button" variant="ghost" {...props}>
           <span className="font-medium text-muted-foreground">{renderedPercent}</span>
-          <ContextIcon />
+          <TokenUsageIcon />
         </Button>
       )}
     </HoverCardTrigger>
   );
 };
 
-export type ContextContentProps = ComponentProps<typeof HoverCardContent>;
+export type TokenUsageContentProps = ComponentProps<typeof HoverCardContent>;
 
-export const ContextContent = ({ className, ...props }: ContextContentProps) => (
+export const TokenUsageContent = ({ className, ...props }: TokenUsageContentProps) => (
   <HoverCardContent className={cn("min-w-60 divide-y overflow-hidden p-0", className)} {...props} />
 );
 
-export type ContextContentHeaderProps = ComponentProps<"div">;
+export type TokenUsageContentHeaderProps = ComponentProps<"div">;
 
-export const ContextContentHeader = ({
+export const TokenUsageContentHeader = ({
   children,
   className,
   ...props
-}: ContextContentHeaderProps) => {
+}: TokenUsageContentHeaderProps) => {
   const { formatNumber } = useLocale();
-  const { usedTokens, maxTokens } = useContextValue();
+  const { usedTokens, maxTokens } = useTokenUsageValue();
   const usedPercent = usedTokens / maxTokens;
   const displayPct = formatNumber(usedPercent, {
     maximumFractionDigits: 1,
@@ -163,23 +169,27 @@ export const ContextContentHeader = ({
   );
 };
 
-export type ContextContentBodyProps = ComponentProps<"div">;
+export type TokenUsageContentBodyProps = ComponentProps<"div">;
 
-export const ContextContentBody = ({ children, className, ...props }: ContextContentBodyProps) => (
+export const TokenUsageContentBody = ({
+  children,
+  className,
+  ...props
+}: TokenUsageContentBodyProps) => (
   <div className={cn("w-full p-3", className)} {...props}>
     {children}
   </div>
 );
 
-export type ContextContentFooterProps = ComponentProps<"div">;
+export type TokenUsageContentFooterProps = ComponentProps<"div">;
 
-export const ContextContentFooter = ({
+export const TokenUsageContentFooter = ({
   children,
   className,
   ...props
-}: ContextContentFooterProps) => {
-  const { formatNumber } = useLocale();
-  const { modelId, usage } = useContextValue();
+}: TokenUsageContentFooterProps) => {
+  const { formatNumber, t } = useLocale();
+  const { modelId, usage } = useTokenUsageValue();
   const costUSD = modelId
     ? getUsage({
         modelId,
@@ -204,7 +214,7 @@ export const ContextContentFooter = ({
     >
       {children ?? (
         <>
-          <span className="text-muted-foreground">Total cost</span>
+          <span className="text-muted-foreground">{t("ai.tokenUsage.totalCost")}</span>
           <span>{totalCost}</span>
         </>
       )}
@@ -222,11 +232,11 @@ const TokensWithCost = ({ tokens, costText }: { tokens?: number; costText?: stri
   );
 };
 
-export type ContextInputUsageProps = ComponentProps<"div">;
+export type TokenUsageInputProps = ComponentProps<"div">;
 
-export const ContextInputUsage = ({ className, children, ...props }: ContextInputUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
+export const TokenUsageInput = ({ className, children, ...props }: TokenUsageInputProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
   const inputTokens = usage?.inputTokens ?? 0;
 
   if (children) {
@@ -250,17 +260,17 @@ export const ContextInputUsage = ({ className, children, ...props }: ContextInpu
 
   return (
     <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Input</span>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.input")}</span>
       <TokensWithCost costText={inputCostText} tokens={inputTokens} />
     </div>
   );
 };
 
-export type ContextOutputUsageProps = ComponentProps<"div">;
+export type TokenUsageOutputProps = ComponentProps<"div">;
 
-export const ContextOutputUsage = ({ className, children, ...props }: ContextOutputUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
+export const TokenUsageOutput = ({ className, children, ...props }: TokenUsageOutputProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
   const outputTokens = usage?.outputTokens ?? 0;
 
   if (children) {
@@ -284,22 +294,24 @@ export const ContextOutputUsage = ({ className, children, ...props }: ContextOut
 
   return (
     <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Output</span>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.output")}</span>
       <TokensWithCost costText={outputCostText} tokens={outputTokens} />
     </div>
   );
 };
 
-export type ContextReasoningUsageProps = ComponentProps<"div">;
+export type TokenUsageReasoningProps = ComponentProps<"div">;
 
-export const ContextReasoningUsage = ({
+export const TokenUsageReasoning = ({
   className,
   children,
   ...props
-}: ContextReasoningUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
-  const reasoningTokens = usage?.reasoningTokens ?? 0;
+}: TokenUsageReasoningProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
+  // `reasoningTokens` moved under `outputTokenDetails` in ai@7 (the flat,
+  // deprecated top-level alias from ai@6 was removed).
+  const reasoningTokens = usage?.outputTokenDetails?.reasoningTokens ?? 0;
 
   if (children) {
     return children;
@@ -322,18 +334,20 @@ export const ContextReasoningUsage = ({
 
   return (
     <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Reasoning</span>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.reasoning")}</span>
       <TokensWithCost costText={reasoningCostText} tokens={reasoningTokens} />
     </div>
   );
 };
 
-export type ContextCacheUsageProps = ComponentProps<"div">;
+export type TokenUsageCacheProps = ComponentProps<"div">;
 
-export const ContextCacheUsage = ({ className, children, ...props }: ContextCacheUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
-  const cacheTokens = usage?.cachedInputTokens ?? 0;
+export const TokenUsageCache = ({ className, children, ...props }: TokenUsageCacheProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
+  // `cachedInputTokens` moved under `inputTokenDetails.cacheReadTokens` in
+  // ai@7 (the flat, deprecated top-level alias from ai@6 was removed).
+  const cacheTokens = usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 
   if (children) {
     return children;
@@ -356,7 +370,7 @@ export const ContextCacheUsage = ({ className, children, ...props }: ContextCach
 
   return (
     <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Cache</span>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.cache")}</span>
       <TokensWithCost costText={cacheCostText} tokens={cacheTokens} />
     </div>
   );

package/src/tool-result-card.stories.tsx

@@ -9,7 +9,15 @@ import { ToolResultCard } from "./tool-result-card";
 const meta = {
   title: "AI/ToolResultCard",
   component: ToolResultCard,
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT produced-artifact card; a console transcript renders the same moment through `Terminal/TerminalToolCall` — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). A separate component from `AI/Tool` by design: `Tool` is the step that RAN (JSON behind disclosure), `ToolResultCard` hosts what it produced — a chart, a table, a file preview — as `children`, on the elevation channel (raised fill, no border).",
+      },
+    },
+  },
   tags: ["autodocs"],
 } satisfies Meta<typeof ToolResultCard>;
 export default meta;

package/src/tool.stories.tsx

@@ -8,9 +8,19 @@ import {
   ToolOutput,
   statusFromToolState,
 } from "./tool";
-const meta = { title: "AI/Tool", component: Tool, parameters: { layout: "padded" } } satisfies Meta<
-  typeof Tool
->;
+const meta = {
+  title: "AI/Tool",
+  component: Tool,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT tool-call row; the console skin is `Terminal/TerminalToolCall`, and both speak the same success / error / pending vocabulary — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). `Tool` owns the rail-and-inspect idiom: a header carrying the derived tool name, a `StatusBadge` and a business summary, with the raw payload behind a default-collapsed `ToolDetails`. The artifact a call PRODUCED is `AI/ToolResultCard` instead.",
+      },
+    },
+  },
+} satisfies Meta<typeof Tool>;
 export default meta;
 type Story = StoryObj<typeof meta>;
 // JSON-behind-disclosure is the package default (#192, research 10 §B.5): the

package/src/tool.tsx

@@ -145,14 +145,19 @@ export type ToolInputProps = ComponentProps<"div"> & {
   input: ToolPart["input"];
 };
 
-export const ToolInput = ({ className, input, ...props }: ToolInputProps) => (
-  <div className={cn("space-y-2 overflow-hidden", className)} {...props}>
-    <h4 className="text-meta uppercase text-muted-foreground">Parameters</h4>
-    <div className="rounded-md bg-muted/50">
-      <CodeBlock code={JSON.stringify(input, null, 2)} language="json" />
+export const ToolInput = ({ className, input, ...props }: ToolInputProps) => {
+  const { t } = useLocale();
+  return (
+    <div className={cn("space-y-2 overflow-hidden", className)} {...props}>
+      <h4 className="text-meta uppercase text-muted-foreground">
+        {t("ai.schemaDisplay.parameters")}
+      </h4>
+      <div className="rounded-md bg-muted/50">
+        <CodeBlock code={JSON.stringify(input, null, 2)} language="json" />
+      </div>
     </div>
-  </div>
-);
+  );
+};
 
 export type ToolOutputProps = ComponentProps<"div"> & {
   /**
@@ -223,7 +228,9 @@ export const ToolOutput = ({
         <div
           className={cn(
             "overflow-x-auto rounded-md text-caption [&_table]:w-full",
-            showError ? "bg-destructive/10 text-destructive" : "bg-muted/50 text-foreground",
+            // #124: this colours the ambient text of the error/result body —
+            // running text, so the error branch takes the ink rung.
+            showError ? "bg-destructive/10 text-destructive-text" : "bg-muted/50 text-foreground",
           )}
         >
           {showError && <div>{errorText}</div>}

package/src/turn-status.stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+import { TurnStatus } from "./turn-status";
+
+const meta = {
+  title: "AI/TurnStatus",
+  component: TurnStatus,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT in-turn footer; the console skin is `Terminal/TerminalWorking` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
+          "The in-turn footer: label, elapsed time, token counts, turn progress and a stop affordance in one place (#105). Exactly one role=status live region announces the label and the settled state — the ticking elapsed/tokens/turn stats are plain visible text so they never flood assistive tech.",
+      },
+    },
+  },
+  args: {
+    elapsedMs: 8000,
+    label: "Working…",
+    status: "working",
+    tokens: { input: 1200, output: 340 },
+    turn: 2,
+    turnTotal: 5,
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof TurnStatus>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A running turn: label, elapsed, tokens, turn progress and a stop button. */
+export const Default: Story = {
+  args: {
+    onStop: () => undefined,
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** No stop control — just the label and live stats. */
+export const WithoutStop: Story = {
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** A minimal working state — only a label, no stats yet. */
+export const LabelOnly: Story = {
+  args: {
+    elapsedMs: undefined,
+    tokens: undefined,
+    turn: undefined,
+    turnTotal: undefined,
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** The completed-turn line — stats and the stop control disappear; the live region stops announcing further ticks. */
+export const Settled: Story = {
+  args: {
+    status: "settled",
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** Adds a "scroll to bottom" affordance beside the stop control. */
+export const WithScrollToBottom: Story = {
+  args: {
+    onScrollToBottom: () => undefined,
+    onStop: () => undefined,
+    showScrollToBottom: true,
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** A live-ticking demo — elapsed time advances every second until Stop settles the turn. */
+export const Live: Story = {
+  render: () => {
+    const LiveDemo = () => {
+      const [elapsedMs, setElapsedMs] = useState(0);
+      const [status, setStatus] = useState<"working" | "settled">("working");
+
+      useEffect(() => {
+        if (status !== "working") return;
+        const id = setInterval(() => setElapsedMs((ms) => ms + 1000), 1000);
+        return () => clearInterval(id);
+      }, [status]);
+
+      return (
+        <div className="max-w-lg rounded-md border bg-card p-2">
+          <TurnStatus
+            elapsedMs={elapsedMs}
+            label="Editing files…"
+            onStop={() => setStatus("settled")}
+            status={status}
+            tokens={{ input: 800 + elapsedMs, output: 120 + elapsedMs / 2 }}
+            turn={1}
+            turnTotal={3}
+          />
+        </div>
+      );
+    };
+    return <LiveDemo />;
+  },
+};

package/src/turn-status.test.tsx

@@ -0,0 +1,74 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { formatElapsed } from "@elabs-ai/components-ui";
+import { TurnStatus } from "./turn-status";
+
+// `formatElapsed` now lives in `@elabs-ai/components-ui` (docs/decisions/
+// 2026-09-01-brainless-adoption-architecture.md § 6.1) — `TurnStatus` imports
+// it rather than declaring it. These tests stay here because `TurnStatus` is
+// the surface whose behaviour they were written to lock.
+describe("formatElapsed", () => {
+  it.each([
+    // [elapsedMs, expected]
+    [0, "0ms"],
+    [420, "420ms"],
+    [999, "999ms"],
+    [1000, "1.0s"],
+    [8000, "8.0s"],
+    [9949, "9.9s"],
+    [10000, "10s"],
+    [42000, "42s"],
+    [59000, "59s"],
+    [60000, "1m00s"],
+    [77000, "1m17s"],
+    [605000, "10m05s"],
+  ] as const)("formats %dms as %s", (elapsedMs, expected) => {
+    expect(formatElapsed(elapsedMs)).toBe(expected);
+  });
+});
+
+describe("TurnStatus", () => {
+  it("renders exactly one live region when label, elapsed, tokens and turn are all supplied", () => {
+    render(
+      <TurnStatus
+        elapsedMs={8000}
+        label="Working…"
+        tokens={{ input: 120, output: 340 }}
+        turn={2}
+        turnTotal={5}
+      />,
+    );
+
+    const liveRegions = screen.getAllByRole("status");
+    expect(liveRegions).toHaveLength(1);
+    expect(liveRegions[0]).toHaveTextContent("Working…");
+  });
+
+  it("renders the elapsed time and does not put it inside the live region", () => {
+    render(<TurnStatus elapsedMs={8000} label="Working…" />);
+
+    expect(screen.getByText("8.0s")).toBeInTheDocument();
+    const [liveRegion] = screen.getAllByRole("status");
+    expect(liveRegion).not.toHaveTextContent("8.0s");
+  });
+
+  it("renders a focusable stop button while working, reachable via onStop", () => {
+    const onStop = () => undefined;
+    render(<TurnStatus label="Working…" onStop={onStop} status="working" />);
+
+    const stop = screen.getByRole("button", { name: "Stop" });
+    expect(stop).toBeInTheDocument();
+    expect(stop.tagName).toBe("BUTTON");
+    stop.focus();
+    expect(stop).toHaveFocus();
+  });
+
+  it("renders the completed-turn line and stops announcing when settled", () => {
+    render(<TurnStatus elapsedMs={8000} status="settled" />);
+
+    expect(screen.queryByRole("button", { name: "Stop" })).not.toBeInTheDocument();
+    const liveRegions = screen.getAllByRole("status");
+    expect(liveRegions).toHaveLength(1);
+    expect(liveRegions[0]).toHaveTextContent(/8\.0s/);
+  });
+});