@vvedantb/ui 0.17.0 → 0.18.0

package/src/ai-elements/context.tsx

@@ -0,0 +1,370 @@
+"use client";
+
+import type { ComponentProps } from "react";
+import { createContext, useContext, useMemo } from "react";
+
+import { Button } from "../ui/button";
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger,
+} from "../ui/hover-card";
+import { Progress } from "../ui/progress";
+import { useCn } from "../ui/ui-config";
+
+const PERCENT_MAX = 100;
+const ICON_RADIUS = 10;
+const ICON_VIEWBOX = 24;
+const ICON_CENTER = 12;
+const ICON_STROKE_WIDTH = 2;
+
+/**
+ * Per-category token counts. Cache reads and writes are priced very differently
+ * (reads ~0.1x input, writes ~1.25x input), so they are tracked separately.
+ */
+interface LanguageModelUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedInputReadTokens?: number;
+  cachedInputWriteTokens?: number;
+}
+
+/**
+ * Pre-computed costs (USD). Pass these when the authoritative cost is known
+ * (e.g. Claude returns `total_cost_usd` directly). Avoids needing a pricing
+ * catalog at render time.
+ */
+interface ContextCosts {
+  totalUSD?: number;
+  inputUSD?: number;
+  outputUSD?: number;
+  cacheReadUSD?: number;
+  cacheWriteUSD?: number;
+}
+
+interface ContextSchema {
+  usedTokens: number;
+  maxTokens: number;
+  usage?: LanguageModelUsage;
+  costs?: ContextCosts;
+}
+
+const ContextContext = createContext<ContextSchema | null>(null);
+
+const useContextValue = () => {
+  const context = useContext(ContextContext);
+
+  if (!context) {
+    throw new Error("ContextUsage components must be used within ContextUsage");
+  }
+
+  return context;
+};
+
+export type ContextUsageProps = ComponentProps<typeof HoverCard> & ContextSchema;
+
+export const ContextUsage = ({
+  usedTokens,
+  maxTokens,
+  usage,
+  costs,
+  ...props
+}: ContextUsageProps) => {
+  const contextValue = useMemo(
+    () => ({ costs, maxTokens, usage, usedTokens }),
+    [costs, maxTokens, usage, usedTokens],
+  );
+
+  return (
+    <ContextContext.Provider value={contextValue}>
+      <HoverCard closeDelay={0} openDelay={0} {...props} />
+    </ContextContext.Provider>
+  );
+};
+
+const ContextIcon = () => {
+  const { usedTokens, maxTokens } = useContextValue();
+  const circumference = 2 * Math.PI * ICON_RADIUS;
+  const usedPercent = maxTokens > 0 ? usedTokens / maxTokens : 0;
+  const dashOffset = circumference * (1 - usedPercent);
+
+  return (
+    <svg
+      aria-label="Model context usage"
+      height="16"
+      role="img"
+      style={{ color: "currentcolor" }}
+      viewBox={`0 0 ${ICON_VIEWBOX} ${ICON_VIEWBOX}`}
+      width="16"
+    >
+      <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 ContextUsageTriggerProps = ComponentProps<typeof Button>;
+
+export const ContextUsageTrigger = ({ children, ...props }: ContextUsageTriggerProps) => {
+  const { usedTokens, maxTokens } = useContextValue();
+  const usedPercent = maxTokens > 0 ? usedTokens / maxTokens : 0;
+  const renderedPercent = new Intl.NumberFormat("en-US", {
+    maximumFractionDigits: 1,
+    style: "percent",
+  }).format(usedPercent);
+
+  return (
+    <HoverCardTrigger asChild>
+      {children ?? (
+        <Button type="button" variant="ghost" size="sm" {...props}>
+          <span className="font-medium text-muted-foreground text-xs tabular-nums">
+            {renderedPercent}
+          </span>
+          <ContextIcon />
+        </Button>
+      )}
+    </HoverCardTrigger>
+  );
+};
+
+export type ContextUsageContentProps = ComponentProps<typeof HoverCardContent>;
+
+export const ContextUsageContent = ({
+  className,
+  ...props
+}: ContextUsageContentProps) => {
+  const merge = useCn();
+  return (
+    <HoverCardContent
+      className={merge("min-w-60 divide-y overflow-hidden p-0", className)}
+      {...props}
+    />
+  );
+};
+
+export type ContextUsageContentHeaderProps = ComponentProps<"div">;
+
+export const ContextUsageContentHeader = ({
+  children,
+  className,
+  ...props
+}: ContextUsageContentHeaderProps) => {
+  const merge = useCn();
+  const { usedTokens, maxTokens } = useContextValue();
+  const usedPercent = maxTokens > 0 ? usedTokens / maxTokens : 0;
+  const displayPct = new Intl.NumberFormat("en-US", {
+    maximumFractionDigits: 1,
+    style: "percent",
+  }).format(usedPercent);
+  const used = new Intl.NumberFormat("en-US", {
+    notation: "compact",
+  }).format(usedTokens);
+  const total = new Intl.NumberFormat("en-US", {
+    notation: "compact",
+  }).format(maxTokens);
+
+  return (
+    <div className={merge("w-full space-y-2 p-3", className)} {...props}>
+      {children ?? (
+        <>
+          <div className="flex items-center justify-between gap-3 text-xs tabular-nums">
+            <p>{displayPct}</p>
+            <p className="font-mono text-muted-foreground">
+              {used} / {total}
+            </p>
+          </div>
+          <div className="space-y-2">
+            <Progress className="bg-surface-secondary" value={usedPercent * PERCENT_MAX} />
+          </div>
+        </>
+      )}
+    </div>
+  );
+};
+
+export type ContextUsageContentBodyProps = ComponentProps<"div">;
+
+export const ContextUsageContentBody = ({
+  children,
+  className,
+  ...props
+}: ContextUsageContentBodyProps) => {
+  const merge = useCn();
+  return (
+    <div className={merge("w-full p-3", className)} {...props}>
+      {children}
+    </div>
+  );
+};
+
+const formatUSD = (value: number) =>
+  new Intl.NumberFormat("en-US", {
+    currency: "USD",
+    // Claude's per-call cost is often sub-cent; show enough precision to be useful.
+    maximumFractionDigits: 4,
+    minimumFractionDigits: 2,
+    style: "currency",
+  }).format(value);
+
+const formatTokens = (value: number) =>
+  new Intl.NumberFormat("en-US", { notation: "compact" }).format(value);
+
+export type ContextUsageContentFooterProps = ComponentProps<"div">;
+
+export const ContextUsageContentFooter = ({
+  children,
+  className,
+  ...props
+}: ContextUsageContentFooterProps) => {
+  const merge = useCn();
+  const { costs } = useContextValue();
+  const totalCost = costs?.totalUSD;
+
+  return (
+    <div
+      className={merge(
+        "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 className="font-mono tabular-nums">
+            {totalCost === undefined ? "—" : formatUSD(totalCost)}
+          </span>
+        </>
+      )}
+    </div>
+  );
+};
+
+const UsageRow = ({
+  label,
+  tokens,
+  costUSD,
+  className,
+  ...rest
+}: {
+  label: string;
+  tokens: number;
+  costUSD?: number;
+} & ComponentProps<"div">) => {
+  const merge = useCn();
+  if (!tokens) return null;
+  return (
+    <div
+      className={merge("flex items-center justify-between text-xs", className)}
+      {...rest}
+    >
+      <span className="text-muted-foreground">{label}</span>
+      <span className="tabular-nums">
+        {formatTokens(tokens)}
+        {costUSD !== undefined ? (
+          <span className="ml-2 font-mono text-muted-foreground">
+            {formatUSD(costUSD)}
+          </span>
+        ) : null}
+      </span>
+    </div>
+  );
+};
+
+export type ContextUsageInputProps = ComponentProps<"div">;
+
+export const ContextUsageInput = (props: ContextUsageInputProps) => {
+  const { usage, costs } = useContextValue();
+  return (
+    <UsageRow
+      label="Input"
+      tokens={usage?.inputTokens ?? 0}
+      costUSD={costs?.inputUSD}
+      {...props}
+    />
+  );
+};
+
+export type ContextUsageOutputProps = ComponentProps<"div">;
+
+export const ContextUsageOutput = (props: ContextUsageOutputProps) => {
+  const { usage, costs } = useContextValue();
+  return (
+    <UsageRow
+      label="Output"
+      tokens={usage?.outputTokens ?? 0}
+      costUSD={costs?.outputUSD}
+      {...props}
+    />
+  );
+};
+
+export type ContextUsageCacheReadProps = ComponentProps<"div">;
+
+export const ContextUsageCacheRead = (props: ContextUsageCacheReadProps) => {
+  const { usage, costs } = useContextValue();
+  return (
+    <UsageRow
+      label="Cache read"
+      tokens={usage?.cachedInputReadTokens ?? 0}
+      costUSD={costs?.cacheReadUSD}
+      {...props}
+    />
+  );
+};
+
+export type ContextUsageCacheWriteProps = ComponentProps<"div">;
+
+export const ContextUsageCacheWrite = (props: ContextUsageCacheWriteProps) => {
+  const { usage, costs } = useContextValue();
+  return (
+    <UsageRow
+      label="Cache write"
+      tokens={usage?.cachedInputWriteTokens ?? 0}
+      costUSD={costs?.cacheWriteUSD}
+      {...props}
+    />
+  );
+};
+
+/**
+ * @deprecated Use ContextUsageCacheRead and ContextUsageCacheWrite separately.
+ * Kept for backwards compat — shows combined cache reads + writes as one row.
+ */
+export const ContextUsageCache = (props: ComponentProps<"div">) => {
+  const { usage, costs } = useContextValue();
+  const cacheTokens =
+    (usage?.cachedInputReadTokens ?? 0) + (usage?.cachedInputWriteTokens ?? 0);
+  const cacheCost =
+    costs?.cacheReadUSD !== undefined || costs?.cacheWriteUSD !== undefined
+      ? (costs?.cacheReadUSD ?? 0) + (costs?.cacheWriteUSD ?? 0)
+      : undefined;
+  return (
+    <UsageRow
+      label="Cache"
+      tokens={cacheTokens}
+      costUSD={cacheCost}
+      {...props}
+    />
+  );
+};

package/src/ai-elements/conversation.tsx

@@ -1,34 +1,71 @@
 "use client";
-import type { ComponentProps } from "react";
-import { AnimatePresence, motion } from "motion/react";
+import type { ComponentProps, ReactNode } from "react";
+import { useEffect, useRef, useState } from "react";
+import { AnimatePresence, domAnimation, LazyMotion, m } from "motion/react";
 import { IconArrowDown, IconDownload } from "@tabler/icons-react";
 import { Button } from "../ui/button";
 import { cn } from "../utils/cn";
 import { flatInteractiveClass } from "../ui/surface-classes";
+import { useCn, useUiConfig } from "../ui/ui-config";
 import { StickToBottom, useStickToBottomContext } from "use-stick-to-bottom";
 import { fastTransition } from "../motion/presets.alt";
+type MotionDivProps = ComponentProps<typeof m.div>;
+/**
+ * `UiConfig.Conversation`. `classes` replace built-in classes: `content`
+ * (`ConversationContent`), `scroll` (a default `scrollClassName`, merged
+ * before the prop), `download`, and the scroll button's `scrollButton`,
+ * `scrollButtonMotion` (the animated wrapper; `""` drops its class) and
+ * `scrollButtonFrame` (a static wrapper around the presence, absent by
+ * default). `scrollButton` holds the scroll button's prop defaults and
+ * motion.
+ */
+export interface ConversationConfig {
+  classes?: {
+    content?: string;
+    scroll?: string;
+    download?: string;
+    scrollButton?: string;
+    scrollButtonMotion?: string;
+    scrollButtonFrame?: string;
+  };
+  scrollButton?: Pick<ConversationScrollButtonProps, "label" | "icon" | "showDelay" | "size"> & {
+    initial?: MotionDivProps["initial"];
+    animate?: MotionDivProps["animate"];
+    exit?: MotionDivProps["exit"];
+    transition?: MotionDivProps["transition"];
+  };
+}
 export type ConversationProps = ComponentProps<typeof StickToBottom>;
-export const Conversation = ({ className, ...props }: ConversationProps) => (
-  <StickToBottom
-    className={cn("relative flex-1 overflow-y-hidden", className)}
-    initial="instant"
-    resize="smooth"
-    role="log"
-    {...props}
-  />
-);
+export const Conversation = ({ className, ...props }: ConversationProps) => {
+  const merge = useCn();
+  return (
+    <StickToBottom
+      className={merge("relative flex-1 overflow-y-hidden", className)}
+      initial="instant"
+      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-4 px-3 py-3", className)}
-    {...props}
-  />
-);
+}: ConversationContentProps) => {
+  const classes = useUiConfig("Conversation")?.classes;
+  const merge = useCn();
+  const scroll = classes?.scroll;
+  return (
+    <StickToBottom.Content
+      className={merge(classes?.content ?? "flex flex-col gap-4 px-3 py-3", className)}
+      {...props}
+      {...(scroll === undefined ? {} : { scrollClassName: merge(scroll, props.scrollClassName) })}
+    />
+  );
+};
 export type ConversationEmptyStateProps = ComponentProps<"div"> & {
   title?: string;
   description?: string;
@@ -41,59 +78,144 @@ export const ConversationEmptyState = ({
   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>;
+}: ConversationEmptyStateProps) => {
+  const merge = useCn();
+  return (
+    <div
+      className={merge(
+        "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> & {
+  /** Text after the icon; also the button's `aria-label` and `title`. */
+  label?: string;
+  /** Replaces the arrow icon. */
+  icon?: ReactNode;
+  /**
+   * Wait this long (ms) after leaving the bottom before showing the button,
+   * so brief layout settles do not flash it. Hiding is immediate. Default 0.
+   */
+  showDelay?: number;
+  /**
+   * When this changes (for example the thread id), hide the button at once and
+   * cancel a pending show; it shows again on the next scroll away.
+   */
+  resetKey?: string;
+};
+/**
+ * `wanted`, or (with a delay or reset key) `wanted` held for `delay` ms, and
+ * a function that hides it at once.
+ */
+function useDelayedShow(
+  wanted: boolean,
+  delay: number,
+  resetKey: string | undefined,
+): [boolean, () => void] {
+  const debounced = delay > 0 || resetKey !== undefined;
+  const [shown, setShown] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const hide = () => {
+    if (timerRef.current !== null) clearTimeout(timerRef.current);
+    timerRef.current = null;
+    setShown(false);
+  };
+  // The reset also cancels the pending show timer, a side effect.
+  useEffect(() => {
+    if (!debounced) return;
+    if (timerRef.current !== null) clearTimeout(timerRef.current);
+    timerRef.current = null;
+    setShown(false);
+  }, [resetKey, debounced]);
+  useEffect(() => {
+    if (!debounced) return;
+    if (!wanted) {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+      timerRef.current = null;
+      setShown(false);
+      return;
+    }
+    timerRef.current = setTimeout(() => {
+      setShown(true);
+      timerRef.current = null;
+    }, delay);
+    return () => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+      timerRef.current = null;
+    };
+  }, [wanted, delay, debounced]);
+  return [debounced ? shown : wanted, debounced ? hide : () => {}];
+}
 export const ConversationScrollButton = ({
   className,
+  label: labelProp,
+  icon: iconProp,
+  showDelay,
+  resetKey,
+  size,
   ...props
 }: ConversationScrollButtonProps) => {
+  const config = useUiConfig("Conversation");
+  const defaults = config?.scrollButton;
+  const classes = config?.classes;
+  const merge = useCn();
   const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+  const [visible, hide] = useDelayedShow(
+    !isAtBottom,
+    showDelay ?? defaults?.showDelay ?? 0,
+    resetKey,
+  );
+  const label = labelProp ?? defaults?.label;
+  const icon = iconProp ?? defaults?.icon;
   const handleScrollToBottom = () => {
+    hide();
     scrollToBottom();
   };
-  return (
-    <AnimatePresence initial={false}>
-      {isAtBottom ? null : (
-        <motion.div
-          key="scroll-to-bottom"
-          className="absolute bottom-4 left-0 right-0 z-10 flex justify-center"
-          initial={{ opacity: 0, y: 8 }}
-          animate={{ opacity: 1, y: 0 }}
-          exit={{ opacity: 0, y: 8 }}
-          transition={fastTransition}
-        >
-          <Button
-            className={cn(flatInteractiveClass, "rounded-full", className)}
-            onClick={handleScrollToBottom}
-            size="icon"
-            type="button"
-            variant="outline"
-            {...props}
+  const motionClass = classes?.scrollButtonMotion ?? "absolute bottom-4 left-0 right-0 z-10 flex justify-center";
+  const presence = (
+    <LazyMotion features={domAnimation}>
+      <AnimatePresence initial={false}>
+        {visible ? (
+          <m.div
+            key="scroll-to-bottom"
+            className={motionClass === "" ? undefined : motionClass}
+            initial={defaults?.initial ?? { opacity: 0, y: 8 }}
+            animate={defaults?.animate ?? { opacity: 1, y: 0 }}
+            exit={defaults?.exit ?? { opacity: 0, y: 8 }}
+            transition={defaults?.transition ?? fastTransition}
           >
-            <IconArrowDown className="size-4" />
-          </Button>
-        </motion.div>
-      )}
-    </AnimatePresence>
+            <Button
+              className={merge(classes?.scrollButton ?? [flatInteractiveClass, "rounded-full"], className)}
+              onClick={handleScrollToBottom}
+              size={size ?? defaults?.size ?? "icon"}
+              type="button"
+              variant="outline"
+              {...(label ? { "aria-label": label, title: label } : {})}
+              {...props}
+            >
+              {icon ?? <IconArrowDown className="size-4" />}
+              {label}
+            </Button>
+          </m.div>
+        ) : null}
+      </AnimatePresence>
+    </LazyMotion>
   );
+  const frame = classes?.scrollButtonFrame;
+  return frame === undefined ? presence : <div className={frame}>{presence}</div>;
 };
 export interface ConversationMessage {
   role: "user" | "assistant" | "system" | "data" | "tool";
@@ -127,6 +249,8 @@ export const ConversationDownload = ({
   children,
   ...props
 }: ConversationDownloadProps) => {
+  const download = useUiConfig("Conversation")?.classes?.download;
+  const merge = useCn();
   const handleDownload = () => {
     const markdown = messagesToMarkdown(messages, formatMessage);
     const blob = new Blob([markdown], { type: "text/markdown" });
@@ -141,8 +265,8 @@ export const ConversationDownload = ({
   };
   return (
     <Button
-      className={cn(
-        cn(flatInteractiveClass, "absolute top-4 right-4 rounded-full"),
+      className={merge(
+        download ?? cn(flatInteractiveClass, "absolute top-4 right-4 rounded-full"),
         className,
       )}
       onClick={handleDownload}