@elabs-ai/components-ui 4.0.0

package/src/components/hover-card/hover-card.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor, within } from "storybook/test";
+import { Button } from "../button";
+import { HoverCard, HoverCardContent, HoverCardTrigger } from "./hover-card";
+const meta = {
+  title: "Overlays/HoverCard",
+  component: HoverCard,
+  tags: ["autodocs"],
+  argTypes: {
+    open: {
+      description: "Controlled open state of the hover card.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    defaultOpen: {
+      description: "Uncontrolled initial open state.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    onOpenChange: {
+      description: "Callback when the open state changes.",
+      control: false,
+      table: { category: "Events" },
+    },
+    openDelay: {
+      description: "Milliseconds to wait before opening on pointer enter. Default 700.",
+      control: "number",
+      table: { category: "Behaviour" },
+    },
+    closeDelay: {
+      description: "Milliseconds to wait before closing on pointer leave. Default 300.",
+      control: "number",
+      table: { category: "Behaviour" },
+    },
+  },
+} satisfies Meta<typeof HoverCard>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <HoverCard openDelay={0} closeDelay={0}>
+      <HoverCardTrigger asChild>
+        <Button variant="link">@brand</Button>
+      </HoverCardTrigger>
+      <HoverCardContent>The brand-ui design system.</HoverCardContent>
+    </HoverCard>
+  ),
+  // Hovers over the trigger (delay zeroed for determinism) to open the portalled
+  // hover card and confirms the content is visible.
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("button", { name: "@brand" });
+    await userEvent.hover(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    const card = await body.findByText("The brand-ui design system.");
+    await waitFor(() => expect(card).toBeVisible());
+  },
+};

package/src/components/hover-card/hover-card.tsx

@@ -0,0 +1,25 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "react";
+import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
+import { cn } from "../../lib/cn";
+
+export const HoverCard = HoverCardPrimitive.Root;
+export const HoverCardTrigger = HoverCardPrimitive.Trigger;
+
+export const HoverCardContent = forwardRef<
+  ElementRef<typeof HoverCardPrimitive.Content>,
+  ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content>
+>(function HoverCardContent({ className, align = "center", sideOffset = 4, ...props }, ref) {
+  return (
+    <HoverCardPrimitive.Content
+      ref={ref}
+      align={align}
+      sideOffset={sideOffset}
+      className={cn(
+        "z-50 w-64 rounded-md bg-popover p-4 text-popover-foreground shadow-ring-md outline-none",
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+        className,
+      )}
+      {...props}
+    />
+  );
+});

package/src/components/hover-card/index.ts

@@ -0,0 +1 @@
+export { HoverCard, HoverCardTrigger, HoverCardContent } from "./hover-card";

package/src/components/icon-button/icon-button.stories.tsx

@@ -0,0 +1,108 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor, within } from "storybook/test";
+import { RefreshCw, Trash2 } from "lucide-react";
+import { IconButton } from "./icon-button";
+
+const meta = {
+  title: "Core/IconButton",
+  component: IconButton,
+  tags: ["autodocs"],
+  args: {
+    label: "Refresh",
+    icon: <RefreshCw aria-hidden="true" />,
+  },
+  argTypes: {
+    label: {
+      description: "Accessible name AND tooltip text — a single source of truth.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    icon: { control: false, table: { category: "Content" } },
+    variant: {
+      control: "select",
+      options: [
+        "default",
+        "secondary",
+        "destructive",
+        "outline",
+        "outline-subtle",
+        "ghost",
+        "link",
+      ],
+      table: { category: "Appearance" },
+    },
+    size: {
+      control: "select",
+      options: ["icon", "icon-sm", "icon-lg"],
+      table: { category: "Appearance" },
+    },
+    disabled: { control: "boolean", table: { category: "State" } },
+    disabledReason: {
+      description:
+        "Shown appended to the tooltip and exposed via aria-describedby, even while disabled.",
+      control: "text",
+      table: { category: "State" },
+    },
+    side: {
+      control: "select",
+      options: ["top", "right", "bottom", "left"],
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof IconButton>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  // Opens on keyboard focus (no pointer) — the a11y-critical path this
+  // component exists for (#335). The tooltip content is Radix-portalled to
+  // `document.body`, outside the story's own canvas root — query the owner
+  // document's body, not `canvas` (mirrors Overlays/Tooltip's Default story).
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const button = canvas.getByRole("button", { name: "Refresh" });
+    await expect(button).not.toHaveAttribute("title");
+    await userEvent.tab();
+    await expect(button).toHaveFocus();
+    const body = within(canvasElement.ownerDocument.body);
+    const tooltip = await body.findByText("Refresh", { selector: "[data-side]" });
+    await waitFor(() => expect(tooltip).toBeVisible());
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+  play: async ({ canvas }) => {
+    const button = canvas.getByRole("button", { name: "Refresh" });
+    await expect(button).toBeDisabled();
+  },
+};
+
+/** A disabled control that still explains WHY via the tooltip + `aria-describedby`. */
+export const DisabledWithReason: Story = {
+  name: "Disabled (with reason)",
+  args: {
+    label: "Delete",
+    icon: <Trash2 aria-hidden="true" />,
+    variant: "destructive",
+    disabled: true,
+    disabledReason: "You don't have permission to delete this item.",
+  },
+  play: async ({ canvas }) => {
+    const button = canvas.getByRole("button", { name: "Delete" });
+    await expect(button).toBeDisabled();
+    const describedBy = button.getAttribute("aria-describedby");
+    await expect(describedBy).toBeTruthy();
+    const description = canvas.getByText("You don't have permission to delete this item.");
+    await expect(description.id).toBe(describedBy);
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-2">
+      <IconButton {...args} size="icon-sm" label="Small" />
+      <IconButton {...args} size="icon" label="Default" />
+      <IconButton {...args} size="icon-lg" label="Large" />
+    </div>
+  ),
+};

package/src/components/icon-button/icon-button.test.tsx

@@ -0,0 +1,93 @@
+import { createRef } from "react";
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { RefreshCw } from "lucide-react";
+import { IconButton } from "./icon-button";
+
+describe("IconButton", () => {
+  it("has exactly one accessible name and no title attribute anywhere in the output", () => {
+    render(<IconButton label="Refresh" icon={<RefreshCw aria-hidden="true" />} />);
+    const button = screen.getByRole("button", { name: "Refresh" });
+    expect(button).not.toHaveAttribute("title");
+    expect(document.querySelector("[title]")).toBeNull();
+  });
+
+  it("opens the tooltip on keyboard focus alone (no pointer interaction)", async () => {
+    render(<IconButton label="Refresh" icon={<RefreshCw aria-hidden="true" />} />);
+    await userEvent.tab();
+    expect(screen.getByRole("button", { name: "Refresh" })).toHaveFocus();
+    const tooltip = await screen.findByText("Refresh", { selector: "[data-side]" });
+    await waitFor(() => expect(tooltip).toBeVisible());
+  });
+
+  it("exposes disabledReason via aria-describedby on an always-present element, even while pointer-events-none", () => {
+    render(
+      <IconButton
+        label="Delete"
+        icon={<RefreshCw aria-hidden="true" />}
+        disabled
+        disabledReason="You don't have permission"
+      />,
+    );
+    const button = screen.getByRole("button", { name: "Delete" });
+    expect(button).toBeDisabled();
+    const describedBy = button.getAttribute("aria-describedby");
+    expect(describedBy).toBeTruthy();
+    const node = describedBy ? document.getElementById(describedBy) : null;
+    expect(node).not.toBeNull();
+    expect(node).toHaveTextContent("You don't have permission");
+  });
+
+  it("does not render a description node (or aria-describedby) when no disabledReason is given", () => {
+    render(<IconButton label="Refresh" icon={<RefreshCw aria-hidden="true" />} />);
+    const button = screen.getByRole("button", { name: "Refresh" });
+    expect(button).not.toHaveAttribute("aria-describedby");
+  });
+
+  // While disabled, the wrapper span — not the button — is the tab stop, so it
+  // must carry the tokened focus ring; without it the browser's own hardcoded
+  // blue outline shows through, identically in every theme.
+  it("gives the disabled-state tab stop the tokened focus ring", async () => {
+    render(
+      <IconButton
+        label="Delete"
+        icon={<RefreshCw aria-hidden="true" />}
+        disabled
+        disabledReason="No permission"
+      />,
+    );
+    const wrapper = document.querySelector('[data-slot="icon-button"]')!;
+    expect(wrapper).toHaveAttribute("tabindex", "0");
+    expect(wrapper.className).toContain("focus-visible:ring-ring");
+    await userEvent.tab();
+    expect(wrapper).toHaveFocus();
+  });
+
+  it("does not put the wrapper in the tab order when enabled (no phantom stop)", async () => {
+    render(<IconButton label="Refresh" icon={<RefreshCw aria-hidden="true" />} />);
+    const wrapper = document.querySelector('[data-slot="icon-button"]')!;
+    expect(wrapper).not.toHaveAttribute("tabindex");
+    await userEvent.tab();
+    expect(screen.getByRole("button", { name: "Refresh" })).toHaveFocus();
+  });
+
+  it("forwards the ref to the underlying <button>", () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(<IconButton ref={ref} label="Refresh" icon={<RefreshCw aria-hidden="true" />} />);
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+    expect(ref.current).toBe(screen.getByRole("button", { name: "Refresh" }));
+  });
+
+  it("cannot have its computed aria-label overridden by a stray prop (single source of truth)", () => {
+    // TypeScript's JSX checker special-cases aria-*/data-* attribute names on
+    // ANY element regardless of the declared prop type, so `aria-label` is
+    // syntactically accepted here even though `IconButtonProps` omits it —
+    // this test locks the RUNTIME guarantee that it can never win.
+    render(
+      <IconButton label="Refresh" icon={<RefreshCw aria-hidden="true" />} aria-label="Wrong" />,
+    );
+    expect(screen.getByRole("button", { name: "Refresh" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Wrong" })).not.toBeInTheDocument();
+  });
+});

package/src/components/icon-button/icon-button.tsx

@@ -0,0 +1,139 @@
+import {
+  forwardRef,
+  useId,
+  type ButtonHTMLAttributes,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import type { VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+import { Button } from "../button";
+import type { buttonVariants } from "../button";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../tooltip";
+
+/** The icon-only size axis (a deliberate subset of `buttonVariants`' `size`). */
+export type IconButtonSize = "icon" | "icon-sm" | "icon-lg";
+
+export interface IconButtonProps
+  extends
+    Omit<
+      ButtonHTMLAttributes<HTMLButtonElement>,
+      "title" | "children" | "aria-label" | "aria-describedby"
+    >,
+    Pick<VariantProps<typeof buttonVariants>, "variant"> {
+  /**
+   * Accessible name AND tooltip text — a single source of truth, so the two
+   * can never drift out of sync (the failure this component exists to close:
+   * `aria-label` and a tooltip's children set independently, most call sites
+   * only setting one).
+   */
+  label: string;
+  /** The glyph (typically a `lucide-react` element). */
+  icon: ReactNode;
+  /** Icon-only size axis. Default `"icon"`. */
+  size?: IconButtonSize;
+  /**
+   * Shown appended to the tooltip text, and — independently — exposed via
+   * `aria-describedby` through an `sr-only` node that is present whenever this
+   * prop is (i.e. it does NOT depend on the tooltip being open, and it is not
+   * rendered at all when there is no reason — so it can never be read as stray
+   * text), so assistive tech gets the reason even while the button is disabled
+   * (a disabled
+   * `<button>` still exposes its ARIA attributes; it just isn't
+   * focusable/hoverable itself, which is why the tooltip trigger wraps a
+   * focusable `<span>` instead — see the render below).
+   */
+  disabledReason?: string;
+  /** Tooltip placement. Default `"top"`. */
+  side?: ComponentProps<typeof TooltipContent>["side"];
+}
+
+/**
+ * A single affordance for an icon-only control: `label` becomes both the
+ * `aria-label` and the tooltip text, so they cannot diverge. Composes
+ * `Button` + `Tooltip` — it does not reimplement either.
+ *
+ * Deliberately has **no `asChild`**: accepting one would dissolve the button
+ * into a Radix `Slot` and break the tooltip-trigger wrapper below. A
+ * link-styled icon button should compose `Button asChild` + `Tooltip`
+ * directly instead.
+ */
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(function IconButton(
+  {
+    label,
+    icon,
+    variant = "ghost",
+    size = "icon",
+    disabled,
+    disabledReason,
+    side = "top",
+    className,
+    ...props
+  },
+  ref,
+) {
+  const reasonId = useId();
+  // The visible tooltip text always LEADS with `label` verbatim (never only
+  // the reason), so it can never contradict the accessible name (WCAG 2.5.3
+  // Label in Name) — the reason is appended context, not a replacement name.
+  const tooltipText = disabledReason ? `${label} — ${disabledReason}` : label;
+
+  return (
+    // Self-provided so this works anywhere — a consumer shouldn't have to
+    // remember to mount a global TooltipProvider for one icon button.
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          {/*
+           * A disabled `Button` carries `pointer-events-none`, so hover never
+           * reaches it and the tooltip would never open. Wrap the trigger
+           * around a plain <span> instead of the <button> itself: it stays
+           * hoverable always, and gains `tabIndex={0}` only while the inner
+           * control is disabled (and therefore removed from the tab order),
+           * so keyboard users can still reach the tooltip without a doubled
+           * stop when the button is enabled.
+           */}
+          <span
+            data-slot="icon-button"
+            tabIndex={disabled ? 0 : undefined}
+            className={cn(
+              "inline-flex rounded-md",
+              // While disabled this span IS the focus target (the button is out
+              // of the tab order), so it must carry the system's focus ring —
+              // without this it falls back to the UA default outline, which is
+              // a hardcoded browser blue identical in all three themes.
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+              disabled && "cursor-not-allowed",
+            )}
+          >
+            <Button
+              ref={ref}
+              variant={variant}
+              size={size}
+              disabled={disabled}
+              {...props}
+              // Computed AFTER the spread so a stray `aria-label`/`aria-describedby`
+              // in `...props` can never win over the derived, single-source-of-truth
+              // values (the type above already excludes both, this is defense in
+              // depth for untyped/JS callers).
+              aria-label={label}
+              aria-describedby={disabledReason ? reasonId : undefined}
+              data-slot="icon-button-control"
+              className={className}
+            >
+              {icon}
+            </Button>
+          </span>
+        </TooltipTrigger>
+        <TooltipContent side={side} data-slot="icon-button-tooltip">
+          {tooltipText}
+        </TooltipContent>
+      </Tooltip>
+      {disabledReason ? (
+        <span id={reasonId} data-slot="icon-button-description" className="sr-only">
+          {disabledReason}
+        </span>
+      ) : null}
+    </TooltipProvider>
+  );
+});

package/src/components/icon-button/index.ts

@@ -0,0 +1 @@
+export { IconButton, type IconButtonProps, type IconButtonSize } from "./icon-button";

package/src/components/input/index.ts

@@ -0,0 +1 @@
+export { Input, type InputProps } from "./input";

package/src/components/input/input.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Input } from "./input";
+
+const meta = {
+  title: "Core/Input",
+  component: Input,
+  tags: ["autodocs"],
+  args: { placeholder: "you@example.com" },
+  argTypes: {
+    type: {
+      description:
+        "HTML input type — controls browser behaviour, autocomplete, and mobile keyboard.",
+      control: { type: "select" },
+      options: ["text", "email", "password", "number", "tel", "url", "search", "date", "file"],
+      table: { category: "Behavior" },
+    },
+    placeholder: {
+      description: "Placeholder hint (should show an example, end with …).",
+      control: "text",
+      table: { category: "Content" },
+    },
+    disabled: {
+      description: "Disables the input — cursor-not-allowed, reduced opacity, muted background.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    "aria-invalid": {
+      description: "Marks the field invalid — shows destructive ring / border.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn().",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof Input>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+export const Invalid: Story = { args: { "aria-invalid": true, defaultValue: "not-an-email" } };
+export const Disabled: Story = { args: { disabled: true, value: "Disabled" } };

package/src/components/input/input.test.tsx

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Input } from "./input";
+
+describe("Input", () => {
+  it("accepts typed text", async () => {
+    render(<Input aria-label="email" />);
+    const el = screen.getByLabelText<HTMLInputElement>("email");
+    await userEvent.type(el, "hi");
+    expect(el.value).toBe("hi");
+  });
+
+  it("is disabled when disabled prop is set", () => {
+    render(<Input aria-label="email" disabled />);
+    const el = screen.getByLabelText<HTMLInputElement>("email");
+    expect(el).toBeDisabled();
+  });
+});

package/src/components/input/input.tsx

@@ -0,0 +1,26 @@
+import { forwardRef, type InputHTMLAttributes } from "react";
+import { cn } from "../../lib/cn";
+
+export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  { className, type = "text", ...props },
+  ref,
+) {
+  return (
+    <input
+      ref={ref}
+      type={type}
+      className={cn(
+        "flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm shadow-sm transition-[color,background-color,border-color,box-shadow] duration-fast ease-standard",
+        "placeholder:text-muted-foreground",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "disabled:cursor-not-allowed disabled:opacity-50 disabled:bg-muted disabled:border-border",
+        "aria-[invalid=true]:border-destructive aria-[invalid=true]:ring-destructive",
+        "file:border-0 file:bg-transparent file:text-sm file:font-medium",
+        className,
+      )}
+      {...props}
+    />
+  );
+});

package/src/components/input-group/index.ts

@@ -0,0 +1,11 @@
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+  inputGroupVariants,
+  inputGroupAddonVariants,
+  type InputGroupProps,
+} from "./input-group";

package/src/components/input-group/input-group.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Search } from "lucide-react";
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+} from "./input-group";
+const meta = {
+  title: "Forms/InputGroup",
+  component: InputGroup,
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      description:
+        "`outline` — bordered form-field look (default). `surface` — soft filled composer look with no hard border. `card` — `bg-card` well for nesting inside an already-tinted outer frame (the double card, #254); its fill is theme-driven, not universally white — raised on light themes, recessed on dark.",
+      control: { type: "radio" },
+      options: ["outline", "surface", "card"],
+      table: { category: "Appearance" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+    children: {
+      description: "Compose with InputGroupAddon, InputGroupInput, InputGroupButton, etc.",
+      control: false,
+      table: { category: "Content" },
+    },
+  },
+} satisfies Meta<typeof InputGroup>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Search_: Story = {
+  name: "Search",
+  render: () => (
+    <InputGroup className="max-w-sm">
+      <InputGroupAddon>
+        <Search />
+      </InputGroupAddon>
+      <InputGroupInput placeholder="Search…" />
+    </InputGroup>
+  ),
+};
+export const WithButton: Story = {
+  render: () => (
+    <InputGroup className="max-w-sm">
+      <InputGroupAddon>
+        <InputGroupText>$</InputGroupText>
+      </InputGroupAddon>
+      <InputGroupInput placeholder="0.00" />
+      <InputGroupAddon align="inline-end">
+        <InputGroupButton size="sm">USD</InputGroupButton>
+      </InputGroupAddon>
+    </InputGroup>
+  ),
+};
+// The composer look (#194, research 08 §C.1): soft `bg-surface-muted` fill +
+// the focus-within ring — no hard border. Used by `PromptInput` in @elabs-ai/components-ai.
+export const Surface: Story = {
+  render: () => (
+    <InputGroup variant="surface" className="max-w-sm">
+      <InputGroupAddon>
+        <Search />
+      </InputGroupAddon>
+      <InputGroupInput placeholder="Ask anything…" />
+    </InputGroup>
+  ),
+};
+// The "double card" well (#254): nest a `card` InputGroup inside an
+// already-tinted outer frame — `PromptInput`'s `tone="card"` prop wires this
+// into the AI composer. The well's fill is theme-driven (raised on light
+// themes, recessed on dark), not universally white.
+export const Card: Story = {
+  render: () => (
+    <div className="max-w-sm rounded-xl bg-surface-muted p-1.5">
+      <InputGroup variant="card">
+        <InputGroupAddon>
+          <Search />
+        </InputGroupAddon>
+        <InputGroupInput placeholder="Ask anything…" />
+      </InputGroup>
+    </div>
+  ),
+};

package/src/components/input-group/input-group.test.tsx

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { InputGroup } from "./input-group";
+
+describe("InputGroup", () => {
+  // Regression lock for #8: the auto-height selector must match ANY descendant
+  // textarea (so it works through PromptInputBody's `display:contents` wrapper),
+  // not just a direct child. jsdom can't compute `:has()` layout, so we lock the
+  // class contract instead.
+  it("uses a descendant `has-[textarea]` selector (not direct-child) to auto-grow", () => {
+    const { container } = render(
+      <InputGroup>
+        <div className="contents">
+          <textarea data-slot="input-group-control" />
+        </div>
+      </InputGroup>,
+    );
+    const group = container.querySelector('[data-slot="input-group"]') as HTMLElement;
+    expect(group).not.toBeNull();
+    expect(group.className).toContain("has-[textarea]:h-auto");
+    expect(group.className).not.toContain("has-[>textarea]");
+  });
+
+  // #194 (research 08 §C.1/§D): the composer variant separates by soft fill +
+  // focus ring, never a hard border; the default stays the form-field outline.
+  it("variant='surface' uses the soft fill with no border; default keeps border-input", () => {
+    const { container } = render(<InputGroup variant="surface" />);
+    const surface = container.querySelector('[data-slot="input-group"]') as HTMLElement;
+    expect(surface.className.split(" ")).toContain("bg-surface-muted");
+    expect(surface.className.split(" ")).not.toContain("border");
+    expect(surface.className).not.toContain("border-input");
+
+    const { container: c2 } = render(<InputGroup />);
+    const outline = c2.querySelector('[data-slot="input-group"]') as HTMLElement;
+    expect(outline.className.split(" ")).toContain("border-input");
+  });
+
+  // #254: the "double card" needs a `bg-card` well with no border of its own
+  // (the outer frame supplies the tint; the well's own fill is theme-driven,
+  // not universally white — see the JSDoc on `inputGroupVariants`).
+  it("variant='card' uses bg-card with no border", () => {
+    const { container } = render(<InputGroup variant="card" />);
+    const card = container.querySelector('[data-slot="input-group"]') as HTMLElement;
+    expect(card.className.split(" ")).toContain("bg-card");
+    expect(card.className.split(" ")).not.toContain("border");
+    expect(card.className).not.toContain("border-input");
+  });
+});