@dowel-ui/react 0.5.0 → 0.8.0

package/src/components/ai-token-usage/ai-token-usage.tsx

@@ -1,7 +1,17 @@
 "use client";
 
-import type { ComponentPropsWithRef } from "react";
+// Motion from SmoothUI AI Context Meter (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import {
+  useEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from "react";
 
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/popover";
+import { focusRing } from "@/lib/styles";
 import { cn } from "@/lib/utils";
 
 /**
@@ -15,6 +25,14 @@ import { cn } from "@/lib/utils";
  * and the numbers are what a screen reader gets.
  */
 
+export interface TokenUsageBreakdownItem {
+  label: string;
+  tokens: number;
+}
+
+/** How numbers are written when no `format` is given. */
+export type TokenNotation = "standard" | "compact";
+
 export interface TokenUsageProps extends ComponentPropsWithRef<"div"> {
   /** Tokens used so far. */
   used: number;
@@ -25,43 +43,125 @@ export interface TokenUsageProps extends ComponentPropsWithRef<"div"> {
   warnAt?: number;
   /** Formats the numbers. Defaults to the runtime locale's grouping. */
   format?: (value: number) => string;
+  /**
+   * `bar` is a labelled bar. `ring` is a compact inline gauge for toolbars: it
+   * changes hue as it fills, never size, since growth would read as health.
+   */
+  variant?: "bar" | "ring";
+  /**
+   * Number style when `format` is not given. `compact` writes 48000 as "48K".
+   * Defaults to `standard`, or to `compact` in the ring variant.
+   */
+  notation?: TokenNotation;
+  /** Fraction past which the gauge reads as critical, before the limit itself. */
+  dangerAt?: number;
+  /**
+   * What is filling the window. Listed under the bar; in the ring variant, in
+   * a popover from the gauge.
+   */
+  breakdown?: TokenUsageBreakdownItem[];
 }
 
 function defaultFormat(value: number): string {
   return new Intl.NumberFormat().format(value);
 }
 
+const compactFormatters = new Map<string, Intl.NumberFormat>();
+
+/**
+ * Compact token counts, locale-aware: 1800 → "1.8K", 48000 → "48K",
+ * 1500000 → "1.5M". Below two integer digits it keeps one decimal, so 1,800
+ * is never rounded to a misleading "2K".
+ */
+export function formatTokensCompact(value: number, locales?: Intl.LocalesArgument): string {
+  const key = JSON.stringify(locales ?? null);
+  let formatter = compactFormatters.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locales, { notation: "compact" });
+    compactFormatters.set(key, formatter);
+  }
+  return formatter.format(value);
+}
+
+function formatterFor(
+  format: ((value: number) => string) | undefined,
+  notation: TokenNotation,
+): (value: number) => string {
+  if (format) return format;
+  return notation === "compact" ? (value) => formatTokensCompact(value) : defaultFormat;
+}
+
 export function TokenUsage({
   className,
   used,
   limit,
   label = "Context used",
   warnAt = 0.85,
-  format = defaultFormat,
+  format,
+  variant = "bar",
+  notation,
+  dangerAt,
+  breakdown,
   ...props
 }: TokenUsageProps) {
   const fraction = limit > 0 ? Math.min(1, Math.max(0, used / limit)) : 0;
   const percent = Math.round(fraction * 100);
   const warning = fraction >= warnAt;
   const over = used > limit;
+  const danger = !over && dangerAt !== undefined && fraction >= dangerAt;
+  const critical = over || danger;
+  const show = formatterFor(format, notation ?? (variant === "ring" ? "compact" : "standard"));
+  const tone = critical
+    ? "text-destructive"
+    : warning
+      ? "text-warning"
+      : "text-muted-foreground";
+
+  const state = {
+    "data-warning": warning || undefined,
+    "data-over": over || undefined,
+    "data-danger": danger || undefined,
+  };
+
+  if (variant === "ring") {
+    return (
+      <div
+        data-slot="token-usage"
+        data-variant="ring"
+        {...state}
+        className={cn("inline-flex items-center gap-1.5 text-xs", className)}
+        {...props}
+      >
+        <TokenRing
+          fraction={fraction}
+          tone={tone}
+          stroke={
+            critical ? "stroke-destructive" : warning ? "stroke-warning" : "stroke-primary"
+          }
+          text={`${show(used)}/${show(limit)}`}
+          // Full figures for assistive technology: never abbreviated.
+          sentence={
+            `${label}: ${defaultFormat(used)} of ${defaultFormat(limit)} tokens, ${String(percent)}%` +
+            (over ? ", over the limit" : danger ? ", nearly full" : "")
+          }
+          breakdown={breakdown}
+          format={format ?? defaultFormat}
+        />
+      </div>
+    );
+  }
 
   return (
     <div
       data-slot="token-usage"
-      data-warning={warning || undefined}
-      data-over={over || undefined}
+      {...state}
       className={cn("flex w-full flex-col gap-1", className)}
       {...props}
     >
       <div className="flex items-baseline justify-between gap-2 text-xs">
         <span className="text-muted-foreground">{label}</span>
-        <span
-          className={cn(
-            "tabular-nums",
-            over ? "text-destructive" : warning ? "text-warning" : "text-muted-foreground",
-          )}
-        >
-          {format(used)} / {format(limit)}
+        <span className={cn("tabular-nums", tone)}>
+          {show(used)} / {show(limit)}
         </span>
       </div>
       {/* The bar summarises what the numbers above already say, so it is
@@ -70,19 +170,192 @@ export function TokenUsage({
         <div
           className={cn(
             "h-full rounded-full transition-[width] duration-[var(--duration-slow)] ease-[var(--ease-out-quint)]",
-            over ? "bg-destructive" : warning ? "bg-warning" : "bg-primary",
+            critical ? "bg-destructive" : warning ? "bg-warning" : "bg-primary",
           )}
           style={{ width: `${String(percent)}%` }}
         />
       </div>
+      {breakdown && breakdown.length > 0 ? (
+        <TokenUsageBreakdown
+          items={breakdown}
+          format={format ?? defaultFormat}
+          className="mt-1"
+        />
+      ) : null}
     </div>
   );
 }
 
+/** Close grace for a hover-opened breakdown, so the pointer can cross the gap. */
+const HOVER_CLOSE_DELAY = 120;
+
+function TokenRing({
+  fraction,
+  tone,
+  stroke,
+  text,
+  sentence,
+  breakdown,
+  format,
+}: {
+  fraction: number;
+  tone: string;
+  stroke: string;
+  text: string;
+  sentence: string;
+  breakdown?: TokenUsageBreakdownItem[];
+  format: (value: number) => string;
+}) {
+  const [open, setOpen] = useState(false);
+  // Opened by a mouse hovering, rather than by a click or a key.
+  const [hovered, setHovered] = useState(false);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+    },
+    [],
+  );
+
+  function cancelClose() {
+    if (closeTimer.current) clearTimeout(closeTimer.current);
+    closeTimer.current = null;
+  }
+
+  function hoverIn(event: ReactPointerEvent) {
+    if (event.pointerType !== "mouse") return;
+    cancelClose();
+    if (!open) {
+      setHovered(true);
+      setOpen(true);
+    }
+  }
+
+  function hoverOut(event: ReactPointerEvent) {
+    if (event.pointerType !== "mouse" || !hovered) return;
+    cancelClose();
+    closeTimer.current = setTimeout(() => {
+      setOpen(false);
+      setHovered(false);
+    }, HOVER_CLOSE_DELAY);
+  }
+
+  // Geometry never changes with state: only the arc's length and hue do.
+  const gauge: ReactNode = (
+    <>
+      <svg
+        viewBox="0 0 32 32"
+        fill="none"
+        aria-hidden="true"
+        className="size-4 shrink-0 -rotate-90 text-muted-foreground"
+      >
+        <circle cx="16" cy="16" r="13" strokeWidth="3" className="stroke-current opacity-20" />
+        <circle
+          data-part="arc"
+          cx="16"
+          cy="16"
+          r="13"
+          strokeWidth="3"
+          pathLength={1}
+          strokeLinecap={fraction > 0 ? "round" : "butt"}
+          className={cn(
+            "transition-[stroke-dasharray,stroke] duration-[var(--duration-slow)] ease-[var(--ease-out-quint)]",
+            stroke,
+          )}
+          style={{ strokeDasharray: `${String(fraction)} ${String(1 - fraction)}` }}
+        />
+      </svg>
+      <span aria-hidden="true" className={cn("tabular-nums", tone)}>
+        {text}
+      </span>
+      <span className="sr-only">{sentence}</span>
+    </>
+  );
+
+  if (!breakdown || breakdown.length === 0) return gauge;
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(next) => {
+        cancelClose();
+        setHovered(false);
+        setOpen(next);
+      }}
+    >
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          data-slot="token-usage-trigger"
+          onPointerEnter={hoverIn}
+          onPointerLeave={hoverOut}
+          onClick={(event) => {
+            // A click on a hover-opened breakdown pins it rather than closing
+            // it — otherwise the first click a mouse user makes does nothing.
+            if (open && hovered) {
+              event.preventDefault();
+              cancelClose();
+              setHovered(false);
+            }
+          }}
+          className={cn("inline-flex items-center gap-1.5 rounded-md", focusRing)}
+        >
+          {gauge}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        side="top"
+        align="start"
+        aria-label="Context breakdown"
+        className="w-56 p-2.5"
+        onPointerEnter={hoverIn}
+        onPointerLeave={hoverOut}
+        onOpenAutoFocus={(event) => {
+          // Hovering never moves focus.
+          if (hovered) event.preventDefault();
+        }}
+      >
+        <TokenUsageBreakdown items={breakdown} format={format} />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export interface TokenUsageBreakdownProps extends ComponentPropsWithRef<"dl"> {
+  items: TokenUsageBreakdownItem[];
+  format?: (value: number) => string;
+}
+
+/** What is filling the window, as a description list of label and count. */
+export function TokenUsageBreakdown({
+  className,
+  items,
+  format = defaultFormat,
+  ...props
+}: TokenUsageBreakdownProps) {
+  return (
+    <dl
+      data-slot="token-usage-breakdown"
+      className={cn("flex flex-col gap-1 text-xs", className)}
+      {...props}
+    >
+      {items.map((item) => (
+        <div key={item.label} className="flex items-baseline justify-between gap-3">
+          <dt className="text-muted-foreground">{item.label}</dt>
+          <dd className="text-foreground tabular-nums">{format(item.tokens)}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
 export interface TokenCountProps extends ComponentPropsWithRef<"span"> {
   value: number;
   label?: string;
   format?: (value: number) => string;
+  /** Number style when `format` is not given. */
+  notation?: TokenNotation;
 }
 
 /** A bare token count, for a message footer or a toolbar. */
@@ -90,7 +363,8 @@ export function TokenCount({
   className,
   value,
   label = "tokens",
-  format = defaultFormat,
+  format,
+  notation = "standard",
   ...props
 }: TokenCountProps) {
   return (
@@ -99,7 +373,7 @@ export function TokenCount({
       className={cn("text-2xs text-muted-foreground tabular-nums", className)}
       {...props}
     >
-      {format(value)} {label}
+      {formatterFor(format, notation)(value)} {label}
     </span>
   );
 }

package/src/components/ai-token-usage/index.ts

@@ -1,6 +1,11 @@
 export {
   TokenCount,
   TokenUsage,
+  TokenUsageBreakdown,
+  formatTokensCompact,
   type TokenCountProps,
+  type TokenNotation,
+  type TokenUsageBreakdownItem,
+  type TokenUsageBreakdownProps,
   type TokenUsageProps,
 } from "./ai-token-usage";

package/src/components/ai-token-usage/meta.ts

@@ -7,10 +7,14 @@ export const meta = defineMeta({
   category: "ai",
   status: "stable",
   dependencies: [],
-  registryDependencies: [],
+  registryDependencies: ["popover"],
   files: ["ai-token-usage.tsx"],
   a11y:
     "The numbers are the content and the bar only summarises them, so the bar is aria-hidden " +
     "rather than a second progressbar to read past. Counts are formatted for the locale. Warning " +
-    "and over-limit states change the wording's colour but never remove the figures.",
+    "and over-limit states change the wording's colour but never remove the figures. The ring " +
+    "variant abbreviates its visible figures, so it carries a visually hidden sentence with the " +
+    "full numbers and percent. Its breakdown trigger is a real, never-disabled button: click, " +
+    "Enter or Space open it and Escape closes it; a mouse hover also opens it without moving " +
+    "focus, and focus alone never does.",
 });

package/src/components/ai-tool/ai-tool.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+// Motion from SmoothUI AI Tool Call (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import { cva, type VariantProps } from "class-variance-authority";
 import { Collapsible as CollapsiblePrimitive } from "radix-ui";
 import type { ComponentPropsWithRef, ReactNode } from "react";
@@ -68,6 +69,17 @@ export interface ToolHeaderProps extends ComponentPropsWithRef<
   /** Overrides the status wording. */
   statusLabel?: string;
   icon?: ReactNode;
+  /**
+   * Status mark style. `icon` is a glyph per status; `ring` is one ring that
+   * breathes while queued, spins with a gap while running, and draws a check
+   * or a cross when done. `icon` wins over both.
+   */
+  indicator?: "icon" | "ring";
+  /**
+   * A short note before the status — "3 sources", "1.2s". It is part of the
+   * trigger's accessible name, so keep it short.
+   */
+  summary?: ReactNode;
 }
 
 export function ToolHeader({
@@ -76,13 +88,17 @@ export function ToolHeader({
   status = "pending",
   statusLabel,
   icon,
+  indicator = "icon",
+  summary,
   ...props
 }: ToolHeaderProps) {
+  const hasSummary = summary !== undefined && summary !== null;
+
   return (
     <CollapsiblePrimitive.Trigger
       data-slot="tool-header"
       className={cn(
-        "flex w-full items-center gap-2 px-3 py-2 text-left",
+        "flex w-full items-center gap-2 px-3 py-2 text-start",
         "transition-colors duration-[var(--duration-fast)] hover:bg-accent/50",
         "[&[data-state=open]>svg:last-child]:rotate-180",
         focusRing,
@@ -90,14 +106,24 @@ export function ToolHeader({
       )}
       {...props}
     >
-      {icon ?? <ToolIcon status={status} />}
+      {icon ??
+        (indicator === "ring" ? <ToolRing status={status} /> : <ToolIcon status={status} />)}
       <span className="font-mono text-xs font-medium">{name}</span>
+      {hasSummary ? (
+        <span
+          data-slot="tool-summary"
+          className="ms-auto shrink-0 text-xs text-muted-foreground tabular-nums"
+        >
+          {summary}
+        </span>
+      ) : null}
       {/* Status in words. A coloured dot alone says nothing to a screen reader
           and nothing to anyone who cannot distinguish the colours. */}
       <span
         data-slot="tool-status"
         className={cn(
-          "ml-auto text-xs",
+          !hasSummary && "ms-auto",
+          "text-xs",
           status === "error" ? "text-destructive" : "text-muted-foreground",
         )}
       >
@@ -107,7 +133,7 @@ export function ToolHeader({
         viewBox="0 0 24 24"
         fill="none"
         aria-hidden="true"
-        className="size-3.5 shrink-0 text-muted-foreground transition-transform duration-[var(--duration-normal)]"
+        className="size-3.5 shrink-0 text-muted-foreground transition-transform duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]"
       >
         <path
           d="m6 9 6 6 6-6"
@@ -168,6 +194,101 @@ function ToolIcon({ status }: { status: ToolStatus }) {
   );
 }
 
+const PREFIX = "dowel-ai-tool";
+
+/*
+ * One ring for the whole lifecycle. The gap is a transitioned dash array, the
+ * spin and breathe are loops, and the check and cross draw once when they
+ * mount. None of it is an indicator: the status word already says "Running",
+ * so under reduced motion the ring settles instead of moving.
+ */
+const STYLES = `
+@keyframes ${PREFIX}-ring-spin{to{rotate:360deg}}
+@keyframes ${PREFIX}-ring-breathe{0%,100%{stroke-opacity:1}50%{stroke-opacity:.35}}
+@keyframes ${PREFIX}-ring-draw{from{stroke-dashoffset:1}}
+[data-slot=tool-ring] [data-part=track]{stroke-dasharray:1 0;transition:stroke-dasharray calc(250ms * var(--motion-scale,1)) var(--ease-out-quint)}
+[data-slot=tool-ring][data-status=running] [data-part=track]{stroke-dasharray:.68 .32}
+[data-slot=tool-ring] [data-part=spin]{transform-box:view-box;transform-origin:center}
+[data-slot=tool-ring][data-status=running] [data-part=spin]{animation:${PREFIX}-ring-spin calc(900ms * var(--motion-scale,1)) linear infinite}
+[data-slot=tool-ring][data-status=pending] [data-part=track]{animation:${PREFIX}-ring-breathe calc(1600ms * var(--motion-scale,1)) ease-in-out infinite}
+[data-slot=tool-ring] [data-part=glyph]{stroke-dasharray:1 1;animation:${PREFIX}-ring-draw calc(220ms * var(--motion-scale,1)) var(--ease-out-quint) both}
+[data-slot=tool-ring] [data-part=glyph][data-stroke=cross]{animation-duration:calc(160ms * var(--motion-scale,1))}
+[data-slot=tool-ring] [data-part=glyph][data-stroke=cross]+[data-stroke=cross]{animation-delay:calc(60ms * var(--motion-scale,1))}
+`;
+
+const RING_TONE: Record<ToolStatus, string> = {
+  pending: "text-muted-foreground",
+  running: "text-info",
+  success: "text-success",
+  error: "text-destructive",
+};
+
+const CHECK_PATH = "M 8.5 12.2 L 11 14.8 L 15.8 9.6";
+const CROSS_PATHS = ["M 9 9 L 15 15", "M 15 9 L 9 15"] as const;
+
+/** The `indicator="ring"` mark. It never unmounts, so its changes transition. */
+function ToolRing({ status }: { status: ToolStatus }) {
+  return (
+    <>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        data-slot="tool-ring"
+        data-status={status}
+        className={cn(
+          "size-4 shrink-0 transition-colors duration-[calc(250ms*var(--motion-scale))] ease-[var(--ease-out-quint)]",
+          RING_TONE[status],
+        )}
+      >
+        <g data-part="spin">
+          <circle
+            data-part="track"
+            cx="12"
+            cy="12"
+            r="8"
+            pathLength={1}
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+          />
+        </g>
+        {/* Keyed by status, so a glyph mounts — and draws — on the change. */}
+        {status === "success" ? (
+          <path
+            key="success"
+            data-part="glyph"
+            data-stroke="check"
+            d={CHECK_PATH}
+            pathLength={1}
+            stroke="currentColor"
+            strokeWidth="2.2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        ) : null}
+        {status === "error"
+          ? CROSS_PATHS.map((d) => (
+              <path
+                key={d}
+                data-part="glyph"
+                data-stroke="cross"
+                d={d}
+                pathLength={1}
+                stroke="currentColor"
+                strokeWidth="2.2"
+                strokeLinecap="round"
+              />
+            ))
+          : null}
+      </svg>
+    </>
+  );
+}
+
 export function ToolContent({
   className,
   ...props

package/src/components/ai-tool/meta.ts

@@ -13,5 +13,7 @@ export const meta = defineMeta({
     "A disclosure: the trigger exposes aria-expanded and controls the panel. Status is stated in " +
     "words, not by a coloured dot — colour alone is unavailable to a screen reader and to anyone " +
     "who cannot distinguish it. Payload blocks are focusable named regions, since JSON scrolls " +
-    "and an unfocusable scroll box is unreachable by keyboard.",
+    "and an unfocusable scroll box is unreachable by keyboard. The optional ring indicator is " +
+    "decorative and hidden; the status word stays visible, and the ring stops moving under " +
+    "reduced motion. A summary note is part of the trigger's name, so keep it short.",
 });