@elabs-ai/components-ui 4.2.0 → 5.0.0

package/src/components/nav-user/nav-user.tsx

@@ -1,6 +1,7 @@
 "use client";
 
-import { BadgeCheck, Bell, ChevronsUpDown, CreditCard, LogOut, Sparkles } from "lucide-react";
+import type { ReactNode } from "react";
+import { ChevronsUpDown, LogOut, Settings } from "lucide-react";
 import { Avatar, AvatarFallback, AvatarImage } from "../avatar";
 import {
   DropdownMenu,
@@ -11,6 +12,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "../dropdown-menu";
+import { useLocale } from "../locale-provider";
 import { SidebarMenu, SidebarMenuButton, SidebarMenuItem, useSidebar } from "../sidebar";
 
 export interface NavUserUser {
@@ -22,24 +24,41 @@ export interface NavUserUser {
 
 export interface NavUserProps {
   user: NavUserUser;
+  /** Fires when "Settings" is chosen. Ignored when `settingsHref` is set. */
+  onSettings?: () => void;
+  /** Route of the settings screen — "Settings" renders as a link to it. */
+  settingsHref?: string;
+  /** Fires when "Sign out" is chosen. */
+  onSignOut?: () => void;
+  /**
+   * Extra `DropdownMenuItem`s, placed above "Settings" (e.g. Profile, Billing).
+   * Settings and Sign out are always present — they are the standard pair.
+   */
+  children?: ReactNode;
 }
 
-/**
- * Sidebar account / user menu. Shared primitive from sidebar-04 (issue #99).
- * Renders a trigger showing name + email + avatar; the dropdown exposes
- * account, billing, notifications and log-out actions.
- *
- * Wire your own action handlers by composing custom `DropdownMenuItem` children
- * if you need more than the default actions — or extend via className.
- */
-export function NavUser({ user }: NavUserProps) {
-  const { isMobile } = useSidebar();
-  const initials = user.name
+function initialsOf(name: string): string {
+  return name
     .split(" ")
-    .map((n) => n[0])
+    .map((part) => part[0])
     .join("")
     .slice(0, 2)
     .toUpperCase();
+}
+
+/**
+ * The standard sidebar footer: the signed-in user (avatar, name, email) as one
+ * row that opens the account menu — Settings, then Sign out. EVERY app shell's
+ * nav rail ends with this; settings never sits in the footer as a loose nav
+ * row, and the footer carries no environment/meta line.
+ *
+ * Collapsed to the 48px icon rail the row is the avatar alone, and its
+ * accessible name is written out because the visible label is gone.
+ */
+export function NavUser({ user, onSettings, settingsHref, onSignOut, children }: NavUserProps) {
+  const { isMobile } = useSidebar();
+  const { t } = useLocale();
+  const initials = initialsOf(user.name);
 
   return (
     <SidebarMenu>
@@ -48,63 +67,59 @@ export function NavUser({ user }: NavUserProps) {
           <DropdownMenuTrigger asChild>
             <SidebarMenuButton
               size="lg"
-              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground md:h-8 md:p-0"
+              tooltip={user.name}
+              // Written out: collapsed, the trigger is only an avatar, so its
+              // contents cannot name it. Same string as the visible label, in
+              // reading order (WCAG 2.5.3).
+              aria-label={`${user.name} ${user.email}`}
+              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
             >
-              <Avatar className="h-8 w-8 rounded-lg">
-                {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
+              <Avatar className="size-8 rounded-lg">
+                {user.avatar && <AvatarImage src={user.avatar} alt="" />}
                 <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
               </Avatar>
-              <div className="grid flex-1 text-start text-body leading-tight">
+              <div className="grid flex-1 text-start text-body leading-tight group-data-[collapsible=icon]:hidden">
                 <span className="truncate font-medium">{user.name}</span>
-                <span className="truncate text-meta">{user.email}</span>
+                <span className="truncate text-meta text-sidebar-muted-foreground">
+                  {user.email}
+                </span>
               </div>
-              <ChevronsUpDown className="ms-auto size-4" />
+              <ChevronsUpDown
+                aria-hidden="true"
+                className="ms-auto size-4 group-data-[collapsible=icon]:hidden"
+              />
             </SidebarMenuButton>
           </DropdownMenuTrigger>
           <DropdownMenuContent
+            data-slot="nav-user-menu"
             className="w-(--radix-dropdown-menu-trigger-width) min-w-56 rounded-lg"
             side={isMobile ? "bottom" : "right"}
             align="end"
             sideOffset={4}
           >
-            <DropdownMenuLabel className="p-0 font-normal">
-              <div className="flex items-center gap-2 px-1 py-1.5 text-start text-body">
-                <Avatar className="h-8 w-8 rounded-lg">
-                  {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
-                  <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
-                </Avatar>
-                <div className="grid flex-1 text-start text-body leading-tight">
-                  <span className="truncate font-medium">{user.name}</span>
-                  <span className="truncate text-meta">{user.email}</span>
-                </div>
-              </div>
+            <DropdownMenuLabel className="text-meta text-muted-foreground">
+              {t("ui.navUser.label")}
             </DropdownMenuLabel>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <Sparkles />
-                Upgrade to Pro
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-            <DropdownMenuSeparator />
             <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <BadgeCheck />
-                Account
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <CreditCard />
-                Billing
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <Bell />
-                Notifications
-              </DropdownMenuItem>
+              {children}
+              {settingsHref ? (
+                <DropdownMenuItem asChild>
+                  <a href={settingsHref}>
+                    <Settings aria-hidden="true" />
+                    {t("ui.navUser.settings")}
+                  </a>
+                </DropdownMenuItem>
+              ) : (
+                <DropdownMenuItem onSelect={onSettings}>
+                  <Settings aria-hidden="true" />
+                  {t("ui.navUser.settings")}
+                </DropdownMenuItem>
+              )}
             </DropdownMenuGroup>
             <DropdownMenuSeparator />
-            <DropdownMenuItem>
-              <LogOut />
-              Log out
+            <DropdownMenuItem onSelect={onSignOut}>
+              <LogOut aria-hidden="true" />
+              {t("ui.navUser.signOut")}
             </DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>

package/src/components/navigation-menu/navigation-menu.stories.tsx

@@ -112,3 +112,45 @@ export const Default: Story = {
     await waitFor(() => expect(trigger).toHaveAttribute("aria-expanded", "false"));
   },
 };
+
+/**
+ * Locks WCAG 1.4.11 (#308): `NavigationMenuTrigger` painted `hover:` and
+ * `focus:` identically, with the fill alone (no ring/outline layer) as the
+ * only signal — not a visible indicator. Keyboard (Tab) focus must now paint
+ * a real compound ring (`focus-ring`: a `boxShadow` layer, or a non-zero,
+ * non-`none` `outline`), and the resting trigger must carry neither layer.
+ *
+ * NOTE: this does not additionally assert "a mouse click shows no ring" —
+ * confirmed BOTH before and after this fix (and independent of story order),
+ * a real click on this trigger still lands the browser in `:focus-visible`
+ * in this environment. `NavigationMenuTrigger` sits in Radix's roving-
+ * tabindex collection, which manages its focus imperatively rather than via
+ * the browser's native click-to-focus default action — the same class of
+ * "script-triggered focus" `CompoundFocusIndicator` (`button.stories.tsx`)
+ * already notes as unreliable against `:focus-visible`. Converting `focus:`
+ * to `focus-visible:` is still the correct, spec-aligned fix (mouse-click
+ * suppression is now possible, keyed on the browser's own determination);
+ * whether Radix's roving-focus internals let the browser actually make that
+ * determination for a plain click is a separate, deeper defect — flagged as
+ * a residual follow-up, not fixed here.
+ */
+export const KeyboardFocusIndicator: Story = {
+  name: "Keyboard focus",
+  render: Default.render,
+  play: async ({ canvas, userEvent }) => {
+    const trigger = canvas.getByRole("button", { name: /products/i });
+
+    const resting = getComputedStyle(trigger);
+    await expect(resting.boxShadow).toBe("none");
+    await expect(resting.outlineStyle).toBe("none");
+
+    // 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(trigger).toHaveFocus();
+    const afterTab = getComputedStyle(trigger);
+    const tabHasRing = afterTab.boxShadow !== "none";
+    const tabHasOutline = afterTab.outlineStyle !== "none" && parseFloat(afterTab.outlineWidth) > 0;
+    await expect(tabHasRing || tabHasOutline).toBe(true);
+  },
+};

package/src/components/navigation-menu/navigation-menu.tsx

@@ -198,7 +198,7 @@ export const NavigationMenuItem = forwardRef<
 });
 
 export const navigationMenuTriggerStyle = cva(
-  "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-body font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:outline-none disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-accent",
+  "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-body font-medium outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground focus-ring disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-accent",
 );
 
 export const NavigationMenuTrigger = forwardRef<

package/src/components/page-shell/page-shell.stories.tsx

@@ -26,7 +26,7 @@ export const Default: Story = {
 /**
  * `headerVariant="toolbar"` places a real `<ViewToolbar>` in `PageShell`'s
  * header slot and pins it in POSITION (never a fixed height — see
- * `Docs/View Toolbar Contract` R7) while the body scrolls beneath it. The
+ * `Layout/ViewToolbar → Contract` R7) while the body scrolls beneath it. The
  * outer `h-[420px] overflow-y-auto` div stands in for the `SidebarInset`
  * scroll region `PageShell` is normally embedded in — `PageShell` itself
  * never owns a scroll container (#367).

package/src/components/page-shell/page-shell.tsx

@@ -10,12 +10,12 @@ export interface PageShellProps extends ComponentProps<"div"> {
    * Byte-identical to today.
    *
    * "toolbar" — for a `<ViewToolbar>` header (`@elabs-ai/components-ui`,
-   * `Docs/View Toolbar Contract`): wraps `header` in a `sticky top-0` container
+   * `Layout/ViewToolbar → Contract`): wraps `header` in a `sticky top-0` container
    * with an opaque/blurred fill and a bottom hairline, so it stays pinned while
    * the body scrolls beneath it. PLACES whatever node `header` is — it does not
    * reimplement ViewToolbar's own info/left-cluster/actions grammar, and it does
    * NOT cap the row's height (a `<ViewToolbar>` wraps at narrow widths; see
-   * `Docs/View Toolbar Contract` R7).
+   * `Layout/ViewToolbar → Contract` R7).
    */
   headerVariant?: "default" | "toolbar";
   /** Constrain content width. Defaults to "xl". */
@@ -92,6 +92,7 @@ export const PageShell = forwardRef<HTMLDivElement, PageShellProps>(function Pag
 
   const headerNode = header ? (
     headerVariant === "toolbar" ? (
+      // header-band-exempt: a page-section toolbar under the top bar, not beside it
       <div
         data-slot="page-shell-toolbar-header"
         className="sticky top-0 z-10 border-b border-border bg-background/95 py-3 backdrop-blur"

package/src/components/pagination/pagination.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { forwardRef, type ComponentProps } from "react";
 import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";
 import { cn } from "../../lib/cn";

package/src/components/parallax-plane/index.ts

@@ -0,0 +1,8 @@
+export {
+  ParallaxPlane,
+  PARALLAX_MAX_TRAVEL,
+  PARALLAX_PLANE_RATES,
+  parallaxOffset,
+  type ParallaxPlaneKind,
+  type ParallaxPlaneProps,
+} from "./parallax-plane";

package/src/components/parallax-plane/parallax-plane.css

@@ -0,0 +1,26 @@
+/*
+ * ParallaxPlane — the scroll-driven path (`animation-timeline: scroll(root)`).
+ * The component sets `data-parallax="timeline"` only after hydration, only when the motion gate
+ * is open and the browser supports scroll timelines, and passes the geometry in:
+ *   --parallax-travel  signed end offset (never more than 60px from the content plane)
+ *   --parallax-range   scroll distance over which that offset is reached (travel / |1 − rate|)
+ * Past the range the plane holds its offset (`both` fill), so the total travel stays clamped at
+ * every scroll position. Under reduced motion the attribute is never set: no animation, no
+ * transform. `transform` only — nothing here triggers layout.
+ */
+@layer base {
+  [data-slot="parallax-plane"][data-parallax="timeline"] {
+    animation: brand-ui-parallax-plane linear both;
+    animation-timeline: scroll(root block);
+    animation-range: 0px var(--parallax-range);
+  }
+
+  @keyframes brand-ui-parallax-plane {
+    from {
+      transform: translateY(0);
+    }
+    to {
+      transform: translateY(var(--parallax-travel));
+    }
+  }
+}

package/src/components/parallax-plane/parallax-plane.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+import { Card, CardDescription, CardHeader, CardTitle } from "../card";
+import { ParallaxPlane, type ParallaxPlaneKind } from "./parallax-plane";
+
+const PLANES: { plane: ParallaxPlaneKind; title: string; description: string }[] = [
+  { plane: "ground", title: "Ground plane", description: "Scrolls at 0.15× — it lags behind." },
+  { plane: "content", title: "Content plane", description: "Scrolls with the page at 1×." },
+  { plane: "float", title: "Float plane", description: "Scrolls at 1.2× — it runs ahead." },
+];
+
+function Planes() {
+  return (
+    <div className="min-h-screen p-8">
+      <p className="text-body text-muted-foreground">
+        Scroll the page: each card moves at its plane’s rate, never more than 60px from the content.
+      </p>
+      <div className="mt-40 grid gap-6 sm:grid-cols-3">
+        {PLANES.map(({ plane, title, description }) => (
+          <ParallaxPlane key={plane} plane={plane}>
+            <Card>
+              <CardHeader>
+                <CardTitle>{title}</CardTitle>
+                <CardDescription>{description}</CardDescription>
+              </CardHeader>
+            </Card>
+          </ParallaxPlane>
+        ))}
+      </div>
+      <div className="min-h-screen" />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Display/ParallaxPlane",
+  component: ParallaxPlane,
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+  render: () => <Planes />,
+} satisfies Meta<typeof ParallaxPlane>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Names a running animation so a failing reduced-motion play says what still moves. */
+function describeAnimation(a: Animation) {
+  const effect = a.effect as KeyframeEffect | null;
+  const target = effect?.target as Element | null | undefined;
+  const name = (a as CSSAnimation).animationName ?? (a as CSSTransition).transitionProperty ?? a.id;
+  return `${name} on ${target?.getAttribute("data-slot") ?? target?.tagName ?? "?"}${effect?.pseudoElement ?? ""}`;
+}
+
+export const Default: Story = {};
+
+export const Dark: Story = {
+  parameters: { themes: { themeOverride: "dark" } },
+};
+
+export const Decoration10: Story = {
+  globals: { decoration: "10" },
+};
+
+/** Under reduced motion every plane scrolls at 1×: no animation, no transform. */
+export const ReducedMotion: Story = {
+  // The real gate on :root (Storybook motion toolbar) plus a subtree dial, because the toolbar
+  // writes :root after the story has mounted.
+  globals: { motionPref: "reduced" },
+  render: () => (
+    <div data-motion-pref="reduced">
+      <Planes />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    // Transitions the harness started before the gate applied (theme/decoration swaps between
+    // stories) settle; a primitive that still animates under the gate never would.
+    await waitFor(() =>
+      expect(
+        document
+          .getAnimations()
+          .filter((a) => a.playState === "running")
+          .map(describeAnimation),
+      ).toEqual([]),
+    );
+    for (const plane of canvasElement.querySelectorAll('[data-slot="parallax-plane"]')) {
+      await expect(getComputedStyle(plane).transform).toBe("none");
+    }
+  },
+};

package/src/components/parallax-plane/parallax-plane.test.tsx

@@ -0,0 +1,57 @@
+import type * as React from "react";
+import { render, waitFor } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PARALLAX_MAX_TRAVEL, ParallaxPlane, parallaxOffset } from "./parallax-plane";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("parallaxOffset", () => {
+  it("moves ground behind and float ahead of content, clamped to the max travel", () => {
+    expect(parallaxOffset(40, 0.15, 1)).toBeCloseTo(34);
+    expect(parallaxOffset(400, 0.15, 1)).toBe(PARALLAX_MAX_TRAVEL);
+    expect(parallaxOffset(200, 1.2, 1)).toBeCloseTo(-40);
+    expect(parallaxOffset(400, 1.2, 1)).toBe(-PARALLAX_MAX_TRAVEL);
+    expect(parallaxOffset(400, 1, 1)).toBe(0);
+  });
+
+  it("collapses to no parallax at the motion floor", () => {
+    expect(Math.abs(parallaxOffset(4000, 0.15, 0.0001))).toBeLessThan(0.5);
+  });
+});
+
+describe("ParallaxPlane", () => {
+  it("server-renders with no transform and no motion state", () => {
+    const html = renderToString(<ParallaxPlane plane="ground">x</ParallaxPlane>);
+    expect(html).toContain('data-plane="ground"');
+    expect(html).not.toContain("data-parallax");
+    expect(html).not.toContain("transform");
+  });
+
+  it("uses the scroll timeline when the browser has one", async () => {
+    vi.stubGlobal("CSS", { supports: () => true });
+    const { container } = render(<ParallaxPlane plane="ground" />);
+    const el = container.querySelector<HTMLElement>('[data-slot="parallax-plane"]')!;
+    await waitFor(() => expect(el).toHaveAttribute("data-parallax", "timeline"));
+    expect(el.style.getPropertyValue("--parallax-travel")).toBe("60px");
+    expect(Number.parseFloat(el.style.getPropertyValue("--parallax-range"))).toBeCloseTo(70.59, 1);
+  });
+
+  it("never moves the content plane or any plane under reduced motion", async () => {
+    vi.stubGlobal("CSS", { supports: () => true });
+    const { container } = render(<ParallaxPlane plane="content" />);
+    // jsdom does not inherit custom properties, so the reduce dial sits on the plane itself.
+    const { container: reduced } = render(
+      <ParallaxPlane
+        plane="float"
+        style={{ "--motion-factor": "0.0001" } as React.CSSProperties}
+      />,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(container.firstElementChild).not.toHaveAttribute("data-parallax");
+    expect(reduced.firstElementChild).not.toHaveAttribute("data-parallax");
+    expect((reduced.firstElementChild as HTMLElement).style.transform).toBe("");
+  });
+});

package/src/components/parallax-plane/parallax-plane.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import * as React from "react";
+import { useScrollProgress } from "../../lib/use-scroll-progress";
+import "./parallax-plane.css";
+
+/** The three depth planes of a page: the ground, the content, and floating accents. */
+export type ParallaxPlaneKind = "ground" | "content" | "float";
+
+/** Default scroll rate per plane, relative to the page (content moves with it at 1×). */
+export const PARALLAX_PLANE_RATES: Record<ParallaxPlaneKind, number> = {
+  ground: 0.15,
+  content: 1,
+  float: 1.2,
+};
+
+/** The largest offset, in px, any plane may drift from the content plane. */
+export const PARALLAX_MAX_TRAVEL = 60;
+
+export interface ParallaxPlaneProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Which depth plane this is; sets `data-plane` and the default `rate`. Default `content`. */
+  plane?: ParallaxPlaneKind;
+  /** Scroll rate relative to the page (1 = moves with the content). Defaults per `plane`. */
+  rate?: number;
+}
+
+/**
+ * Offset of a plane from the content plane after `scrollY` px of scroll: `(1 − rate) × factor`
+ * per px, clamped to ±{@link PARALLAX_MAX_TRAVEL}. Reduced motion (factor at the floor) gives an
+ * effective rate of 1 for every plane — no parallax.
+ */
+export function parallaxOffset(scrollY: number, rate: number, factor: number): number {
+  const offset = (1 - rate) * factor * scrollY;
+  return Math.max(-PARALLAX_MAX_TRAVEL, Math.min(PARALLAX_MAX_TRAVEL, offset));
+}
+
+/**
+ * A depth plane that scrolls at its own rate. Uses CSS `animation-timeline: scroll(root)` where
+ * the browser has it, else `motion`'s `scroll()` (lazy optional peer) writing `transform`. The
+ * server HTML has no transform; motion starts after hydration and only when the gate is open.
+ * The plane owns its `transform` — put layout transforms on a child.
+ */
+export const ParallaxPlane = React.forwardRef<HTMLDivElement, ParallaxPlaneProps>(
+  ({ plane = "content", rate, className, style, ...props }, ref) => {
+    const innerRef = React.useRef<HTMLDivElement>(null);
+    React.useImperativeHandle(ref, () => innerRef.current as HTMLDivElement, []);
+
+    const effectiveRate = rate ?? PARALLAX_PLANE_RATES[plane];
+    const { mode, factor } = useScrollProgress(
+      (scrollY) => {
+        const el = innerRef.current;
+        if (el)
+          el.style.transform = `translateY(${parallaxOffset(scrollY, effectiveRate, factor)}px)`;
+      },
+      { enabled: effectiveRate !== 1, target: innerRef },
+    );
+
+    const perPx = (1 - effectiveRate) * factor;
+    const timelineStyle =
+      mode === "timeline" && perPx !== 0
+        ? ({
+            "--parallax-travel": `${Math.sign(perPx) * PARALLAX_MAX_TRAVEL}px`,
+            "--parallax-range": `${PARALLAX_MAX_TRAVEL / Math.abs(perPx)}px`,
+          } as React.CSSProperties)
+        : undefined;
+
+    return (
+      <div
+        ref={innerRef}
+        data-slot="parallax-plane"
+        data-plane={plane}
+        data-parallax={mode === "static" ? undefined : mode}
+        className={className}
+        style={timelineStyle ? { ...style, ...timelineStyle } : style}
+        {...props}
+      />
+    );
+  },
+);
+ParallaxPlane.displayName = "ParallaxPlane";

package/src/components/popover/popover.tsx

@@ -18,7 +18,7 @@ export const PopoverContent = forwardRef<
         align={align}
         sideOffset={sideOffset}
         className={cn(
-          "z-50 w-72 rounded-md bg-popover p-4 text-popover-foreground shadow-ring-md outline-none",
+          "z-50 w-72 rounded-md bg-popover p-4 text-popover-foreground shadow-popover 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 data-[state=closed]:zoom-out-95",
           "data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
           className,

package/src/components/progress/progress.stories.tsx

@@ -28,6 +28,18 @@ const meta = {
       control: "text",
       table: { category: "Appearance" },
     },
+    marker: {
+      description:
+        "Reference point (0–100) rendered as a thin vertical tick — e.g. an “expected by today” pace or a target. Unset renders no tick.",
+      control: { type: "number", min: 0, max: 100 },
+      table: { category: "Reference" },
+    },
+    markerLabel: {
+      description:
+        "What `marker` represents, already localized (e.g. “expected 70% by today”). Appended to the accessible value text unless a caller-supplied `aria-valuetext` is set.",
+      control: "text",
+      table: { category: "Reference" },
+    },
   },
 } satisfies Meta<typeof Progress>;
 export default meta;
@@ -78,3 +90,76 @@ export const Tones: Story = {
     await expect(destructive).toHaveAttribute("aria-valuetext", "Exceeded — 120 of 100");
   },
 };
+
+/**
+ * A KPI running behind its pace marker (62% done, expected 70% by today) —
+ * `markerLabel` composes into `aria-valuetext` alongside the raw value.
+ */
+export const WithMarker: Story = {
+  render: () => (
+    <Progress
+      aria-label="Quarterly goal"
+      className="w-64"
+      marker={70}
+      markerLabel="expected 70% by today"
+      value={62}
+    />
+  ),
+  play: async ({ canvas }) => {
+    const bar = canvas.getByRole("progressbar", { name: "Quarterly goal" });
+    await expect(bar).toHaveAttribute("aria-valuetext", "62%, expected 70% by today");
+  },
+};
+
+/** Ahead of pace — the same reference tick, further behind the filled value. */
+export const WithMarkerAhead: Story = {
+  render: () => (
+    <Progress
+      aria-label="Quarterly goal"
+      className="w-64"
+      marker={50}
+      markerLabel="expected 50% by today"
+      value={78}
+    />
+  ),
+  play: async ({ canvas }) => {
+    const bar = canvas.getByRole("progressbar", { name: "Quarterly goal" });
+    await expect(bar).toHaveAttribute("aria-valuetext", "78%, expected 50% by today");
+  },
+};
+
+/** The pace tick renders on every tone variant, not only `default`. */
+export const MarkerAllVariants: Story = {
+  render: () => (
+    <div className="flex w-64 flex-col gap-3">
+      <Progress
+        aria-label="Default tone with marker"
+        marker={70}
+        markerLabel="expected 70% by today"
+        value={62}
+        variant="default"
+      />
+      <Progress
+        aria-label="Success tone with marker"
+        marker={70}
+        markerLabel="expected 70% by today"
+        value={62}
+        variant="success"
+      />
+      <Progress
+        aria-label="Warning tone with marker"
+        marker={70}
+        markerLabel="expected 70% by today"
+        value={62}
+        variant="warning"
+      />
+      <Progress
+        aria-label="Destructive tone with marker"
+        marker={70}
+        markerLabel="expected 70% by today"
+        value={62}
+        variant="destructive"
+      />
+    </div>
+  ),
+};