@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/resizable/resizable.tsx

@@ -1,28 +1,54 @@
+import { forwardRef, type ForwardRefExoticComponent, type RefAttributes } from "react";
 import { GripVertical } from "lucide-react";
 import * as ResizablePrimitive from "react-resizable-panels";
 import { cn } from "../../lib/cn";
 
-export function ResizablePanelGroup({
-  className,
-  ...props
-}: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>) {
+export const ResizablePanelGroup: ForwardRefExoticComponent<
+  React.ComponentProps<typeof ResizablePrimitive.PanelGroup> &
+    RefAttributes<ResizablePrimitive.ImperativePanelGroupHandle>
+> = forwardRef<
+  ResizablePrimitive.ImperativePanelGroupHandle,
+  React.ComponentProps<typeof ResizablePrimitive.PanelGroup>
+>(function ResizablePanelGroup({ className, ...props }, ref) {
   return (
     <ResizablePrimitive.PanelGroup
+      ref={ref}
       className={cn("flex size-full data-[panel-group-direction=vertical]:flex-col", className)}
       {...props}
     />
   );
-}
+});
 
 export const ResizablePanel = ResizablePrimitive.Panel;
 
+/**
+ * The visible line stays 1px (`w-px`); the DRAG hit area is expanded via the
+ * primitive's own `hitAreaMargins` (pointer-distance based, not a CSS trick),
+ * so pointer/touch users get a ≥16px target without widening what's drawn.
+ * Callers can still override `hitAreaMargins` explicitly.
+ */
+const DEFAULT_HIT_AREA_MARGINS: ResizablePrimitive.PointerHitAreaMargins = {
+  coarse: 15,
+  fine: 8,
+};
+
+/**
+ * NOT wrapped in `forwardRef`: `react-resizable-panels`' `PanelResizeHandle`
+ * is a plain function component that hardcodes its own internal element ref
+ * and does not accept `ref` as a prop at all (neither in its types nor at
+ * runtime — verified: a `ref` passed to it resolves to `null`). There is no
+ * DOM node here for a wrapper ref to attach to without changing what render
+ * onto the actual drag surface, so adding `forwardRef` would be a dead prop.
+ */
 export function ResizableHandle({
   withHandle,
   className,
+  hitAreaMargins,
   ...props
 }: React.ComponentProps<typeof ResizablePrimitive.PanelResizeHandle> & { withHandle?: boolean }) {
   return (
     <ResizablePrimitive.PanelResizeHandle
+      hitAreaMargins={hitAreaMargins ?? DEFAULT_HIT_AREA_MARGINS}
       className={cn(
         "relative flex w-px items-center justify-center bg-border after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-ring",
         "data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-1 data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:-translate-y-1/2 data-[panel-group-direction=vertical]:after:translate-x-0",

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";

package/src/components/revision-timeline/revision-timeline.tsx

@@ -73,6 +73,7 @@ import {
 import { cva, type VariantProps } from "class-variance-authority";
 import { ChevronRight, GitBranch, GitCommitHorizontal, GitMerge, Plus, Minus } from "lucide-react";
 import { cn } from "../../lib/cn";
+import { useLocale } from "../locale-provider";
 
 // ─── Public data types ────────────────────────────────────────────────────────
 
@@ -527,9 +528,7 @@ function DayHeader({ label }: DayHeaderProps) {
       style={{ height: DAY_HEADER_H }}
       className="box-border flex items-center gap-3 px-3"
     >
-      <span className="text-meta font-medium uppercase tracking-wide text-muted-foreground">
-        {label}
-      </span>
+      <span className="text-eyebrow uppercase text-muted-foreground">{label}</span>
       <div className="h-px flex-1 bg-border" aria-hidden="true" />
     </div>
   );
@@ -937,6 +936,7 @@ export const RevisionTimeline = forwardRef<HTMLDivElement, RevisionTimelineProps
     },
     ref,
   ) {
+    const { t } = useLocale();
     const resolvedDensity: RevisionTimelineDensity = density ?? "comfortable";
 
     // Collapse/expand mode is opt-in: active only when `branches` are supplied.
@@ -1059,7 +1059,7 @@ export const RevisionTimeline = forwardRef<HTMLDivElement, RevisionTimelineProps
         const from = summaryOf.get(e.from) ?? e.from;
         const to = summaryOf.get(e.to) ?? e.to;
         if (from === to) continue; // collapsed into a single node
-        const key = `${from}${to}`;
+        const key = `${from}\u0000${to}`;
         if (seen.has(key)) continue; // de-dup coincident remaps
         seen.add(key);
         out.push({ from, to });
@@ -1102,7 +1102,10 @@ export const RevisionTimeline = forwardRef<HTMLDivElement, RevisionTimelineProps
               {groups.map((group) => (
                 <div key={group.dayKey}>
                   {groupBy === "day" && <DayHeader label={group.dayLabel} />}
-                  <ol role="list" aria-label={groupBy === "day" ? group.dayLabel : "Revisions"}>
+                  <ol
+                    role="list"
+                    aria-label={groupBy === "day" ? group.dayLabel : t("ui.revisionTimeline.label")}
+                  >
                     {group.items.map((it) => {
                       if (it.kind === "summary") {
                         return (

package/src/components/schema-form/index.ts

@@ -33,6 +33,7 @@ export {
 export {
   fieldSpecSchema,
   formSpecSchema,
+  formSectionSchema,
   enumOptionSchema,
   keyValueRowSchema,
   stringFieldSchema,
@@ -73,6 +74,7 @@ export {
   type GroupFieldSpec,
   type FieldSpec,
   type FormSpec,
+  type FormSectionSpec,
   type FormValue,
   type FormValues,
   type FormSubmitState,

package/src/components/schema-form/schema-form-spec.ts

@@ -91,6 +91,11 @@ const baseField = {
       equals: z.union([z.string(), z.number(), z.boolean()]),
     })
     .optional(),
+  /**
+   * Show the value as read-only text (a `Descriptions` item) instead of an
+   * editable control. The value still belongs to the form's `values`.
+   */
+  readOnly: z.boolean().optional(),
 };
 
 /** A single-line or multi-line text field. */
@@ -306,7 +311,25 @@ export const formSpecSchema = z.object({
   fields: z.array(fieldSpecSchema),
   /** Submit button label. @default "Submit" */
   submitLabel: z.string().optional(),
+  /**
+   * Collapsible groups of top-level fields, in display order. Fields not named
+   * in any section render first, ungrouped. Omit for the flat layout.
+   */
+  sections: z.array(z.lazy(() => formSectionSchema)).optional(),
+});
+
+/** One collapsible group of top-level fields in a `FormSpec`. */
+export const formSectionSchema = z.object({
+  /** Stable key for the section. */
+  id: z.string(),
+  /** Heading on the section's disclosure trigger. */
+  label: z.string(),
+  /** Names of the top-level fields the section holds, in display order. */
+  fields: z.array(z.string()),
+  /** Start collapsed. @default false */
+  collapsed: z.boolean().optional(),
 });
+export type FormSectionSpec = z.infer<typeof formSectionSchema>;
 export type FormSpec = Omit<z.infer<typeof formSpecSchema>, "fields"> & { fields: FieldSpec[] };
 
 // ---------------------------------------------------------------------------
@@ -345,6 +368,8 @@ export interface NormalizedFormSpec {
   description?: string;
   submitLabel?: string;
   fields: FieldSpec[];
+  /** Collapsible field groups; absent when the spec declares none. */
+  sections?: FormSectionSpec[];
 }
 
 /**
@@ -415,10 +440,21 @@ export function normalizeFormSpec(
       description: typeof raw.description === "string" ? raw.description : undefined,
       submitLabel: typeof raw.submitLabel === "string" ? raw.submitLabel : undefined,
       fields,
+      ...normalizeSections(raw.sections),
     },
   };
 }
 
+/** Keep only well-formed sections; `{}` when there are none, so the normalized shape is unchanged. */
+function normalizeSections(raw: unknown): { sections?: FormSectionSpec[] } {
+  if (!Array.isArray(raw)) return {};
+  const sections = raw.flatMap((candidate) => {
+    const parsed = formSectionSchema.safeParse(candidate);
+    return parsed.success ? [parsed.data] : [];
+  });
+  return sections.length > 0 ? { sections } : {};
+}
+
 // ---------------------------------------------------------------------------
 // Field tree helpers (fields can nest inside `group` branches)
 // ---------------------------------------------------------------------------