@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/field-row/field-row.tsx

@@ -8,16 +8,43 @@ import {
 } from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { cn } from "../../lib/cn";
+import { hasRenderableContent } from "../../lib/has-renderable-content";
 import { Label } from "../label";
 
 export interface FieldRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
   /** Field label — rendered as a real `<label>`, click-to-focus associated with the control. */
   label: ReactNode;
-  /** Optional help/description text, always visible (not gated by an error). */
+  /**
+   * Optional help/description text, always visible (not gated by an error).
+   * Renders nothing — and contributes no id to `aria-describedby` — when
+   * `description` is falsy (`false`/`0`/`""`/`null`/`undefined`), an empty
+   * array, or an array containing only falsy values (`{list.map(...)}` on an
+   * empty list; `[a && "x", b && "y"]` with both false).
+   *
+   * **Known limit:** a value that is itself a COMPONENT that renders nothing
+   * (returns `null`/an empty fragment) is not knowable before render, so it
+   * still produces an empty paragraph that `aria-describedby` points at.
+   * `FieldDescription` and the wider React ecosystem share this limit — pass
+   * a falsy value instead of a component that may render nothing, e.g.
+   * `description={hasHint ? hintText : undefined}`, never
+   * `description={<MaybeRendersNull />}`.
+   */
   description?: ReactNode;
   /**
    * Validation error text. When present: sets `aria-invalid` on the control,
    * is appended to `aria-describedby`, and is announced via `role="alert"`.
+   * Renders nothing — and leaves `aria-invalid="false"` — when `error` is
+   * falsy (`false`/`0`/`""`/`null`/`undefined`), an empty array, or an array
+   * containing only falsy values (`{errors.map(...)}` on an empty list — the
+   * idiomatic "no errors" shape).
+   *
+   * **Known limit:** a value that is itself a COMPONENT that renders nothing
+   * (returns `null`/an empty fragment) is not knowable before render, so it
+   * still produces an empty `role="alert"` element that `aria-describedby`
+   * points at. `FieldError` and the wider React ecosystem share this limit —
+   * pass a falsy value instead of a component that may render nothing, e.g.
+   * `error={hasError ? message : undefined}`, never
+   * `error={<MaybeRendersNull />}`.
    */
   error?: ReactNode;
   /**
@@ -62,11 +89,19 @@ export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function Field
   const childProps = control.props;
   const controlId = childProps.id ?? `${id}-control`;
 
+  // Same predicate `FieldDescription`/`FieldError` use (`../field/field.tsx`)
+  // — bare truthiness (`description ? … : null`) treats an empty/all-falsy
+  // ARRAY as content, since every array is truthy in JS. `errors.map(...)`
+  // on an empty list is the idiomatic "no errors" shape, so that gap is a
+  // real defect here, not a hypothetical (#93).
+  const hasDescription = hasRenderableContent(description);
+  const hasError = hasRenderableContent(error);
+
   const describedBy =
     [
       childProps["aria-describedby"] ?? null,
-      description ? descriptionId : null,
-      error ? errorId : null,
+      hasDescription ? descriptionId : null,
+      hasError ? errorId : null,
     ]
       .filter(Boolean)
       .join(" ") || undefined;
@@ -86,12 +121,19 @@ export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function Field
       <Slot
         id={controlId}
         aria-describedby={describedBy}
-        aria-invalid={!!error}
+        // `FieldRoot.invalid` (`../field/field.tsx`) is intentionally
+        // INDEPENDENT of whether a `FieldError` with content is mounted — a
+        // caller can mark the control invalid before its message settles.
+        // `FieldRow` has no such prop: `error` is its only invalidity
+        // signal, so "no error content" must mean "not invalid" — deriving
+        // this from raw `!!error` marked `error={[]}` invalid with nothing
+        // to explain why (#93).
+        aria-invalid={hasError}
         data-slot="field-row-control"
       >
         {cloneElement(control, { id: controlId, "aria-describedby": describedBy })}
       </Slot>
-      {description ? (
+      {hasDescription ? (
         <p
           id={descriptionId}
           data-slot="field-row-description"
@@ -100,7 +142,7 @@ export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function Field
           {description}
         </p>
       ) : null}
-      {error ? (
+      {hasError ? (
         <p
           id={errorId}
           role="alert"

package/src/components/file-upload/file-upload.stories.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
 import {
   FileUpload,
   FileUploadDropzone,
@@ -106,6 +107,21 @@ export const Default: Story = {
       </FileUpload>
     </div>
   ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // #322 — the dropzone (`focus-ring-within`) is the sole compound focus
+    // indicator for this composite control; the inner "Browse files" button
+    // must delegate its own indicator to it, never paint a second one.
+    const browseButton = canvas.getByRole("button", { name: "Browse files" });
+    await userEvent.tab();
+    await expect(browseButton).toHaveFocus();
+    const dropzone = browseButton.closest('[data-slot="file-upload-dropzone"]');
+    await expect(dropzone).not.toBeNull();
+    const dropzoneStyle = getComputedStyle(dropzone as HTMLElement);
+    const buttonStyle = getComputedStyle(browseButton);
+    await expect(dropzoneStyle.outlineStyle).toBe("solid");
+    await expect(buttonStyle.outlineStyle).not.toBe("solid");
+  },
 };
 
 export const Uncontrolled: Story = {

package/src/components/file-upload/file-upload.test.tsx

@@ -88,7 +88,11 @@ describe("FileUpload", () => {
     expect(onFilesChange.mock.calls[0]![0]).toHaveLength(0);
   });
 
-  it("FileUploadList renders role=status and aria-live=polite", () => {
+  it("FileUploadList announces via aria-live while keeping its native list role", () => {
+    // NOT role="status" — that would override the <ul>'s implicit `list`
+    // role and strip `listitem` from every <FileUploadItem> inside it
+    // (an axe `listitem` violation). `aria-live="polite"` alone still
+    // announces additions/removals to assistive tech.
     const f = makeUploadFile();
     render(
       <FileUpload files={[f]} onFilesChange={() => {}}>
@@ -97,8 +101,9 @@ describe("FileUpload", () => {
         </FileUploadList>
       </FileUpload>,
     );
-    const list = screen.getByRole("status");
+    const list = screen.getByRole("list");
     expect(list).toHaveAttribute("aria-live", "polite");
+    expect(list).not.toHaveAttribute("role");
   });
 
   it("FileUploadList returns null when no files and no children", () => {

package/src/components/file-upload/file-upload.tsx

@@ -289,7 +289,7 @@ export const FileUploadDropzone = forwardRef<HTMLElement, FileUploadDropzoneProp
           "hover:border-ring hover:bg-accent/50",
           "data-[dragging]:border-primary data-[dragging]:bg-primary/5",
           "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
-          "focus-within:outline-none focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background",
+          "focus-ring-within focus-within:ring-offset-2 focus-within:ring-offset-background",
           className,
         )}
         {...props}
@@ -312,7 +312,11 @@ export const FileUploadDropzone = forwardRef<HTMLElement, FileUploadDropzoneProp
                   }}
                   className={cn(
                     // #399 — inline text trigger inside a sentence → `-text` rung.
-                    "text-primary-text underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm",
+                    "text-primary-text underline-offset-2 hover:underline focus-ring rounded-sm",
+                    // #322 — the dropzone's `focus-ring-within` (above) is the
+                    // one compound indicator for this composite control; this
+                    // button delegates rather than painting a second one.
+                    "focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0",
                     "disabled:pointer-events-none disabled:opacity-50",
                   )}
                 >
@@ -343,9 +347,13 @@ export const FileUploadList = forwardRef<HTMLUListElement, FileUploadListProps>(
     if (files.length === 0 && !children) return null;
 
     return (
+      // `aria-live="polite"` alone is enough to announce additions/removals —
+      // it does NOT require `role="status"`. Adding that role here used to
+      // override the `<ul>`'s implicit `list` role, which strips the
+      // `listitem` role from every `<FileUploadItem>` (`<li>`) inside it and
+      // fails axe's `listitem` rule the moment the list is non-empty.
       <ul
         ref={ref}
-        role="status"
         aria-live="polite"
         aria-label="Selected files"
         data-slot="file-upload-list"
@@ -434,7 +442,10 @@ export const FileUploadItem = forwardRef<HTMLLIElement, FileUploadItemProps>(
           <Progress value={resolvedProgress} className="h-1" />
         )}
         {isError && resolvedError && (
-          <p role="alert" className="text-xs text-destructive">
+          // #124: this is running text (the rejection reason), so it takes the
+          // >=4.5:1 ink rung `text-destructive-text` — not the 3:1 mark rung the
+          // `statusIcon.error` glyph above correctly keeps.
+          <p role="alert" className="text-xs text-destructive-text">
             {resolvedError}
           </p>
         )}

package/src/components/form/form.tsx

@@ -80,7 +80,8 @@ export const FormLabel = forwardRef<
       htmlFor={formItemId}
       className={cn(
         "transition-colors duration-fast ease-standard",
-        error && "text-destructive",
+        // #124: the label's own error-state text, not a mark — ink rung.
+        error && "text-destructive-text",
         className,
       )}
       {...props}
@@ -129,7 +130,9 @@ export const FormMessage = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLP
         ref={ref}
         id={formMessageId}
         className={cn(
-          "text-sm font-medium text-destructive animate-in fade-in slide-in-from-top-1 ease-entrance",
+          // #124: the error message body is running text — ink rung, not the
+          // 3:1 mark rung `text-destructive` guarantees.
+          "text-sm font-medium text-destructive-text animate-in fade-in slide-in-from-top-1 ease-entrance",
           className,
         )}
         {...props}

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

@@ -59,7 +59,7 @@ describe("IconButton", () => {
     );
     const wrapper = document.querySelector('[data-slot="icon-button"]')!;
     expect(wrapper).toHaveAttribute("tabindex", "0");
-    expect(wrapper.className).toContain("focus-visible:ring-ring");
+    expect(wrapper.className).toContain("focus-ring");
     await userEvent.tab();
     expect(wrapper).toHaveFocus();
   });

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

@@ -101,8 +101,8 @@ export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(functio
               // 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",
+              // a hardcoded browser blue identical in every theme.
+              "focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
               disabled && "cursor-not-allowed",
             )}
           >

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

@@ -1,10 +1,19 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
 import { Input } from "./input";
 
 const meta = {
   title: "Core/Input",
   component: Input,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The plain text field. A search box with a leading icon and a clear button is `Data/SearchInput`, which is built on this one; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).",
+      },
+    },
+  },
   args: { placeholder: "you@example.com" },
   argTypes: {
     type: {
@@ -42,3 +51,115 @@ 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" } };
+
+/**
+ * The element whose `data-theme` actually GOVERNS `el` — the nearest ancestor
+ * carrying the attribute, falling back to the document element.
+ *
+ * The earlier version of this helper guessed between `document.body` and
+ * `document.documentElement`. When the decorator wrote `data-theme` onto a
+ * wrapper closer to the story than either of those, flipping the far ancestor
+ * was a silent no-op: the nearer attribute still won the cascade, so BOTH
+ * branches of the loop below asserted in whatever theme the run had already
+ * chosen, and the docblock's "checked in both themes" claim was false. That
+ * stayed invisible until the suite was run under `STORYBOOK_THEME=dark`, where
+ * the same two branches both asserted in dark and the guard fired. Resolving
+ * the governing element from the input itself cannot drift that way.
+ */
+function themeHost(el: Element): HTMLElement {
+  return (el.closest("[data-theme]") as HTMLElement | null) ?? document.documentElement;
+}
+
+/**
+ * Regression lock for #49: `Input` must set its OWN text colour rather than
+ * inherit whatever ambient ink its container declares. Nested inside a
+ * `text-sidebar-foreground` wrapper (the `sidebar-04` mail search field's real
+ * shape), the input's resolved `color` must still match an un-nested `Input`'s
+ * — not the wrapper's near-invisible-on-`--background` sidebar ink. Runs in
+ * the Storybook browser project so `getComputedStyle` reflects the real
+ * Tailwind/token cascade (a jsdom unit test has none — `css: false` in
+ * `vitest.config.ts` — so it can only assert the class list, which would stay
+ * green even if a later change kept the class string but lost the cascade).
+ * Checked in BOTH themes via an in-place `data-theme` flip (no remount), so
+ * the fix is verified theme-safe rather than merely assumed to be from the
+ * class being additive.
+ */
+export const InAmbientTextContainer: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Input aria-label="reference input" placeholder="reference (no ambient wrapper)" />
+      <div className="text-sidebar-foreground">
+        <Input aria-label="nested input" placeholder="nested under text-sidebar-foreground" />
+      </div>
+      <div className="text-muted-foreground">
+        <Input aria-label="muted input" placeholder="nested under text-muted-foreground" />
+      </div>
+    </div>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const reference = canvas.getByLabelText<HTMLInputElement>("reference input");
+    const nested = canvas.getByLabelText<HTMLInputElement>("nested input");
+    const muted = canvas.getByLabelText<HTMLInputElement>("muted input");
+    await userEvent.type(nested, "search query");
+
+    const assertMatchesReference = async () => {
+      await waitFor(() => {
+        expect(getComputedStyle(nested).color).toBe(getComputedStyle(reference).color);
+        expect(getComputedStyle(muted).color).toBe(getComputedStyle(reference).color);
+      });
+      /*
+       * Guard against a vacuous pass: an ambient wrapper's ink must actually
+       * differ from the input's own, or this lock could never fail.
+       *
+       * The guard rides on the `text-muted-foreground` wrapper, NOT the
+       * sidebar one. `--sidebar-foreground` and `--foreground` are separate
+       * roles that happen to carry the same literal in the dark reference
+       * theme (both `oklch(0.95 0.004 257)`) — a legitimate coincidence, not
+       * an undeclared alias: light's sidebar ink is near-white because that
+       * theme's sidebar ground is DARK, and dark's is near-white because
+       * everything is. So in dark the sidebar wrapper cannot express a
+       * difference, and asserting one there is unsatisfiable.
+       * `--muted-foreground` differs from `--foreground` in both reference
+       * themes (light 0.5 vs 0.3, dark 0.72 vs 0.95), so it can carry the
+       * guard in either. The sidebar wrapper stays because it is the real
+       * shape this locks (the `sidebar-04` mail search field).
+       */
+      await expect(getComputedStyle(muted).color).not.toBe(
+        getComputedStyle(muted.parentElement!).color,
+      );
+    };
+
+    const host = themeHost(nested);
+    const original = host.getAttribute("data-theme");
+    /*
+     * Prove the flip actually took, rather than assuming it. A flip that lands
+     * on an element the cascade ignores turns the whole cross-theme claim into
+     * a no-op, which is precisely how this story passed for two themes while
+     * only ever measuring one.
+     */
+    const assertThemeApplied = async (expected: string) => {
+      await waitFor(() => {
+        expect(getComputedStyle(host).getPropertyValue("--foreground").trim()).not.toBe("");
+      });
+      expect(host.getAttribute("data-theme")).toBe(expected);
+      expect(nested.closest("[data-theme]")).toBe(host);
+    };
+
+    try {
+      host.setAttribute("data-theme", "light");
+      await assertThemeApplied("light");
+      const lightInk = getComputedStyle(nested).color;
+      await assertMatchesReference();
+
+      host.setAttribute("data-theme", "dark");
+      await assertThemeApplied("dark");
+      await assertMatchesReference();
+      // The two themes must actually resolve to different ink, or "checked in
+      // both themes" is a claim about an attribute nobody read.
+      expect(getComputedStyle(nested).color).not.toBe(lightInk);
+    } finally {
+      if (original === null) host.removeAttribute("data-theme");
+      else host.setAttribute("data-theme", original);
+    }
+  },
+};

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

@@ -16,4 +16,17 @@ describe("Input", () => {
     const el = screen.getByLabelText<HTMLInputElement>("email");
     expect(el).toBeDisabled();
   });
+
+  it("applies text-foreground class to ensure text color is not inherited from parent", () => {
+    // Render Input inside a container with a different text color (simulating sidebar)
+    render(
+      <div className="text-sidebar-foreground">
+        <Input aria-label="search" />
+      </div>,
+    );
+    const el = screen.getByLabelText<HTMLInputElement>("search");
+    // Verify that the Input element has the text-foreground class
+    // This ensures its text color is explicitly set and not inherited
+    expect(el.className).toContain("text-foreground");
+  });
 });

package/src/components/input/input.tsx

@@ -12,9 +12,9 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function 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",
+        "flex h-9 w-full rounded-md border border-input bg-background text-foreground 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",
+        "focus-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",

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

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
 import { Search } from "lucide-react";
 import {
   InputGroup,
@@ -85,3 +86,76 @@ export const Card: Story = {
     </div>
   ),
 };
+
+/**
+ * Regression lock for #67 (fix round 2) — the compound focus indicator must be
+ * ONE mark on ONE element.
+ *
+ * `InputGroup` delegates its indicator to the wrapper, because the control is
+ * borderless and full-bleed and a ring around IT would be drawn inside the
+ * well. Before this lock the delegation was only half done and the indicator
+ * split across two elements: the wrapper painted the brand ring and no contour
+ * (its own base `outline-none` set `--tw-outline-style: none`, and a following
+ * `outline-1` re-declared `outline-style` from that variable), while the inner
+ * control painted the contour and no ring, ~10px inside, at a different radius.
+ * On light that read as a stray dark rectangle across the composer, and the
+ * well kept the 1.23:1 un-contoured lime ring #67 exists to remove.
+ *
+ * THE ASSERTION IS ON COMPUTED STYLE, NOT ON THE CLASS STRING. The class string
+ * was already "correct" while the bug shipped — `has-[…]:focus-ring-static` was
+ * present and cancelled by a sibling utility — so a class-name assertion (or a
+ * jsdom unit test, which has no CSS at all: `css: false` in `vitest.config.ts`)
+ * stays green through the exact regression this locks. It therefore lives in
+ * the Storybook browser project, where `getComputedStyle` reflects the real
+ * Tailwind cascade.
+ */
+export const CompoundFocusIndicator: Story = {
+  tags: ["!autodocs"],
+  render: () => (
+    <InputGroup className="max-w-sm">
+      <InputGroupAddon>
+        <Search />
+      </InputGroupAddon>
+      <InputGroupInput aria-label="locked control" placeholder="Search…" />
+    </InputGroup>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const control = canvas.getByLabelText<HTMLInputElement>("locked control");
+    const wrapper = control.closest<HTMLElement>("[data-slot=input-group]")!;
+    await userEvent.tab();
+    await expect(control).toHaveFocus();
+
+    /*
+     * Settle past `transition-colors`: reading immediately after focus catches
+     * `outline-color` mid-transition and reports the element's own ink instead
+     * of the contour token. That artefact is why the utility now declares
+     * `outline-color` at rest (themes.css); the wait keeps this lock honest
+     * about which property it is measuring.
+     */
+    await waitFor(() => {
+      const w = getComputedStyle(wrapper);
+      // The wrapper owns BOTH layers.
+      expect(w.outlineStyle).not.toBe("none");
+      expect(w.outlineWidth).toBe("1px");
+      expect(ringSpread(w)).toBeGreaterThan(0);
+      // …and they are flush: the contour sits exactly on the ring's outer edge.
+      expect(parseFloat(w.outlineOffset)).toBe(ringSpread(w));
+    });
+
+    // The control paints NEITHER layer — no second mark inside the well.
+    const c = getComputedStyle(control);
+    await expect(c.outlineStyle).toBe("none");
+    await expect(ringSpread(c)).toBe(0);
+  },
+};
+
+/**
+ * `--tw-ring-shadow` is a `0 0 0 calc(<offset> + <width>) <colour>` string; the
+ * painted reach is that `calc`. Reading it (rather than `boxShadow`) keeps the
+ * measurement independent of whatever elevation rung the element also carries.
+ */
+function ringSpread(style: CSSStyleDeclaration): number {
+  const shadow = style.getPropertyValue("--tw-ring-shadow");
+  const match = /calc\(\s*([\d.]+)px\s*\+\s*([\d.]+)px\s*\)/.exec(shadow);
+  return match ? parseFloat(match[1]) + parseFloat(match[2]) : 0;
+}

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

@@ -7,12 +7,21 @@ import { Textarea } from "../textarea";
 
 export const inputGroupVariants = cva(
   cn(
-    "group/input-group relative flex w-full flex-wrap items-center rounded-md outline-none transition-[color,box-shadow] duration-fast ease-standard",
+    "group/input-group relative flex w-full flex-wrap items-center rounded-md transition-[color,box-shadow] duration-fast ease-standard",
     // Grow to fit a textarea even when it's nested (e.g. wrapped in a
     // `display:contents` body like PromptInputBody). `:has(>textarea)`
     // misses through that wrapper, so match any descendant textarea.
     "h-9 has-[textarea]:h-auto",
-    "has-[[data-slot=input-group-control]:focus-visible]:ring-2 has-[[data-slot=input-group-control]:focus-visible]:ring-ring has-[[data-slot=input-group-control]:focus-visible]:ring-offset-1 has-[[data-slot=input-group-control]:focus-visible]:ring-offset-background",
+    // The compound indicator is the wrapper's, not the control's — the control
+    // is borderless and full-bleed, so a ring around IT would draw inside the
+    // well. `focus-ring-static` paints BOTH layers; the only geometry knob is
+    // `ring-offset-1`, which `outline-offset: calc(--tw-ring-offset-width + 2px)`
+    // tracks so ring and contour stay flush at the same radius. Do NOT add an
+    // `outline-*` utility here: `outline-1` re-declares
+    // `outline-style: var(--tw-outline-style)`, which `outline-none` on this
+    // same element used to pin to `none` — that pairing shipped, and it cancelled
+    // the contour on every composer, NumberInput and TagInput (#67 fix round 2).
+    "has-[[data-slot=input-group-control]:focus-visible]:focus-ring-static has-[[data-slot=input-group-control]:focus-visible]:ring-offset-1 has-[[data-slot=input-group-control]:focus-visible]:ring-offset-background",
     "has-[[data-slot=input-group-control][aria-invalid=true]]:ring-2 has-[[data-slot=input-group-control][aria-invalid=true]]:ring-destructive",
   ),
   {
@@ -144,7 +153,7 @@ export const InputGroupInput = forwardRef<HTMLInputElement, ComponentProps<typeo
         ref={ref}
         data-slot="input-group-control"
         className={cn(
-          "flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:ring-0 focus-visible:ring-offset-0",
+          "flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0",
           className,
         )}
         {...props}
@@ -160,7 +169,7 @@ export const InputGroupTextarea = forwardRef<HTMLTextAreaElement, ComponentProps
         ref={ref}
         data-slot="input-group-control"
         className={cn(
-          "flex-1 resize-none rounded-none border-0 bg-transparent py-2.5 shadow-none focus-visible:ring-0 focus-visible:ring-offset-0",
+          "flex-1 resize-none rounded-none border-0 bg-transparent py-2.5 shadow-none focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0",
           className,
         )}
         {...props}

package/src/components/input-otp/input-otp.tsx

@@ -42,7 +42,11 @@ export const InputOTPSlot = forwardRef<
       ref={ref}
       className={cn(
         "relative flex size-9 items-center justify-center border-y border-e border-input text-sm shadow-sm transition-[color,border-color,box-shadow] duration-fast ease-standard first:rounded-s-md first:border-s last:rounded-e-md",
-        isActive && "z-10 ring-2 ring-ring",
+        // The OTP slot IS the field's focus indicator: the real focused element is
+        // InputOTP's visually-hidden <input>, and `isActive` is the caret's slot. It
+        // therefore carries the compound indicator (#67) — the state is JS-driven, so
+        // it is the `-static` flavour rather than a `:focus-visible` one.
+        isActive && "z-10 focus-ring-static",
         className,
       )}
       {...props}

package/src/components/keyboard-shortcuts/index.ts

@@ -0,0 +1,6 @@
+export {
+  KeyboardShortcuts,
+  type KeyboardShortcutsProps,
+  type Shortcut,
+  type ShortcutGroup,
+} from "./keyboard-shortcuts";