@elabs-ai/components-ui 4.2.0 → 5.1.0

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>
+  ),
+};

package/src/components/progress/progress.test.tsx

@@ -32,4 +32,51 @@ describe("Progress", () => {
       "Exceeded — 100 of 100",
     );
   });
+
+  // marker (pace / target reference tick)
+  it("renders no tick and leaves the DOM unchanged when marker is unset", () => {
+    const { container } = render(<Progress value={40} />);
+    expect(container.querySelector('[data-slot="progress-marker"]')).toBeNull();
+    // The Indicator stays the progressbar's direct child (no wrapper added).
+    const directChild = container.querySelector('[role="progressbar"] > *');
+    expect(directChild).toHaveAttribute("data-slot", "progress-indicator");
+  });
+
+  it("positions the tick at marker% via insetInlineStart", () => {
+    const { container } = render(<Progress value={40} marker={70} />);
+    const tick = container.querySelector('[data-slot="progress-marker"]');
+    expect(tick).toHaveStyle({ insetInlineStart: "70%" });
+  });
+
+  it("clamps marker to 0–100", () => {
+    const { container } = render(<Progress value={40} marker={140} />);
+    const tick = container.querySelector('[data-slot="progress-marker"]');
+    expect(tick).toHaveStyle({ insetInlineStart: "100%" });
+  });
+
+  it("is decorative and leaves aria-valuetext unchanged when markerLabel is absent", () => {
+    render(<Progress value={62} marker={70} />);
+    const progressbar = screen.getByRole("progressbar");
+    expect(progressbar).not.toHaveAttribute("aria-valuetext");
+  });
+
+  it("composes aria-valuetext from value + markerLabel when both marker and markerLabel are set", () => {
+    render(<Progress value={62} marker={70} markerLabel="expected 70% by today" />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-valuetext",
+      "62%, expected 70% by today",
+    );
+  });
+
+  it("lets a caller-supplied aria-valuetext win over the composed marker text", () => {
+    render(
+      <Progress
+        aria-valuetext="Custom text"
+        marker={70}
+        markerLabel="expected 70% by today"
+        value={62}
+      />,
+    );
+    expect(screen.getByRole("progressbar")).toHaveAttribute("aria-valuetext", "Custom text");
+  });
 });

package/src/components/progress/progress.tsx

@@ -23,7 +23,25 @@ export const progressIndicatorVariants = cva("size-full flex-1 transition-transf
 export interface ProgressProps
   extends
     ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>,
-    VariantProps<typeof progressIndicatorVariants> {}
+    VariantProps<typeof progressIndicatorVariants> {
+  /**
+   * Reference point (0–100, same scale as `value`) — e.g. an "expected by
+   * today" pace or a target — rendered as a thin vertical tick on the track.
+   * Unset (default) renders no tick and leaves the DOM/layout byte-identical
+   * to a marker-less `Progress`.
+   */
+  marker?: number;
+  /**
+   * What `marker` represents (already localized by the caller — e.g.
+   * `"expected 70% by today"`). When set, it is appended to the progress
+   * bar's accessible value text so assistive tech hears the reference point
+   * alongside the value; a caller-supplied `aria-valuetext` always wins over
+   * this composition. When `marker` is set but `markerLabel` is not, the
+   * tick is purely decorative and `aria-valuetext` is left untouched — this
+   * component never invents its own English copy (i18n-strings).
+   */
+  markerLabel?: string;
+}
 
 /**
  * Color must not be the only signal a guardrail tripped: set `aria-valuetext`
@@ -32,12 +50,27 @@ export interface ProgressProps
  * `...props` (Radix's `ProgressPrimitive.Root` already supports it).
  */
 export const Progress = forwardRef<ElementRef<typeof ProgressPrimitive.Root>, ProgressProps>(
-  function Progress({ className, value, variant, ...props }, ref) {
-    return (
+  function Progress(
+    { className, value, variant, marker, markerLabel, "aria-valuetext": ariaValuetext, ...props },
+    ref,
+  ) {
+    const hasMarker = typeof marker === "number" && Number.isFinite(marker);
+    const clampedMarker = hasMarker ? Math.min(100, Math.max(0, marker as number)) : undefined;
+    // No invented English glue words (i18n-strings) — just the numeric value
+    // plus the caller's own, already-localized `markerLabel`. A caller's own
+    // `aria-valuetext` always wins and is never overwritten.
+    const resolvedValuetext =
+      ariaValuetext ??
+      (hasMarker && markerLabel && typeof value === "number"
+        ? `${Math.round(value)}%, ${markerLabel}`
+        : undefined);
+
+    const root = (
       <ProgressPrimitive.Root
         ref={ref}
         data-slot="progress"
         value={value}
+        aria-valuetext={resolvedValuetext}
         className={cn("relative h-2 w-full overflow-hidden rounded-full bg-muted", className)}
         {...props}
       >
@@ -48,5 +81,26 @@ export const Progress = forwardRef<ElementRef<typeof ProgressPrimitive.Root>, Pr
         />
       </ProgressPrimitive.Root>
     );
+
+    if (!hasMarker) {
+      return root;
+    }
+
+    return (
+      // Root keeps `overflow-hidden` (clips the indicator fill, unchanged
+      // above); the tick lives OUTSIDE it as a sibling so it is never
+      // clipped. The wrapper mirrors `className` so it matches the track's
+      // own box exactly (width/height/flex sizing), which is what the
+      // tick's `insetInlineStart` percentage is measured against.
+      <div className={cn("relative", className)}>
+        {root}
+        <span
+          aria-hidden={markerLabel ? undefined : "true"}
+          className="pointer-events-none absolute -top-0.5 -bottom-0.5 w-0.5 bg-foreground"
+          data-slot="progress-marker"
+          style={{ insetInlineStart: `${clampedMarker}%` }}
+        />
+      </div>
+    );
   },
 );

package/src/components/reveal-on-enter/index.ts

@@ -0,0 +1,5 @@
+export {
+  RevealOnEnter,
+  type RevealOnEnterElement,
+  type RevealOnEnterProps,
+} from "./reveal-on-enter";

package/src/components/reveal-on-enter/reveal-on-enter.css

@@ -0,0 +1,32 @@
+/*
+ * RevealOnEnter — once-only entrance. The server HTML never carries the hidden state: the
+ * component sets `data-reveal="hidden"` only after hydration, only when the motion gate is open,
+ * only for content still outside the viewport, and flips it to "shown" the first time it
+ * intersects (never back). Timing and easing are the gated tokens (`--t-base`,
+ * `--ease-entrance`); the stagger step scales with `--motion-factor`. `opacity`/`transform` only.
+ */
+@layer base {
+  [data-slot="reveal-on-enter"] {
+    /* Per-child delay step for `stagger`; multiplied by --motion-factor below. */
+    --reveal-stagger-step: 60ms;
+  }
+
+  [data-slot="reveal-on-enter"][data-reveal]:not([data-stagger]),
+  [data-slot="reveal-on-enter"][data-reveal][data-stagger] > * {
+    transition-property: opacity, transform;
+    transition-duration: var(--t-base);
+    transition-timing-function: var(--ease-entrance);
+  }
+
+  [data-slot="reveal-on-enter"][data-reveal][data-stagger] > * {
+    transition-delay: calc(
+      var(--reveal-index, 0) * var(--reveal-stagger-step) * var(--motion-factor)
+    );
+  }
+
+  [data-slot="reveal-on-enter"][data-reveal="hidden"]:not([data-stagger]),
+  [data-slot="reveal-on-enter"][data-reveal="hidden"][data-stagger] > * {
+    opacity: 0;
+    transform: translateY(24px);
+  }
+}

package/src/components/reveal-on-enter/reveal-on-enter.stories.tsx

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+import { Card, CardDescription, CardHeader, CardTitle } from "../card";
+import { RevealOnEnter } from "./reveal-on-enter";
+
+const ITEMS = [
+  {
+    id: "once",
+    title: "Once",
+    description: "Content reveals the first time it enters, never again.",
+  },
+  { id: "visible", title: "Visible first", description: "The server HTML is fully visible." },
+  { id: "gated", title: "Gated", description: "Reduced motion shows everything at once." },
+];
+
+function Reveals({ stagger = false }: { stagger?: boolean }) {
+  return (
+    <div className="p-8">
+      <p className="text-body text-muted-foreground">Scroll down to reveal the cards.</p>
+      <div className="min-h-screen" />
+      <RevealOnEnter as="ul" stagger={stagger} className="grid gap-6 sm:grid-cols-3">
+        {ITEMS.map((item) => (
+          <li key={item.id}>
+            <Card>
+              <CardHeader>
+                <CardTitle>{item.title}</CardTitle>
+                <CardDescription>{item.description}</CardDescription>
+              </CardHeader>
+            </Card>
+          </li>
+        ))}
+      </RevealOnEnter>
+      <div className="min-h-96" />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Display/RevealOnEnter",
+  component: RevealOnEnter,
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+  render: () => <Reveals />,
+} satisfies Meta<typeof RevealOnEnter>;
+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 = {
+  play: async ({ canvasElement }) => {
+    const el = canvasElement.querySelector<HTMLElement>('[data-slot="reveal-on-enter"]')!;
+    el.scrollIntoView();
+    await waitFor(() => expect(el.getAttribute("data-reveal")).not.toBe("hidden"));
+  },
+};
+
+/** Each child reveals 60 ms × `--motion-factor` after the one before. */
+export const Stagger: Story = {
+  render: () => <Reveals stagger />,
+};
+
+export const Dark: Story = {
+  parameters: { themes: { themeOverride: "dark" } },
+};
+
+export const Decoration10: Story = {
+  globals: { decoration: "10" },
+};
+
+/** Under reduced motion nothing is ever hidden and nothing animates. */
+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">
+      <Reveals stagger />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.querySelector("[data-reveal]")).toBeNull();
+    // 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([]),
+    );
+  },
+};

package/src/components/reveal-on-enter/reveal-on-enter.test.tsx

@@ -0,0 +1,87 @@
+import type * as React from "react";
+import { act, render } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RevealOnEnter } from "./reveal-on-enter";
+
+type ObserverCallback = (entries: Array<{ isIntersecting: boolean }>) => void;
+let fire: ObserverCallback = () => {};
+
+function stubObserver() {
+  vi.stubGlobal(
+    "IntersectionObserver",
+    class {
+      constructor(cb: ObserverCallback) {
+        fire = cb;
+      }
+      observe() {}
+      disconnect() {}
+    },
+  );
+}
+
+function belowTheFold(el: Element) {
+  vi.spyOn(el, "getBoundingClientRect").mockReturnValue({ top: 5000, bottom: 5100 } as DOMRect);
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  document.documentElement.style.removeProperty("--motion-factor");
+});
+
+describe("RevealOnEnter", () => {
+  it("server-renders its children fully visible", () => {
+    const html = renderToString(
+      <RevealOnEnter as="section" stagger>
+        <p>One</p>
+        <p>Two</p>
+      </RevealOnEnter>,
+    );
+    expect(html).toContain("<section");
+    expect(html).toContain("One");
+    expect(html).not.toMatch(/opacity|hidden|data-reveal/);
+  });
+
+  it("hides off-screen content after hydration and reveals it once", () => {
+    stubObserver();
+    const proto = HTMLElement.prototype;
+    belowTheFold(proto);
+    const { container } = render(<RevealOnEnter>Hello</RevealOnEnter>);
+    const el = container.firstElementChild!;
+    expect(el).toHaveAttribute("data-reveal", "hidden");
+    act(() => fire([{ isIntersecting: true }]));
+    expect(el).toHaveAttribute("data-reveal", "shown");
+    act(() => fire([{ isIntersecting: false }]));
+    expect(el).toHaveAttribute("data-reveal", "shown");
+  });
+
+  it("indexes children for the stagger", () => {
+    stubObserver();
+    belowTheFold(HTMLElement.prototype);
+    const { container } = render(
+      <RevealOnEnter stagger>
+        <p>One</p>
+        <p>Two</p>
+      </RevealOnEnter>,
+    );
+    const second = container.querySelectorAll("p")[1]!;
+    expect(second.style.getPropertyValue("--reveal-index")).toBe("1");
+  });
+
+  it("never hides content at the motion floor or without an observer", () => {
+    belowTheFold(HTMLElement.prototype);
+    vi.stubGlobal("IntersectionObserver", undefined);
+    const { container: noObserver } = render(<RevealOnEnter>A</RevealOnEnter>);
+    expect(noObserver.firstElementChild).not.toHaveAttribute("data-reveal");
+    stubObserver();
+    // A subtree dials motion through --motion-factor; jsdom does not inherit custom
+    // properties, so the dial sits on the element itself here.
+    const { container: reduced } = render(
+      <RevealOnEnter style={{ "--motion-factor": "0.0001" } as React.CSSProperties}>
+        B
+      </RevealOnEnter>,
+    );
+    expect(reduced.firstElementChild).not.toHaveAttribute("data-reveal");
+  });
+});

package/src/components/reveal-on-enter/reveal-on-enter.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import * as React from "react";
+import { isMotionAtFloor, readMotionFactor } from "../../lib/use-scroll-progress";
+import "./reveal-on-enter.css";
+
+/** Elements RevealOnEnter may render as. */
+export type RevealOnEnterElement =
+  | "div"
+  | "section"
+  | "article"
+  | "aside"
+  | "header"
+  | "footer"
+  | "ul"
+  | "ol"
+  | "li";
+
+export interface RevealOnEnterProps extends React.HTMLAttributes<HTMLElement> {
+  /** The element to render. Default `div`. */
+  as?: RevealOnEnterElement;
+  /** Reveal each direct child in turn (60 ms × `--motion-factor` apart) instead of the whole. */
+  stagger?: boolean;
+}
+
+type RevealPhase = "idle" | "hidden" | "shown";
+
+/**
+ * Fades and lifts its content in the first time it scrolls into view — once, never re-hiding.
+ * Content is never hidden from a reader or a crawler: the server HTML is fully visible, and the
+ * hidden state is applied only after hydration, only when the motion gate is open, only when
+ * `IntersectionObserver` exists, and only for content that is not already on screen.
+ */
+export const RevealOnEnter = React.forwardRef<HTMLElement, RevealOnEnterProps>(
+  ({ as: Comp = "div", stagger = false, ...props }, ref) => {
+    const innerRef = React.useRef<HTMLElement>(null);
+    React.useImperativeHandle(ref, () => innerRef.current as HTMLElement, []);
+    const [phase, setPhase] = React.useState<RevealPhase>("idle");
+
+    React.useEffect(() => {
+      const el = innerRef.current;
+      if (!el || typeof IntersectionObserver === "undefined") return;
+      if (isMotionAtFloor(readMotionFactor(el))) return;
+      const rect = el.getBoundingClientRect();
+      if (rect.top < window.innerHeight && rect.bottom > 0) return; // already seen: leave it be
+      if (stagger) {
+        Array.from(el.children).forEach((child, index) => {
+          (child as HTMLElement).style.setProperty("--reveal-index", String(index));
+        });
+      }
+      setPhase("hidden");
+      const observer = new IntersectionObserver((entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return;
+        setPhase("shown");
+        observer.disconnect();
+      });
+      observer.observe(el);
+      return () => observer.disconnect();
+    }, [stagger]);
+
+    // Every `as` option is a block element with the same attribute surface; typing the tag as
+    // `div` keeps JSX (and its `data-slot` declaration) without a per-tag ref union.
+    const Tag = Comp as "div";
+    return (
+      <Tag
+        ref={innerRef as React.Ref<HTMLDivElement>}
+        data-slot="reveal-on-enter"
+        data-reveal={phase === "idle" ? undefined : phase}
+        data-stagger={stagger ? "" : undefined}
+        {...props}
+      />
+    );
+  },
+);
+RevealOnEnter.displayName = "RevealOnEnter";