@momentumworld/ui-react 0.17.0

package/src/components/ui/aurora-orb.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { MODE_DRAWS, resolvePreset, type OrbSize, type OrbState } from "thinking-orbs";
+
+import { cn } from "../../lib/utils/css";
+
+// Re-exported so consumers can type their own props without depending on
+// thinking-orbs directly.
+export type { OrbSize, OrbState } from "thinking-orbs";
+
+/** AuroraText's default RGB stops, so orb + text read as one piece. */
+const DEFAULT_COLORS = ["#FF0080", "#7928CA", "#0070F3", "#38bdf8"];
+
+export interface AuroraOrbProps {
+  /**
+   * Which thinking-orbs animation to show: "working" | "searching" |
+   * "solving" | "listening" | "composing" | "shaping". Default "working".
+   */
+  state?: OrbState;
+  /** Tuned size preset from thinking-orbs — 20 (inline) or 64 (avatar). Default 20. */
+  size?: OrbSize;
+  /** Animation speed multiplier on top of the preset's baked speed. Default 1. */
+  speed?: number;
+  /**
+   * Gradient stops swept across the dots, matching AuroraText's default RGB
+   * set (pink → purple → blue → sky). Vivid stops stay legible on both light
+   * and dark backgrounds — the dots are painted with these colors directly.
+   */
+  colors?: string[];
+  className?: string;
+}
+
+/**
+ * A `thinking-orbs` orb recolored with the aurora gradient — the dotted-orb
+ * counterpart to `AuroraText`.
+ *
+ * The stock `<ThinkingOrb>` has no color API (its canvas paints monochrome
+ * theme ink only), but the package exports its frame painters (`MODE_DRAWS` +
+ * `resolvePreset`) for custom rendering. So we run the same animation loop
+ * and, after each frame, composite a slowly rotating aurora gradient onto the
+ * dots via `source-in`: the dots' alpha (their depth shading) survives while
+ * their ink color is replaced by the gradient. Theme detection becomes
+ * unnecessary — the gradient works on light and dark backgrounds alike.
+ * Respects prefers-reduced-motion (renders a single still frame).
+ *
+ * @example
+ * <AuroraOrb state="solving" speed={0.7} />
+ * <AuroraOrb size={64} colors={["#22d3ee", "#a855f7", "#f43f5e"]} />
+ */
+export function AuroraOrb({
+  className,
+  colors = DEFAULT_COLORS,
+  size = 20,
+  speed = 1,
+  state = "working",
+}: AuroraOrbProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  // A joined key keeps the effect's deps primitive (an inline `colors` array
+  // would otherwise retrigger every render). Joined on a control character so
+  // comma-bearing stops like rgb(255, 0, 128) survive the round-trip.
+  const colorsKey = colors.join("\u001f");
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const dpr = Math.min(2, (typeof devicePixelRatio !== "undefined" && devicePixelRatio) || 1);
+    canvas.width = Math.round(size * dpr);
+    canvas.height = Math.round(size * dpr);
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+
+    // Guard colors={[]}: an empty array bypasses the default parameter.
+    const stops = colorsKey ? colorsKey.split("\u001f") : DEFAULT_COLORS;
+    const { mode, speed: baseSpeed, opts } = resolvePreset(state, size);
+    const draw = MODE_DRAWS[mode];
+    const rate = baseSpeed * speed;
+
+    const paint = (t: number, wall: number) => {
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      ctx.clearRect(0, 0, size, size);
+      draw(ctx, size, t, false, opts);
+      // Recolor the frame: a linear gradient across the orb, rotating so the
+      // colors drift the way AuroraText's sweep does. Driven by wall-clock
+      // (~5s per turn) rather than the preset-scaled t, so the drift stays
+      // visible even for slow presets/speeds.
+      const angle = wall * 1.2;
+      const r = size / 2;
+      const dx = Math.cos(angle) * r;
+      const dy = Math.sin(angle) * r;
+      const gradient = ctx.createLinearGradient(r - dx, r - dy, r + dx, r + dy);
+      stops.forEach((color, i) => {
+        gradient.addColorStop(stops.length === 1 ? 0 : i / (stops.length - 1), color);
+      });
+      ctx.globalCompositeOperation = "source-in";
+      ctx.fillStyle = gradient;
+      ctx.fillRect(0, 0, size, size);
+      ctx.globalCompositeOperation = "source-over";
+    };
+
+    // Reduced motion: a single still frame, matching the stock component.
+    if (typeof matchMedia !== "undefined" && matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      paint(0.6, 0.6);
+      return;
+    }
+
+    // Animation loop, paused while the orb is off-screen or the tab is
+    // hidden — mirroring the stock ThinkingOrb's behavior.
+    let frame = 0;
+    let running = false;
+    const loop = () => {
+      const now = performance.now() / 1000;
+      paint(now * rate, now);
+      if (running) frame = requestAnimationFrame(loop);
+    };
+    const start = () => {
+      if (running) return;
+      running = true;
+      frame = requestAnimationFrame(loop);
+    };
+    const stop = () => {
+      running = false;
+      cancelAnimationFrame(frame);
+    };
+
+    const first = performance.now() / 1000;
+    paint(first * rate, first);
+    let visible = true;
+    const observer =
+      typeof IntersectionObserver !== "undefined"
+        ? new IntersectionObserver((entries) => {
+            const entry = entries[0];
+            if (!entry) return;
+            visible = entry.isIntersecting;
+            if (visible && document.visibilityState !== "hidden") start();
+            else stop();
+          })
+        : null;
+    observer?.observe(canvas);
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "hidden") stop();
+      else if (visible) start();
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    if (!observer) start();
+
+    return () => {
+      stop();
+      observer?.disconnect();
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [colorsKey, size, speed, state]);
+
+  return (
+    <canvas
+      aria-hidden="true"
+      className={cn("shrink-0", className)}
+      data-slot="aurora-orb"
+      ref={canvasRef}
+      style={{ width: size, height: size, display: "block" }}
+    />
+  );
+}

package/src/components/ui/aurora-text.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { memo, type CSSProperties, type ReactNode } from "react";
+
+import { cn } from "../../lib/utils/css";
+
+export interface AuroraTextProps {
+  children: ReactNode;
+  className?: string;
+  /**
+   * Gradient stops, cycled left→right and looped back to the first. The default
+   * is a vivid RGB set (pink → purple → blue → sky) chosen to stay legible on
+   * BOTH light and dark backgrounds — the text is painted with these colors
+   * (transparent fill + clipped gradient), so it never depends on the page bg.
+   */
+  colors?: string[];
+  /** Animation speed multiplier. 1 ≈ a 10s loop; 2 is twice as fast. */
+  speed?: number;
+  /** Add a soft, blurred RGB halo behind the text (a subtle aura). */
+  glow?: boolean;
+}
+
+const DEFAULT_COLORS = ["#FF0080", "#7928CA", "#0070F3", "#38bdf8"];
+
+/**
+ * Animated RGB gradient text: the gradient slowly sweeps across the glyphs on a
+ * loop (via `background-position`, so it's GPU-composited and cheap — safe on
+ * mobile). Purely CSS; no JS ticking. The real text is kept in an `sr-only`
+ * span so it stays selectable/announced while the visible layer is decorative.
+ *
+ * @example
+ * <AuroraText>Thinking</AuroraText>
+ * <AuroraText glow speed={1.4} colors={["#22d3ee", "#a855f7", "#f43f5e"]}>Live</AuroraText>
+ */
+export const AuroraText = memo(function AuroraText({
+  children,
+  className,
+  colors = DEFAULT_COLORS,
+  speed = 1,
+  glow = false,
+}: AuroraTextProps) {
+  const gradientStyle: CSSProperties = {
+    backgroundImage: `linear-gradient(135deg, ${colors.join(", ")}, ${colors[0]})`,
+    // Oversized so the sweep has room to travel before repeating.
+    backgroundSize: "200% auto",
+    WebkitBackgroundClip: "text",
+    backgroundClip: "text",
+    WebkitTextFillColor: "transparent",
+    color: "transparent",
+    // Full `animation` inline (not the `animate-aurora` utility): the keyframe
+    // ships in styles.css unconditionally, so the sweep runs even if the
+    // consumer's Tailwind never generates that utility class.
+    animation: `aurora ${10 / speed}s ease infinite`,
+  };
+
+  return (
+    <span className={cn("relative inline-block", className)}>
+      {/* Accessible, copyable text; the colored layers below are decorative. */}
+      <span className="sr-only">{children}</span>
+      {glow ? (
+        <span
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 select-none blur-[6px] opacity-60"
+          style={gradientStyle}
+        >
+          {children}
+        </span>
+      ) : null}
+      <span aria-hidden="true" className="relative" style={gradientStyle}>
+        {children}
+      </span>
+    </span>
+  );
+});
+
+AuroraText.displayName = "AuroraText";

package/src/components/ui/autocomplete.tsx

@@ -0,0 +1,296 @@
+"use client";
+
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { ChevronsUpDownIcon, XIcon } from "lucide-react";
+import { Input } from "./input";
+import { ScrollArea } from "./scroll-area";
+import { cn } from "../../lib/utils/css";
+
+const Autocomplete = AutocompletePrimitive.Root;
+
+function AutocompleteInput({
+  className,
+  showTrigger = false,
+  showClear = false,
+  startAddon,
+  size,
+  ...props
+}: Omit<AutocompletePrimitive.Input.Props, "size"> & {
+  showTrigger?: boolean;
+  showClear?: boolean;
+  startAddon?: React.ReactNode;
+  size?: "sm" | "default" | "lg" | number;
+  ref?: React.Ref<HTMLInputElement>;
+}) {
+  const sizeValue = (size ?? "default") as "sm" | "default" | "lg" | number;
+
+  return (
+    <div className="relative not-has-[>*.w-full]:w-fit w-full text-foreground has-disabled:opacity-64">
+      {startAddon && (
+        <div
+          aria-hidden="true"
+          className="[&_svg]:-mx-0.5 pointer-events-none absolute inset-y-0 start-px z-10 flex items-center ps-[calc(--spacing(3)-1px)] opacity-80 has-[+[data-size=sm]]:ps-[calc(--spacing(2.5)-1px)] [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4"
+          data-slot="autocomplete-start-addon"
+        >
+          {startAddon}
+        </div>
+      )}
+      <AutocompletePrimitive.Input
+        className={cn(
+          startAddon &&
+            "data-[size=sm]:*:data-[slot=autocomplete-input]:ps-[calc(--spacing(7.5)-1px)] *:data-[slot=autocomplete-input]:ps-[calc(--spacing(8.5)-1px)] sm:data-[size=sm]:*:data-[slot=autocomplete-input]:ps-[calc(--spacing(7)-1px)] sm:*:data-[slot=autocomplete-input]:ps-[calc(--spacing(8)-1px)]",
+          sizeValue === "sm"
+            ? "has-[+[data-slot=autocomplete-trigger],+[data-slot=autocomplete-clear]]:*:data-[slot=autocomplete-input]:pe-6.5"
+            : "has-[+[data-slot=autocomplete-trigger],+[data-slot=autocomplete-clear]]:*:data-[slot=autocomplete-input]:pe-7",
+          className,
+        )}
+        data-slot="autocomplete-input"
+        render={<Input nativeInput size={sizeValue} />}
+        {...props}
+      />
+      {showTrigger && (
+        <AutocompleteTrigger
+          className={cn(
+            "-translate-y-1/2 absolute top-1/2 inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md border border-transparent opacity-80 outline-none transition-colors pointer-coarse:after:absolute pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:opacity-100 has-[+[data-slot=autocomplete-clear]]:hidden sm:size-7 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+            sizeValue === "sm" ? "end-0" : "end-0.5",
+          )}
+        >
+          <ChevronsUpDownIcon />
+        </AutocompleteTrigger>
+      )}
+      {showClear && (
+        <AutocompleteClear
+          className={cn(
+            "-translate-y-1/2 absolute top-1/2 inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md border border-transparent opacity-80 outline-none transition-colors pointer-coarse:after:absolute pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:opacity-100 has-[+[data-slot=autocomplete-clear]]:hidden sm:size-7 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+            sizeValue === "sm" ? "end-0" : "end-0.5",
+          )}
+        >
+          <XIcon />
+        </AutocompleteClear>
+      )}
+    </div>
+  );
+}
+
+function AutocompletePopup({
+  className,
+  children,
+  sideOffset = 4,
+  ...props
+}: AutocompletePrimitive.Popup.Props & {
+  sideOffset?: number;
+}) {
+  return (
+    <AutocompletePrimitive.Portal>
+      <AutocompletePrimitive.Positioner
+        className="z-50 select-none"
+        data-slot="autocomplete-positioner"
+        sideOffset={sideOffset}
+      >
+        <AutocompletePrimitive.Popup
+          className={cn(
+            "relative flex max-h-[min(var(--available-height),23rem)] w-(--anchor-width) max-w-(--available-width) origin-(--transform-origin) flex-col rounded-lg border bg-popover not-dark:bg-clip-padding text-foreground shadow-lg/5 transition-opacity duration-150 ease-out before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/6%)] data-ending-style:opacity-0 data-starting-style:opacity-0 dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+            className,
+          )}
+          data-slot="autocomplete-popup"
+          {...props}
+        >
+          {children}
+        </AutocompletePrimitive.Popup>
+      </AutocompletePrimitive.Positioner>
+    </AutocompletePrimitive.Portal>
+  );
+}
+
+function AutocompleteItem({
+  className,
+  children,
+  ...props
+}: AutocompletePrimitive.Item.Props) {
+  return (
+    <AutocompletePrimitive.Item
+      className={cn(
+        "flex min-h-8 cursor-default select-none items-center rounded-sm px-2 py-1 text-base outline-none data-disabled:pointer-events-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:opacity-64 sm:min-h-7 sm:text-sm",
+        className,
+      )}
+      data-slot="autocomplete-item"
+      {...props}
+    >
+      {children}
+    </AutocompletePrimitive.Item>
+  );
+}
+
+function AutocompleteSeparator({
+  className,
+  ...props
+}: AutocompletePrimitive.Separator.Props) {
+  return (
+    <AutocompletePrimitive.Separator
+      className={cn("mx-2 my-1 h-px bg-border last:hidden", className)}
+      data-slot="autocomplete-separator"
+      {...props}
+    />
+  );
+}
+
+function AutocompleteGroup({
+  className,
+  ...props
+}: AutocompletePrimitive.Group.Props) {
+  return (
+    <AutocompletePrimitive.Group
+      className={cn("[[role=group]+&]:mt-1.5", className)}
+      data-slot="autocomplete-group"
+      {...props}
+    />
+  );
+}
+
+function AutocompleteGroupLabel({
+  className,
+  ...props
+}: AutocompletePrimitive.GroupLabel.Props) {
+  return (
+    <AutocompletePrimitive.GroupLabel
+      className={cn(
+        "px-2 py-1.5 font-medium text-muted-foreground text-xs",
+        className,
+      )}
+      data-slot="autocomplete-group-label"
+      {...props}
+    />
+  );
+}
+
+function AutocompleteEmpty({
+  className,
+  ...props
+}: AutocompletePrimitive.Empty.Props) {
+  return (
+    <AutocompletePrimitive.Empty
+      className={cn(
+        "not-empty:p-2 text-center text-base text-muted-foreground sm:text-sm",
+        className,
+      )}
+      data-slot="autocomplete-empty"
+      {...props}
+    />
+  );
+}
+
+function AutocompleteRow({
+  className,
+  ...props
+}: AutocompletePrimitive.Row.Props) {
+  return (
+    <AutocompletePrimitive.Row
+      className={className}
+      data-slot="autocomplete-row"
+      {...props}
+    />
+  );
+}
+
+function AutocompleteValue({ ...props }: AutocompletePrimitive.Value.Props) {
+  return (
+    <AutocompletePrimitive.Value data-slot="autocomplete-value" {...props} />
+  );
+}
+
+function AutocompleteList({
+  className,
+  ...props
+}: AutocompletePrimitive.List.Props) {
+  return (
+    <ScrollArea scrollbarGutter scrollFade className="grow">
+      <AutocompletePrimitive.List
+        className={cn(
+          "not-empty:scroll-py-1 not-empty:p-1 in-data-has-overflow-y:pe-3",
+          className,
+        )}
+        data-slot="autocomplete-list"
+        {...props}
+      />
+    </ScrollArea>
+  );
+}
+
+function AutocompleteClear({
+  className,
+  ...props
+}: AutocompletePrimitive.Clear.Props) {
+  return (
+    <AutocompletePrimitive.Clear
+      className={cn(
+        "-translate-y-1/2 absolute end-0.5 top-1/2 inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md border border-transparent opacity-80 outline-none transition-[color,background-color,box-shadow,opacity] pointer-coarse:after:absolute pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:opacity-100 sm:size-7 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        className,
+      )}
+      data-slot="autocomplete-clear"
+      {...props}
+    >
+      <XIcon />
+    </AutocompletePrimitive.Clear>
+  );
+}
+
+function AutocompleteStatus({
+  className,
+  ...props
+}: AutocompletePrimitive.Status.Props) {
+  return (
+    <AutocompletePrimitive.Status
+      className={cn(
+        "px-3 py-2 font-medium text-muted-foreground text-xs empty:m-0 empty:p-0",
+        className,
+      )}
+      data-slot="autocomplete-status"
+      {...props}
+    />
+  );
+}
+
+function AutocompleteCollection({
+  ...props
+}: AutocompletePrimitive.Collection.Props) {
+  return (
+    <AutocompletePrimitive.Collection
+      data-slot="autocomplete-collection"
+      {...props}
+    />
+  );
+}
+
+function AutocompleteTrigger({
+  className,
+  ...props
+}: AutocompletePrimitive.Trigger.Props) {
+  return (
+    <AutocompletePrimitive.Trigger
+      className={className}
+      data-slot="autocomplete-trigger"
+      {...props}
+    />
+  );
+}
+
+const useAutocompleteFilter = AutocompletePrimitive.useFilter;
+
+export {
+  Autocomplete,
+  AutocompleteInput,
+  AutocompleteTrigger,
+  AutocompletePopup,
+  AutocompleteItem,
+  AutocompleteSeparator,
+  AutocompleteGroup,
+  AutocompleteGroupLabel,
+  AutocompleteEmpty,
+  AutocompleteValue,
+  AutocompleteList,
+  AutocompleteClear,
+  AutocompleteStatus,
+  AutocompleteRow,
+  AutocompleteCollection,
+  useAutocompleteFilter,
+};

package/src/components/ui/avatar-group.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type * as React from "react";
+
+import { cn } from "../../lib/utils/css";
+import { Avatar, avatarVariants } from "./avatar";
+import {
+  Tooltip,
+  TooltipPopup,
+  TooltipProvider,
+  TooltipTrigger,
+} from "./tooltip";
+
+type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>;
+
+const avatarGroupVariants = cva(
+  // Each child gets a ring in the page color so overlapping avatars stay
+  // visually separated; hover lifts one to the front.
+  "isolate flex items-center *:relative *:rounded-full *:ring-2 *:ring-background *:transition-transform hover:*:z-10",
+  {
+    defaultVariants: { overlap: "md" },
+    variants: {
+      overlap: {
+        sm: "*:not-first:-ml-1.5",
+        md: "*:not-first:-ml-2.5",
+        lg: "*:not-first:-ml-3.5",
+      },
+    },
+  },
+);
+
+interface AvatarGroupItem {
+  src?: string;
+  /** Initials shown when there is no image. */
+  initials?: React.ReactNode;
+  alt?: string;
+  /**
+   * Label revealed on hover when `showNameOnHover` is set (e.g. the person's
+   * name). Falls back to `alt` when omitted.
+   */
+  name?: React.ReactNode;
+}
+
+interface AvatarGroupProps
+  extends React.ComponentProps<"div">,
+    VariantProps<typeof avatarGroupVariants> {
+  /** Data-driven avatars. Omit to compose `<Avatar>` children yourself. */
+  items?: AvatarGroupItem[];
+  /** Cap the visible avatars; the rest collapse into a "+N" chip. */
+  max?: number;
+  size?: AvatarSize;
+  /**
+   * Reveal each avatar's `name` (or `alt`) in a tooltip above it on hover /
+   * focus. Only applies to the data-driven `items` path.
+   */
+  showNameOnHover?: boolean;
+}
+
+/**
+ * A row of overlapping avatars with an overflow "+N" chip. Pass `items` for the
+ * data-driven path, or compose `<Avatar>` children directly for full control.
+ *
+ * With `showNameOnHover`, hovering (or focusing) an avatar reveals its `name`
+ * in a tooltip — e.g. hovering Amir's photo shows "Amir".
+ */
+function AvatarGroup({
+  className,
+  items,
+  max,
+  size = "sm",
+  overlap,
+  showNameOnHover = false,
+  children,
+  ...props
+}: AvatarGroupProps) {
+  const shown = items && max ? items.slice(0, max) : items;
+  const overflow = items && max ? items.length - max : 0;
+
+  const group = (
+    <div
+      className={cn(avatarGroupVariants({ overlap }), className)}
+      data-slot="avatar-group"
+      role="group"
+      {...props}
+    >
+      {items
+        ? shown?.map((item, i) => {
+            const label = item.name ?? item.alt;
+            const avatar = (
+              <Avatar
+                alt={item.alt}
+                initials={item.initials}
+                size={size}
+                src={item.src}
+              />
+            );
+            if (!(showNameOnHover && label)) {
+              // biome-ignore lint/suspicious/noArrayIndexKey: order is stable
+              return <Avatar alt={item.alt} initials={item.initials} key={i} size={size} src={item.src} />;
+            }
+            return (
+              // The span wrapper is the group's direct child, so it carries the
+              // ring/overlap styling; the tooltip anchors to it (Base UI needs a
+              // ref-able host, which the Avatar fn component doesn't forward).
+              // biome-ignore lint/suspicious/noArrayIndexKey: order is stable
+              <Tooltip key={i}>
+                <TooltipTrigger
+                  className="inline-flex cursor-default"
+                  render={<span />}
+                >
+                  {avatar}
+                </TooltipTrigger>
+                <TooltipPopup>{label}</TooltipPopup>
+              </Tooltip>
+            );
+          })
+        : children}
+      {overflow > 0 ? (
+        <span
+          aria-label={`${overflow} more`}
+          className={cn(
+            avatarVariants({ size }),
+            // Solid neutral fill so the chip reads as a distinct surface in both
+            // themes — the `bg-muted` token is only 4% opacity (near-transparent).
+            "bg-stone-200 font-medium text-stone-600 dark:bg-stone-700 dark:text-stone-200",
+          )}
+          data-slot="avatar-group-overflow"
+        >
+          +{overflow}
+        </span>
+      ) : null}
+    </div>
+  );
+
+  // Self-contained: provide a tooltip context so the hover mode works without
+  // the consumer having to mount a TooltipProvider. A short delay keeps names
+  // from flickering as the pointer sweeps across the row.
+  if (showNameOnHover) {
+    return (
+      <TooltipProvider delay={150} closeDelay={0}>
+        {group}
+      </TooltipProvider>
+    );
+  }
+
+  return group;
+}
+
+export { AvatarGroup, avatarGroupVariants };