@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/attribution-panel/attributions.generated.ts

@@ -1,8 +1,8 @@
 // GENERATED by scripts/gen-attributions.mjs — DO NOT EDIT BY HAND.
-// Run `pnpm gen:attributions` after changing a dependency, a vendored font, or
-// scripts/attributions.sources.json. `pnpm attributions:check` fails on a stale copy.
+// Run `pnpm gen` after changing a dependency, a vendored font, or
+// scripts/attributions.sources.json. `pnpm gen:check` fails on a stale copy.
 //
-// 116 entries (data: 2, source: 16, font: 2, dependency: 96).
+// 116 entries (data: 2, source: 18, font: 2, dependency: 94).
 
 import type { Attribution } from "./attribution-types";
 
@@ -93,14 +93,14 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
   },
   {
     version: null,
-    note: "The sidebar-02 / sidebar-04 / sidebar-05 copy-owned blocks, re-tokenized with Tabler icons mapped to Lucide.",
-    id: "blocks-so",
+    note: "Agent-session UI logic re-expressed on our tokens: the line-level diff model and its screen-reader polarity prefixes, the scoped N-option permission anatomy, the slash-palette prefix-filter/clamp behaviour, the turn-status elapsed formatter, the hook/lifecycle event line, and the grouped keyboard-shortcuts sheet. No upstream code, styling or terminal palette is shipped.",
+    id: "brainless",
     category: "source",
-    name: "blocks.so",
+    name: "brainless",
     license: "MIT",
-    copyright: "Copyright (c) 2025 Ephraim Duncan",
-    url: "https://github.com/ephraimduncan/blocks",
-    usedBy: ["@elabs-ai/components-ui"],
+    copyright: "Copyright (c) 2026 Ben Swerdlow",
+    url: "https://github.com/theswerd/brainless",
+    usedBy: ["@elabs-ai/components-ai", "@elabs-ai/components-ui", "@elabs-ai/components-terminal"],
     required: false,
   },
   {
@@ -115,6 +115,18 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     usedBy: ["@elabs-ai/components-viewer"],
     required: false,
   },
+  {
+    version: null,
+    note: "The editorial chart gallery behind the 2026-09-04 charts gap analysis: 71 files across the charts and tokens packages cite it as the source of a value, a mark shape or a composition (unit decomposition, hairline furniture, the sequential/diverging ramps, the reveal timing), and three copy-own registry blocks (chart-editorial-hourglass, -patchwork, -almanac) reproduce three of its gallery cards' DATA-SHAPE DESCRIPTIONS from that same analysis' one-line prose. No code was copied verbatim — each was re-expressed onto this repo's tokens and primitives. Its LICENSE is PolyForm Noncommercial 1.0.0, read verbatim from the upstream file; GitHub's own detection reports NOASSERTION, which is why nothing flagged it earlier. The licence's Required Notice slot is left at the template's example value, so upstream states no copyright holder and none is claimed here. Noncommercial-only is unresolved for a repo headed for public release — a licensing decision for the maintainer, not something attribution settles.",
+    id: "lieflat-charts",
+    category: "source",
+    name: "lieflat-charts",
+    license: "PolyForm-Noncommercial-1.0.0",
+    copyright: null,
+    url: "https://github.com/larashero3-dotcom/lieflat-charts",
+    usedBy: ["@elabs-ai/components-charts", "@elabs-ai/components-tokens"],
+    required: false,
+  },
   {
     version: null,
     note: "The live-axis tick-interval picker behind live-y-axis.tsx. Upstream now names that function niceTimeInterval.",
@@ -151,6 +163,18 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     usedBy: ["@elabs-ai/components-editor"],
     required: false,
   },
+  {
+    version: null,
+    note: "Algorithm shape for the framework-free process-mining core: which aggregates a directly-follows graph carries (discoverGraph) and how traces are grouped into variants (extractVariants), with durationStats as their shared summary. Re-typed in TypeScript from the published algorithms, not copied.",
+    id: "pm4js",
+    category: "source",
+    name: "pm4js",
+    license: "BSD-3-Clause",
+    copyright: "Copyright 2021 Alessandro Berti",
+    url: "https://github.com/pm4js/pm4js-core",
+    usedBy: ["@elabs-ai/components-process"],
+    required: false,
+  },
   {
     version: null,
     note: "Beyond the npm dependency below, the shipped dist of react-scroll-area and react-select is modified in patches/ — disclosed here so the change is not invisible.",
@@ -261,14 +285,38 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     note: null,
   },
   {
-    id: "@hookform/resolvers",
+    id: "@dnd-kit/core",
     category: "dependency",
-    name: "@hookform/resolvers",
-    version: "3.10.0",
+    name: "@dnd-kit/core",
+    version: "6.3.1",
     license: "MIT",
-    copyright: "bluebill1049",
-    url: "https://www.npmjs.com/package/@hookform/resolvers",
-    usedBy: ["@elabs-ai/components-ui"],
+    copyright: "Claudéric Demers",
+    url: "https://www.npmjs.com/package/@dnd-kit/core",
+    usedBy: ["@elabs-ai/components-data"],
+    required: false,
+    note: null,
+  },
+  {
+    id: "@dnd-kit/sortable",
+    category: "dependency",
+    name: "@dnd-kit/sortable",
+    version: "10.0.0",
+    license: "MIT",
+    copyright: "Claudéric Demers",
+    url: "https://www.npmjs.com/package/@dnd-kit/sortable",
+    usedBy: ["@elabs-ai/components-data"],
+    required: false,
+    note: null,
+  },
+  {
+    id: "@dnd-kit/utilities",
+    category: "dependency",
+    name: "@dnd-kit/utilities",
+    version: "3.2.2",
+    license: "MIT",
+    copyright: "Claudéric Demers",
+    url: "https://www.npmjs.com/package/@dnd-kit/utilities",
+    usedBy: ["@elabs-ai/components-data"],
     required: false,
     note: null,
   },
@@ -656,18 +704,6 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     required: false,
     note: null,
   },
-  {
-    id: "@rive-app/react-webgl2",
-    category: "dependency",
-    name: "@rive-app/react-webgl2",
-    version: "4.28.6",
-    license: "MIT",
-    copyright: null,
-    url: "https://www.npmjs.com/package/@rive-app/react-webgl2",
-    usedBy: ["@elabs-ai/components-ai"],
-    required: false,
-    note: null,
-  },
   {
     id: "@streamdown/cjk",
     category: "dependency",
@@ -901,30 +937,6 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     required: false,
     note: null,
   },
-  {
-    id: "@xterm/addon-fit",
-    category: "dependency",
-    name: "@xterm/addon-fit",
-    version: "0.11.0",
-    license: "MIT",
-    copyright: "The xterm.js authors",
-    url: "https://www.npmjs.com/package/@xterm/addon-fit",
-    usedBy: ["@elabs-ai/components-ai"],
-    required: false,
-    note: null,
-  },
-  {
-    id: "@xterm/xterm",
-    category: "dependency",
-    name: "@xterm/xterm",
-    version: "6.0.0",
-    license: "MIT",
-    copyright: null,
-    url: "https://www.npmjs.com/package/@xterm/xterm",
-    usedBy: ["@elabs-ai/components-ai"],
-    required: false,
-    note: null,
-  },
   {
     id: "ansi-to-react",
     category: "dependency",
@@ -933,7 +945,7 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     license: "BSD-3-Clause",
     copyright: "Kyle Kelley",
     url: "https://www.npmjs.com/package/ansi-to-react",
-    usedBy: ["@elabs-ai/components-ai"],
+    usedBy: ["@elabs-ai/components-terminal"],
     required: false,
     note: null,
   },
@@ -949,6 +961,8 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
       "@elabs-ai/components-ai",
       "@elabs-ai/components-charts",
       "@elabs-ai/components-editor",
+      "@elabs-ai/components-process",
+      "@elabs-ai/components-terminal",
       "@elabs-ai/components-ui",
     ],
     required: false,
@@ -998,7 +1012,7 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     license: "ISC",
     copyright: "Mike Bostock",
     url: "https://www.npmjs.com/package/d3-force",
-    usedBy: ["@elabs-ai/components-flow"],
+    usedBy: ["@elabs-ai/components-charts", "@elabs-ai/components-flow"],
     required: false,
     note: null,
   },
@@ -1014,6 +1028,18 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     required: false,
     note: null,
   },
+  {
+    id: "d3-hierarchy",
+    category: "dependency",
+    name: "d3-hierarchy",
+    version: "3.1.2",
+    license: "ISC",
+    copyright: "Mike Bostock",
+    url: "https://www.npmjs.com/package/d3-hierarchy",
+    usedBy: ["@elabs-ai/components-charts"],
+    required: false,
+    note: null,
+  },
   {
     id: "d3-sankey",
     category: "dependency",
@@ -1113,24 +1139,14 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
       "@elabs-ai/components-editor",
       "@elabs-ai/components-flow",
       "@elabs-ai/components-maps",
+      "@elabs-ai/components-process",
+      "@elabs-ai/components-terminal",
       "@elabs-ai/components-ui",
       "@elabs-ai/components-viewer",
     ],
     required: false,
     note: null,
   },
-  {
-    id: "media-chrome",
-    category: "dependency",
-    name: "media-chrome",
-    version: "4.19.1",
-    license: "MIT",
-    copyright: "@muxinc",
-    url: "https://www.npmjs.com/package/media-chrome",
-    usedBy: ["@elabs-ai/components-ai"],
-    required: false,
-    note: null,
-  },
   {
     id: "mermaid",
     category: "dependency",
@@ -1139,7 +1155,7 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     license: "MIT",
     copyright: "Knut Sveidqvist",
     url: "https://www.npmjs.com/package/mermaid",
-    usedBy: ["@elabs-ai/components-ai", "@elabs-ai/components-editor"],
+    usedBy: ["@elabs-ai/components-editor"],
     required: false,
     note: null,
   },
@@ -1179,18 +1195,6 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     required: false,
     note: null,
   },
-  {
-    id: "react-hook-form",
-    category: "dependency",
-    name: "react-hook-form",
-    version: "7.77.0",
-    license: "MIT",
-    copyright: "Beier(Bill) Luo",
-    url: "https://www.npmjs.com/package/react-hook-form",
-    usedBy: ["@elabs-ai/components-ui"],
-    required: false,
-    note: null,
-  },
   {
     id: "react-jsx-parser",
     category: "dependency",
@@ -1415,7 +1419,7 @@ export const ATTRIBUTIONS: readonly Attribution[] = [
     license: "MIT",
     copyright: "Colin McDonnell",
     url: "https://www.npmjs.com/package/zod",
-    usedBy: ["@elabs-ai/components-ai", "@elabs-ai/components-ui"],
+    usedBy: ["@elabs-ai/components-ai"],
     required: false,
     note: null,
   },

package/src/components/avatar/avatar.tsx

@@ -9,6 +9,7 @@ export const Avatar = forwardRef<
   return (
     <AvatarPrimitive.Root
       ref={ref}
+      data-slot="avatar"
       className={cn("relative flex size-9 shrink-0 overflow-hidden rounded-full", className)}
       {...props}
     />
@@ -21,6 +22,7 @@ export const AvatarImage = forwardRef<
   return (
     <AvatarPrimitive.Image
       ref={ref}
+      data-slot="avatar-image"
       className={cn(
         "aspect-square size-full animate-in fade-in duration-base ease-entrance",
         className,
@@ -36,8 +38,9 @@ export const AvatarFallback = forwardRef<
   return (
     <AvatarPrimitive.Fallback
       ref={ref}
+      data-slot="avatar-fallback"
       className={cn(
-        "flex size-full items-center justify-center rounded-full bg-muted text-sm font-medium text-muted-foreground",
+        "flex size-full items-center justify-center rounded-full bg-muted text-meta font-medium text-muted-foreground",
         className,
       )}
       {...props}

package/src/components/badge/badge.stories.tsx

@@ -5,6 +5,14 @@ const meta = {
   title: "Core/Badge",
   component: Badge,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A neutral label or count. The closed seven-state execution-status vocabulary — each state carrying its own glyph, so it survives greyscale — is `Core/StatusBadge`; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). Reach for `Badge` when the text IS the meaning and the tone is decoration.",
+      },
+    },
+  },
   args: { children: "Badge" },
   argTypes: {
     variant: {

package/src/components/badge/badge.test.tsx

@@ -1,3 +1,4 @@
+import { createRef } from "react";
 import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { Badge } from "./badge";
@@ -7,4 +8,11 @@ describe("Badge", () => {
     render(<Badge>New</Badge>);
     expect(screen.getByText("New")).toBeInTheDocument();
   });
+
+  it("forwards its ref to the rendered <span>", () => {
+    const ref = createRef<HTMLSpanElement>();
+    render(<Badge ref={ref}>New</Badge>);
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement);
+    expect(ref.current).toBe(screen.getByText("New"));
+  });
 });

package/src/components/badge/badge.tsx

@@ -1,9 +1,9 @@
-import { type HTMLAttributes } from "react";
+import { forwardRef, type HTMLAttributes } from "react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
 
 export const badgeVariants = cva(
-  "inline-flex items-center gap-1 rounded-full border px-2.5 py-0.5 text-meta font-medium transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+  "inline-flex items-center gap-1 rounded-full border px-2.5 py-0.5 text-meta font-medium transition-colors focus-ring focus-visible:ring-offset-2",
   {
     variants: {
       variant: {
@@ -23,6 +23,16 @@ export const badgeVariants = cva(
 export interface BadgeProps
   extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {}
 
-export function Badge({ className, variant, ...props }: BadgeProps) {
-  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
-}
+export const Badge = forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
+  { className, variant, ...props },
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      data-slot="badge"
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    />
+  );
+});

package/src/components/bento-grid/bento-grid.test.tsx

@@ -1,5 +1,5 @@
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
 
 import { BentoGrid, BentoGridItem } from "./bento-grid";
 
@@ -104,7 +104,7 @@ describe("BentoGridItem", () => {
     // The tile stays a div; the inner anchor is the focusable element.
     const item = screen.getByTestId("item");
     expect(item.tagName).toBe("DIV");
-    expect(item.className).toMatch(/focus-within:ring/);
+    expect(item.className).toMatch(/focus-ring-within/);
     expect(screen.getByRole("link", { name: "go" })).toBeInTheDocument();
   });
 
@@ -116,4 +116,25 @@ describe("BentoGridItem", () => {
     );
     expect(screen.getByTestId("item").className).toMatch(/from-primary/);
   });
+
+  it("cancels a pending spotlight rAF on unmount", () => {
+    const rafSpy = vi.spyOn(window, "requestAnimationFrame").mockReturnValue(7);
+    const cafSpy = vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => {});
+    const { unmount } = render(
+      <BentoGridItem spotlight data-testid="item">
+        content
+      </BentoGridItem>,
+    );
+    const item = screen.getByTestId("item");
+    fireEvent.mouseMove(item, { clientX: 10, clientY: 10 });
+    expect(rafSpy).toHaveBeenCalled();
+
+    unmount();
+    // A mouse move right before the tile unmounts (removed from the grid
+    // while hovered) must not leave a scheduled frame pending after teardown.
+    expect(cafSpy).toHaveBeenCalledWith(7);
+
+    rafSpy.mockRestore();
+    cafSpy.mockRestore();
+  });
 });

package/src/components/bento-grid/bento-grid.tsx

@@ -34,6 +34,7 @@ import {
   createContext,
   forwardRef,
   use,
+  useEffect,
   useRef,
   useCallback,
   type CSSProperties,
@@ -178,7 +179,7 @@ export const bentoGridItemVariants = cva(
        * (elevation + edge) is on the base — every tile lifts, clickable or not.
        */
       interactive: {
-        true: "cursor-pointer focus-within:outline-none focus-within:ring-2 focus-within:ring-ring",
+        true: "cursor-pointer focus-ring-within",
         false: "",
       },
     },
@@ -244,6 +245,15 @@ export const BentoGridItem = forwardRef<HTMLDivElement, BentoGridItemProps>(func
   // rAF ref so we only schedule one frame at a time.
   const rafRef = useRef<number>(0);
 
+  // Cancel a pending frame on unmount — otherwise a mouse move right before
+  // the tile unmounts (removed from the grid while hovered) still fires the
+  // scheduled callback after teardown.
+  useEffect(() => {
+    return () => {
+      if (rafRef.current) cancelAnimationFrame(rafRef.current);
+    };
+  }, []);
+
   const handleMouseMove = useCallback(
     (e: React.MouseEvent<HTMLDivElement>) => {
       if (!spotlightOn || !tileRef.current || !overlayRef.current) return;

package/src/components/bounded-number/bounded-number.test.tsx

@@ -18,7 +18,7 @@ describe("BoundedNumber", () => {
   it("hides the empty label once a value is set", () => {
     render(<BoundedNumber aria-label="Limit" defaultValue={250} />);
     expect(screen.queryByText("No limit")).not.toBeInTheDocument();
-    expect(screen.getByRole("spinbutton", { name: "Limit" })).toHaveValue(250);
+    expect(screen.getByRole("spinbutton", { name: "Limit" })).toHaveValue("250");
   });
 
   it("hides the empty label while focused so the field reads as truly empty", async () => {

package/src/components/bounded-number/bounded-number.tsx

@@ -28,83 +28,86 @@ export interface BoundedNumberProps extends NumberInputProps {
  * `null` AND the field is not focused, so the underlying input stays fully
  * clickable/typable and still round-trips to `null` on an empty blur.
  */
-export const BoundedNumber = forwardRef<HTMLDivElement, BoundedNumberProps>(function BoundedNumber(
-  {
-    value: valueProp,
-    defaultValue,
-    onValueChange,
-    emptyLabel,
-    onFocus,
-    onBlur,
-    className,
-    ...props
-  },
-  ref,
-) {
-  const { t } = useLocale();
-  const resolvedEmptyLabel = emptyLabel ?? t("ui.boundedNumber.emptyLabel");
-  const isControlled = valueProp !== undefined;
-  const [internalValue, setInternalValue] = useState<number | null>(
-    defaultValue !== undefined ? defaultValue : null,
-  );
-  const [focused, setFocused] = useState(false);
-  const currentValue = isControlled ? valueProp : internalValue;
-
-  const handleValueChange = useCallback(
-    (next: number | null) => {
-      if (!isControlled) setInternalValue(next);
-      onValueChange?.(next);
+export const BoundedNumber = forwardRef<HTMLInputElement, BoundedNumberProps>(
+  function BoundedNumber(
+    {
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      emptyLabel,
+      onFocus,
+      onBlur,
+      className,
+      ...props
     },
-    [isControlled, onValueChange],
-  );
+    ref,
+  ) {
+    const { t } = useLocale();
+    const resolvedEmptyLabel = emptyLabel ?? t("ui.boundedNumber.emptyLabel");
+    const isControlled = valueProp !== undefined;
+    const [internalValue, setInternalValue] = useState<number | null>(
+      defaultValue !== undefined ? defaultValue : null,
+    );
+    const [focused, setFocused] = useState(false);
+    const currentValue = isControlled ? valueProp : internalValue;
 
-  const handleFocus = useCallback(
-    (event: FocusEvent<HTMLDivElement>) => {
-      setFocused(true);
-      onFocus?.(event);
-    },
-    [onFocus],
-  );
+    const handleValueChange = useCallback(
+      (next: number | null) => {
+        if (!isControlled) setInternalValue(next);
+        onValueChange?.(next);
+      },
+      [isControlled, onValueChange],
+    );
 
-  const handleBlur = useCallback(
-    (event: FocusEvent<HTMLDivElement>) => {
-      setFocused(false);
-      onBlur?.(event);
-    },
-    [onBlur],
-  );
+    const handleFocus = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(false);
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
 
-  const showEmptyLabel = currentValue == null && !focused;
+    const showEmptyLabel = currentValue == null && !focused;
 
-  return (
-    // `className` lands on the ROOT (the positioning context), not on the
-    // inner `NumberInput`: a width utility on the inner control would resolve
-    // against a shrink-to-fit wrapper and silently do nothing, so
-    // `className="w-full"` could never widen the field. `w-36` here is
-    // `NumberInput`'s own default width, re-declared so `cn()` lets the caller
-    // override it; the input then simply fills the root.
-    <div className={cn("relative inline-block w-36", className)} data-slot="bounded-number">
-      <NumberInput
-        ref={ref}
-        value={currentValue}
-        onValueChange={handleValueChange}
-        onFocus={handleFocus}
-        onBlur={handleBlur}
-        className="w-full"
-        {...props}
-      />
-      {showEmptyLabel && (
-        <span
-          aria-hidden="true"
-          data-slot="bounded-number-empty-label"
-          className={cn(
-            "pointer-events-none absolute inset-0 flex items-center justify-center",
-            "text-body text-muted-foreground",
-          )}
-        >
-          {resolvedEmptyLabel}
-        </span>
-      )}
-    </div>
-  );
-});
+    return (
+      // `className` lands on the ROOT (the positioning context), not on the
+      // inner `NumberInput`: a width utility on the inner control would resolve
+      // against a shrink-to-fit wrapper and silently do nothing, so
+      // `className="w-full"` could never widen the field. `w-36` is this
+      // preset's own default width (`NumberInput` itself is unconstrained and
+      // fills its container) — `cn()` lets the caller override it, and the
+      // inner `NumberInput` simply fills the root via `className="w-full"`.
+      <div className={cn("relative inline-block w-36", className)} data-slot="bounded-number">
+        <NumberInput
+          ref={ref}
+          value={currentValue}
+          onValueChange={handleValueChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          className="w-full"
+          {...props}
+        />
+        {showEmptyLabel && (
+          <span
+            aria-hidden="true"
+            data-slot="bounded-number-empty-label"
+            className={cn(
+              "pointer-events-none absolute inset-0 flex items-center justify-center",
+              "text-body text-muted-foreground",
+            )}
+          >
+            {resolvedEmptyLabel}
+          </span>
+        )}
+      </div>
+    );
+  },
+);

package/src/components/breadcrumb/breadcrumb.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
 import {
   Breadcrumb,
   BreadcrumbItem,
@@ -45,3 +46,40 @@ export const Default: Story = {
     </Breadcrumb>
   ),
 };
+
+/**
+ * #310 — `BreadcrumbLink` had no focus-visible styling of its own, so keyboard
+ * focus fell straight through to the browser's own default ring instead of
+ * the library's token-driven indicator (`focus-ring`, ADR 0027) every other
+ * interactive control carries. A class-string assertion would be worthless
+ * (it wouldn't prove anything actually paints) so this locks the RENDERED
+ * indicator: Tab to the first link and assert a real box-shadow exists,
+ * mirroring `Button`'s `CompoundFocusIndicator` lock.
+ */
+export const FocusIndicator: Story = {
+  name: "Focus indicator (#310)",
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">Home</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>brand-ui</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const link = canvas.getByRole("link", { name: "Home" });
+
+    // Tab rather than .focus(): `:focus-visible` is what `focus-ring` keys
+    // on, and a programmatic focus does not reliably match it.
+    await userEvent.tab();
+    await expect(link).toHaveFocus();
+
+    const focused = getComputedStyle(link);
+    await expect(focused.boxShadow).not.toBe("none");
+  },
+};