@elabs-ai/components-ai 4.0.0

package/src/selection-toolbar.test.tsx

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { readSelectionWithin, SelectionToolbar } from "./selection-toolbar";
+
+function mockSelection(node: Node | null, text: string, collapsed = false) {
+  const range = {
+    getBoundingClientRect: () => ({
+      top: 100,
+      left: 50,
+      width: text ? 80 : 0,
+      height: text ? 18 : 0,
+      right: 130,
+      bottom: 118,
+      x: 50,
+      y: 100,
+      toJSON: () => ({}),
+    }),
+  };
+  return {
+    isCollapsed: collapsed,
+    rangeCount: collapsed ? 0 : 1,
+    anchorNode: node,
+    focusNode: node,
+    toString: () => text,
+    getRangeAt: () => range,
+  } as unknown as Selection;
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("readSelectionWithin", () => {
+  it("returns null for a collapsed selection", () => {
+    const container = document.createElement("div");
+    vi.spyOn(window, "getSelection").mockReturnValue(mockSelection(container, "", true));
+    expect(readSelectionWithin(container)).toBeNull();
+  });
+
+  it("returns a snapshot for a non-empty selection inside the container", () => {
+    const container = document.createElement("div");
+    const child = document.createElement("p");
+    container.appendChild(child);
+    vi.spyOn(window, "getSelection").mockReturnValue(mockSelection(child, "hello"));
+    const snap = readSelectionWithin(container);
+    expect(snap?.text).toBe("hello");
+    expect(snap?.rect.width).toBe(80);
+  });
+
+  it("returns null when the selection is outside the container", () => {
+    const container = document.createElement("div");
+    const outside = document.createElement("p");
+    vi.spyOn(window, "getSelection").mockReturnValue(mockSelection(outside, "hello"));
+    expect(readSelectionWithin(container)).toBeNull();
+  });
+});
+
+describe("SelectionToolbar", () => {
+  it("shows a Quote toolbar over a selection and calls onQuote", async () => {
+    const user = userEvent.setup();
+    const onQuote = vi.fn();
+    render(
+      <SelectionToolbar data-testid="region" onQuote={onQuote}>
+        <p>Quote me please, this is the transcript.</p>
+      </SelectionToolbar>,
+    );
+    const region = screen.getByTestId("region");
+    const para = screen.getByText(/Quote me please/);
+    vi.spyOn(window, "getSelection").mockReturnValue(mockSelection(para, "Quote me please"));
+
+    fireEvent.pointerUp(region);
+
+    const quote = await screen.findByRole("button", { name: /Quote/ });
+    await user.click(quote);
+    expect(onQuote).toHaveBeenCalledWith("Quote me please");
+  });
+
+  it("does not open when disabled", () => {
+    render(
+      <SelectionToolbar data-testid="region" disabled onQuote={vi.fn()}>
+        <p>Some text</p>
+      </SelectionToolbar>,
+    );
+    const region = screen.getByTestId("region");
+    const para = screen.getByText("Some text");
+    vi.spyOn(window, "getSelection").mockReturnValue(mockSelection(para, "Some text"));
+    fireEvent.pointerUp(region);
+    expect(screen.queryByRole("button", { name: /Quote/ })).not.toBeInTheDocument();
+  });
+});

package/src/selection-toolbar.tsx

@@ -0,0 +1,192 @@
+"use client";
+
+/**
+ * SelectionToolbar — a floating toolbar over selected transcript text.
+ *
+ * Wrap a transcript region; when the user selects text inside it, a small
+ * toolbar floats above the selection with a single default action: Quote.
+ * `onQuote(selectedText)` fires — the consumer prepends a `>`-prefixed
+ * blockquote into the composer. Positioned with the `@elabs-ai/components-ui` Popover
+ * primitives (a virtual anchor at the selection rect); dismisses when the
+ * selection collapses. Presentational only.
+ */
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from "react";
+import { Quote } from "lucide-react";
+import { Button, Popover, PopoverAnchor, PopoverContent } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useLocale } from "@elabs-ai/components-ui";
+
+/** A captured selection snapshot: the trimmed text + its viewport rect. */
+export interface SelectionSnapshot {
+  text: string;
+  rect: { top: number; left: number; width: number; height: number };
+}
+
+function isEditableNode(node: Node | null): boolean {
+  let el: Node | null = node;
+  while (el) {
+    if (el instanceof HTMLElement) {
+      const tag = el.tagName;
+      if (tag === "INPUT" || tag === "TEXTAREA" || el.isContentEditable) return true;
+    }
+    el = el.parentNode;
+  }
+  return false;
+}
+
+/**
+ * Read the current selection if it is a non-empty range fully inside
+ * `container` (and not inside a form field / editor). Returns `null` otherwise.
+ * Exported for testing + custom integrations.
+ */
+export function readSelectionWithin(container: HTMLElement | null): SelectionSnapshot | null {
+  if (!container || typeof window === "undefined") return null;
+  const selection = window.getSelection();
+  if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;
+
+  const text = selection.toString().trim();
+  if (text.length === 0) return null;
+
+  const { anchorNode, focusNode } = selection;
+  if (!anchorNode || !focusNode) return null;
+  if (!container.contains(anchorNode) || !container.contains(focusNode)) return null;
+  if (isEditableNode(anchorNode)) return null;
+
+  const rect = selection.getRangeAt(0).getBoundingClientRect();
+  if (rect.width <= 0 && rect.height <= 0) return null;
+
+  return {
+    text,
+    rect: { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
+  };
+}
+
+export interface SelectionToolbarProps extends HTMLAttributes<HTMLDivElement> {
+  /** Called with the selected text when the user clicks Quote. */
+  onQuote?: (selectedText: string) => void;
+  /** Quote button label. @default "Quote" */
+  quoteLabel?: string;
+  /** Extra toolbar controls rendered after the Quote button. */
+  actions?: ReactNode;
+  /** Disable selection detection entirely. */
+  disabled?: boolean;
+  /** The transcript region to watch for selections. */
+  children: ReactNode;
+}
+
+/**
+ * Wraps a region and shows a floating Quote toolbar over selected text.
+ * The wrapper renders inline (`display: contents` is avoided — it's a real
+ * relative box) so the anchor + portal position correctly.
+ */
+export const SelectionToolbar = forwardRef<HTMLDivElement, SelectionToolbarProps>(
+  function SelectionToolbar(
+    { onQuote, quoteLabel = "Quote", actions, disabled = false, className, children, ...props },
+    ref,
+  ) {
+    const { t } = useLocale();
+    const containerRef = useRef<HTMLDivElement | null>(null);
+    const [snapshot, setSnapshot] = useState<SelectionSnapshot | null>(null);
+    const open = snapshot !== null;
+
+    const setContainer = useCallback(
+      (node: HTMLDivElement | null) => {
+        containerRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
+      [ref],
+    );
+
+    const refresh = useCallback(() => {
+      if (disabled) return;
+      setSnapshot(readSelectionWithin(containerRef.current));
+    }, [disabled]);
+
+    const dismiss = useCallback(() => setSnapshot(null), []);
+
+    // Open after the user finishes selecting; close when the selection collapses.
+    useEffect(() => {
+      if (disabled || typeof document === "undefined") return;
+      const onSelectionChange = () => {
+        const sel = window.getSelection();
+        if (!sel || sel.isCollapsed || sel.toString().trim().length === 0) dismiss();
+      };
+      const onScroll = () => dismiss();
+      const onKeyDown = (e: KeyboardEvent) => {
+        if (e.key === "Escape") dismiss();
+      };
+      document.addEventListener("selectionchange", onSelectionChange);
+      window.addEventListener("scroll", onScroll, true);
+      document.addEventListener("keydown", onKeyDown);
+      return () => {
+        document.removeEventListener("selectionchange", onSelectionChange);
+        window.removeEventListener("scroll", onScroll, true);
+        document.removeEventListener("keydown", onKeyDown);
+      };
+    }, [disabled, dismiss]);
+
+    const handleQuote = () => {
+      if (snapshot) onQuote?.(snapshot.text);
+      dismiss();
+    };
+
+    const rect = snapshot?.rect;
+
+    return (
+      <div
+        ref={setContainer}
+        className={cn("relative", className)}
+        onPointerUp={refresh}
+        onKeyUp={refresh}
+        {...props}
+      >
+        {children}
+
+        <Popover open={open} onOpenChange={(next) => (next ? undefined : dismiss())}>
+          {/* Virtual anchor positioned at the selection rect (viewport coords). */}
+          <PopoverAnchor asChild>
+            <span
+              aria-hidden="true"
+              className="pointer-events-none fixed"
+              style={
+                rect
+                  ? { top: rect.top, left: rect.left, width: rect.width, height: rect.height }
+                  : { top: 0, left: 0, width: 0, height: 0 }
+              }
+            />
+          </PopoverAnchor>
+          <PopoverContent
+            side="top"
+            align="center"
+            sideOffset={8}
+            // On open, let focus move to the Quote button so the action is
+            // keyboard-reachable (a11y: mouse-operable ⇒ keyboard-operable). The
+            // captured snapshot text drives the quote, so a grayed selection is
+            // fine. On close, DON'T return focus to the anchor (it's an
+            // aria-hidden virtual span) — prevent that jump.
+            onCloseAutoFocus={(e) => e.preventDefault()}
+            className="flex w-auto items-center gap-1 p-1"
+            role="toolbar"
+            aria-label={t("ai.selectionToolbar.label")}
+          >
+            <Button size="sm" variant="ghost" onClick={handleQuote}>
+              <Quote aria-hidden="true" className="size-4" />
+              {quoteLabel}
+            </Button>
+            {actions}
+          </PopoverContent>
+        </Popover>
+      </div>
+    );
+  },
+);

package/src/shimmer.stories.tsx

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Shimmer } from "./shimmer";
+const meta = {
+  title: "AI/Shimmer",
+  component: Shimmer,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Shimmer>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = { render: () => <Shimmer>Generating response…</Shimmer> };

package/src/shimmer.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { useReducedMotion } from "@elabs-ai/components-tokens";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { MotionProps } from "motion/react";
+import { motion } from "motion/react";
+import type { CSSProperties, ElementType, JSX } from "react";
+import { memo, useMemo } from "react";
+
+type MotionHTMLProps = MotionProps & Record<string, unknown>;
+
+// Cache motion components at module level to avoid creating during render
+const motionComponentCache = new Map<
+  keyof JSX.IntrinsicElements,
+  React.ComponentType<MotionHTMLProps>
+>();
+
+const getMotionComponent = (element: keyof JSX.IntrinsicElements) => {
+  let component = motionComponentCache.get(element);
+  if (!component) {
+    component = motion.create(element);
+    motionComponentCache.set(element, component);
+  }
+  return component;
+};
+
+export interface TextShimmerProps {
+  children: string;
+  as?: ElementType;
+  className?: string;
+  duration?: number;
+  spread?: number;
+}
+
+const ShimmerComponent = ({
+  children,
+  as: Component = "p",
+  className,
+  duration = 2,
+  spread = 2,
+}: TextShimmerProps) => {
+  const MotionComponent = getMotionComponent(Component as keyof JSX.IntrinsicElements);
+
+  // The CSS --motion-factor gate cannot reach this JS timeline; resolve the
+  // motion preference (user > OS) here and stop the infinite sweep when reduced.
+  const reducedMotion = useReducedMotion();
+
+  const dynamicSpread = useMemo(() => (children?.length ?? 0) * spread, [children, spread]);
+
+  return (
+    <MotionComponent
+      animate={{ backgroundPosition: "0% center" }}
+      className={cn(
+        "relative inline-block bg-[length:250%_100%,auto] bg-clip-text text-transparent",
+        "[--bg:linear-gradient(90deg,#0000_calc(50%-var(--spread)),var(--color-background),#0000_calc(50%+var(--spread)))] [background-repeat:no-repeat,padding-box]",
+        className,
+      )}
+      initial={{ backgroundPosition: "100% center" }}
+      style={
+        {
+          "--spread": `${dynamicSpread}px`,
+          backgroundImage:
+            "var(--bg), linear-gradient(var(--color-muted-foreground), var(--color-muted-foreground))",
+        } as CSSProperties
+      }
+      transition={
+        reducedMotion
+          ? { duration: 0, repeat: 0 }
+          : {
+              duration,
+              ease: "linear",
+              repeat: Number.POSITIVE_INFINITY,
+            }
+      }
+    >
+      {children}
+    </MotionComponent>
+  );
+};
+
+export const Shimmer = memo(ShimmerComponent);

package/src/snippet.stories.tsx

@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Snippet, SnippetAddon, SnippetCopyButton, SnippetInput } from "./snippet";
+const meta = {
+  title: "AI/Snippet",
+  component: Snippet,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Snippet>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <Snippet code="npm i @elabs-ai/components-ui" className="max-w-sm">
+      <SnippetInput />
+      <SnippetAddon align="inline-end">
+        <SnippetCopyButton />
+      </SnippetAddon>
+    </Snippet>
+  ),
+};

package/src/snippet.test.tsx

@@ -0,0 +1,116 @@
+/**
+ * snippet.test.tsx — smoke + copy-contract lock for the one-line snippet (#59).
+ *
+ * `Snippet` is the "here is the command, take it" surface. Two contracts:
+ * the code travels through context (so `SnippetInput` and `SnippetCopyButton`
+ * can never disagree about WHAT gets copied), and the icon-only copy control
+ * carries an accessible name from the locale seam — never a bare glyph.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { Snippet, SnippetAddon, SnippetCopyButton, SnippetInput, SnippetText } from "./snippet";
+
+const CODE = "pnpm add @elabs-ai/components-ui";
+
+/** Install a clipboard stub for one test; returns the writeText spy. */
+function stubClipboard(impl: () => Promise<void> = () => Promise.resolve()) {
+  const writeText = vi.fn(impl);
+  Object.defineProperty(navigator, "clipboard", {
+    value: { writeText },
+    configurable: true,
+    writable: true,
+  });
+  return writeText;
+}
+
+function renderSnippet(extra?: React.ReactNode) {
+  return render(
+    <Snippet code={CODE}>
+      <SnippetInput />
+      <SnippetAddon align="inline-end">
+        <SnippetCopyButton />
+        {extra}
+      </SnippetAddon>
+    </Snippet>,
+  );
+}
+
+describe("Snippet — the code channel", () => {
+  it("renders the code in a read-only field (selectable, never editable)", () => {
+    renderSnippet();
+    const field = screen.getByRole("textbox");
+    expect(field).toHaveValue(CODE);
+    expect(field).toHaveAttribute("readonly");
+  });
+
+  it("renders an optional prompt prefix via SnippetText", () => {
+    render(
+      <Snippet code={CODE}>
+        <SnippetAddon align="inline-start">
+          <SnippetText>$</SnippetText>
+        </SnippetAddon>
+        <SnippetInput />
+      </Snippet>,
+    );
+    expect(screen.getByText("$")).toBeInTheDocument();
+  });
+
+  it("uses a monospace face for the snippet frame", () => {
+    const { container } = renderSnippet();
+    expect(container.querySelector(".font-mono")).not.toBeNull();
+  });
+});
+
+describe("SnippetCopyButton", () => {
+  it("is an icon-only control with an accessible name from the locale seam", () => {
+    stubClipboard();
+    renderSnippet();
+    expect(screen.getByRole("button", { name: "Copy" })).toBeInTheDocument();
+  });
+
+  it("copies the SAME code the field shows (both read one context)", async () => {
+    const writeText = stubClipboard();
+    renderSnippet();
+    fireEvent.click(screen.getByRole("button", { name: "Copy" }));
+    await waitFor(() => expect(writeText).toHaveBeenCalledWith(CODE));
+  });
+
+  it("reports a clipboard rejection through onError instead of throwing", async () => {
+    stubClipboard(() => Promise.reject(new Error("denied")));
+    const onError = vi.fn();
+    render(
+      <Snippet code={CODE}>
+        <SnippetInput />
+        <SnippetCopyButton onError={onError} />
+      </Snippet>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Copy" }));
+    await waitFor(() => expect(onError).toHaveBeenCalled());
+  });
+
+  it("reports an UNAVAILABLE clipboard through onError (insecure context / old browser)", () => {
+    Object.defineProperty(navigator, "clipboard", { value: undefined, configurable: true });
+    const onError = vi.fn();
+    render(
+      <Snippet code={CODE}>
+        <SnippetInput />
+        <SnippetCopyButton onError={onError} />
+      </Snippet>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Copy" }));
+    expect(onError).toHaveBeenCalled();
+  });
+
+  it("fires onCopy once the write resolves", async () => {
+    stubClipboard();
+    const onCopy = vi.fn();
+    render(
+      <Snippet code={CODE}>
+        <SnippetInput />
+        <SnippetCopyButton onCopy={onCopy} />
+      </Snippet>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Copy" }));
+    await waitFor(() => expect(onCopy).toHaveBeenCalledTimes(1));
+  });
+});

package/src/snippet.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useLocale } from "@elabs-ai/components-ui";
+import { CheckIcon, CopyIcon } from "lucide-react";
+import type { ComponentProps } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+interface SnippetContextType {
+  code: string;
+}
+
+const SnippetContext = createContext<SnippetContextType>({
+  code: "",
+});
+
+export type SnippetProps = ComponentProps<typeof InputGroup> & {
+  code: string;
+};
+
+export const Snippet = ({ code, className, children, ...props }: SnippetProps) => {
+  const contextValue = useMemo(() => ({ code }), [code]);
+
+  return (
+    <SnippetContext.Provider value={contextValue}>
+      <InputGroup className={cn("font-mono", className)} {...props}>
+        {children}
+      </InputGroup>
+    </SnippetContext.Provider>
+  );
+};
+
+export type SnippetAddonProps = ComponentProps<typeof InputGroupAddon>;
+
+export const SnippetAddon = (props: SnippetAddonProps) => <InputGroupAddon {...props} />;
+
+export type SnippetTextProps = ComponentProps<typeof InputGroupText>;
+
+export const SnippetText = ({ className, ...props }: SnippetTextProps) => (
+  <InputGroupText className={cn("ps-2 font-normal text-muted-foreground", className)} {...props} />
+);
+
+export type SnippetInputProps = Omit<ComponentProps<typeof InputGroupInput>, "readOnly" | "value">;
+
+export const SnippetInput = ({ className, ...props }: SnippetInputProps) => {
+  const { code } = useContext(SnippetContext);
+
+  return (
+    <InputGroupInput
+      className={cn("text-foreground", className)}
+      readOnly
+      value={code}
+      {...props}
+    />
+  );
+};
+
+export type SnippetCopyButtonProps = ComponentProps<typeof InputGroupButton> & {
+  onCopy?: () => void;
+  onError?: (error: Error) => void;
+  timeout?: number;
+};
+
+export const SnippetCopyButton = ({
+  onCopy,
+  onError,
+  timeout = 2000,
+  children,
+  className,
+  ...props
+}: SnippetCopyButtonProps) => {
+  const { t } = useLocale();
+  const [isCopied, setIsCopied] = useState(false);
+  const timeoutRef = useRef<number>(0);
+  const { code } = useContext(SnippetContext);
+
+  const copyToClipboard = useCallback(async () => {
+    if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+      onError?.(new Error("Clipboard API not available"));
+      return;
+    }
+
+    try {
+      if (!isCopied) {
+        await navigator.clipboard.writeText(code);
+        setIsCopied(true);
+        onCopy?.();
+        timeoutRef.current = window.setTimeout(() => setIsCopied(false), timeout);
+      }
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  }, [code, onCopy, onError, timeout, isCopied]);
+
+  useEffect(
+    () => () => {
+      window.clearTimeout(timeoutRef.current);
+    },
+    [],
+  );
+
+  const Icon = isCopied ? CheckIcon : CopyIcon;
+
+  return (
+    <InputGroupButton
+      aria-label={t("copy")}
+      className={className}
+      onClick={copyToClipboard}
+      size="icon-sm"
+      title={t("copy")}
+      {...props}
+    >
+      {children ?? (
+        <span
+          key={isCopied ? "check" : "copy"}
+          className="flex animate-in fade-in-0 zoom-in-95 duration-fast ease-entrance"
+        >
+          <Icon className="size-3.5" size={14} />
+        </span>
+      )}
+    </InputGroupButton>
+  );
+};

package/src/sources.stories.tsx

@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Source, SourceList, Sources, SourcesContent, SourcesTrigger } from "./sources";
+const meta = {
+  title: "AI/Sources",
+  component: Sources,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Sources>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <Sources>
+      <SourcesTrigger count={2} />
+      <SourcesContent>
+        <Source href="https://docs.acme.com" title="Acme Docs" />
+        <Source href="https://ci.acme.com" title="CI run #42" />
+      </SourcesContent>
+    </Sources>
+  ),
+};
+// SourceList — the per-answer grounding footer preset (#191, research 11 §B.4).
+export const GroundingFooter: Story = {
+  name: "SourceList",
+  render: () => (
+    <SourceList
+      defaultOpen
+      sources={[
+        { href: "https://warehouse.acme.com/q3-retention", title: "Q3 retention cohort" },
+        { href: "https://crm.acme.com/renewals", title: "Renewal desk log" },
+        { href: "https://docs.acme.com/churn", title: "Churn playbook" },
+      ]}
+    />
+  ),
+};