@elabs-ai/components-ui 4.0.0

package/src/components/wizard/wizard.tsx

@@ -0,0 +1,354 @@
+"use client";
+// a2ui.exposed: no
+
+import {
+  createContext,
+  forwardRef,
+  use,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Check } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Button } from "../button";
+
+// ---------------------------------------------------------------------------
+// Types & context
+// ---------------------------------------------------------------------------
+
+export interface WizardStepMeta {
+  /** Stable id for the step. */
+  id: string;
+  /** Title shown in the step indicator. */
+  title: string;
+  /** Optional supporting text shown under the title. */
+  description?: string;
+}
+
+/** A step validator — return false (or a rejected/`false` promise) to block advance. */
+export type WizardValidator = () => boolean | Promise<boolean>;
+
+interface WizardContextValue {
+  baseId: string;
+  step: number;
+  steps: WizardStepMeta[];
+  count: number;
+  isFirst: boolean;
+  isLast: boolean;
+  validating: boolean;
+  goTo: (index: number) => void;
+  next: () => void;
+  prev: () => void;
+  setActiveValidator: (validator: WizardValidator | undefined) => void;
+  orientation: "horizontal" | "vertical";
+}
+
+const WizardContext = createContext<WizardContextValue | null>(null);
+
+function useWizard(): WizardContextValue {
+  const ctx = use(WizardContext);
+  if (!ctx) throw new Error("Wizard subcomponents must be used inside <Wizard>.");
+  return ctx;
+}
+
+const wizardVariants = cva("flex gap-6", {
+  variants: {
+    orientation: {
+      horizontal: "flex-col",
+      vertical: "flex-row",
+    },
+  },
+  defaultVariants: {
+    orientation: "horizontal",
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Wizard (Provider / root)
+// ---------------------------------------------------------------------------
+
+export interface WizardProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "onChange">, VariantProps<typeof wizardVariants> {
+  /** The ordered step metadata used to render the indicator. */
+  steps: WizardStepMeta[];
+  /** Controlled active step index. */
+  step?: number;
+  /** Uncontrolled initial step index. Default 0. */
+  defaultStep?: number;
+  /** Called whenever the active step changes. */
+  onStepChange?: (step: number) => void;
+  children?: ReactNode;
+}
+
+/**
+ * Wizard — a multi-step flow with a step indicator, per-step validation gating,
+ * and Back/Next/Finish navigation.
+ *
+ * Controlled via `step`/`onStepChange`; uncontrolled via `defaultStep`. State is
+ * lifted into the provider and exposed to `WizardSteps`/`WizardStep`/`WizardNav`
+ * via context. `Next` runs the active step's `validate` (sync or async) before
+ * advancing and stays enabled until validation runs.
+ */
+export const Wizard = forwardRef<HTMLDivElement, WizardProps>(function Wizard(
+  {
+    steps,
+    step: stepProp,
+    defaultStep = 0,
+    onStepChange,
+    orientation = "horizontal",
+    className,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const baseId = useId();
+  const isControlled = stepProp !== undefined;
+  const [internalStep, setInternalStep] = useState(defaultStep);
+  const [validating, setValidating] = useState(false);
+  const activeValidator = useRef<WizardValidator | undefined>(undefined);
+
+  const count = steps.length;
+  const step = Math.min(isControlled ? (stepProp ?? 0) : internalStep, Math.max(0, count - 1));
+
+  const commit = useCallback(
+    (next: number) => {
+      const clamped = Math.min(Math.max(0, next), Math.max(0, count - 1));
+      if (!isControlled) setInternalStep(clamped);
+      onStepChange?.(clamped);
+    },
+    [isControlled, onStepChange, count],
+  );
+
+  const goTo = useCallback(
+    (index: number) => {
+      // Backward / same navigation never requires validation.
+      if (index <= step) {
+        commit(index);
+      }
+    },
+    [step, commit],
+  );
+
+  const next = useCallback(() => {
+    const validator = activeValidator.current;
+    const advance = () => commit(step + 1);
+    if (!validator) {
+      advance();
+      return;
+    }
+    const result = validator();
+    if (typeof result === "boolean") {
+      if (result) advance();
+      return;
+    }
+    setValidating(true);
+    result
+      .then((ok) => {
+        if (ok) advance();
+      })
+      .finally(() => setValidating(false));
+  }, [step, commit]);
+
+  const prev = useCallback(() => commit(step - 1), [step, commit]);
+
+  const setActiveValidator = useCallback((validator: WizardValidator | undefined) => {
+    activeValidator.current = validator;
+  }, []);
+
+  const ctx = useMemo<WizardContextValue>(
+    () => ({
+      baseId,
+      step,
+      steps,
+      count,
+      isFirst: step === 0,
+      isLast: step === count - 1,
+      validating,
+      goTo,
+      next,
+      prev,
+      setActiveValidator,
+      orientation: orientation ?? "horizontal",
+    }),
+    [baseId, step, steps, count, validating, goTo, next, prev, setActiveValidator, orientation],
+  );
+
+  return (
+    <WizardContext value={ctx}>
+      <div
+        ref={ref}
+        data-slot="wizard"
+        className={cn(wizardVariants({ orientation }), className)}
+        {...props}
+      >
+        {children}
+      </div>
+    </WizardContext>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// WizardSteps (the indicator)
+// ---------------------------------------------------------------------------
+
+export type WizardStepsProps = HTMLAttributes<HTMLOListElement>;
+
+/** WizardSteps — the ordered step indicator. Reads steps from context. */
+export const WizardSteps = forwardRef<HTMLOListElement, WizardStepsProps>(function WizardSteps(
+  { className, ...props },
+  ref,
+) {
+  const { baseId, step, steps, orientation, goTo } = useWizard();
+  return (
+    <ol
+      ref={ref}
+      className={cn(
+        "flex gap-2",
+        orientation === "vertical" ? "flex-col" : "flex-row flex-wrap items-center",
+        className,
+      )}
+      {...props}
+    >
+      {steps.map((meta, index) => {
+        const isActive = index === step;
+        const isComplete = index < step;
+        const isClickable = index <= step;
+        return (
+          <li
+            key={meta.id}
+            id={`${baseId}-step-${index}`}
+            aria-current={isActive ? "step" : undefined}
+            className={cn("flex items-center gap-2", orientation === "horizontal" && "min-w-0")}
+          >
+            <button
+              type="button"
+              disabled={!isClickable}
+              onClick={() => goTo(index)}
+              className={cn(
+                "flex size-7 shrink-0 items-center justify-center rounded-full border text-xs font-medium tabular-nums",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+                isActive && "border-primary bg-primary text-primary-foreground",
+                // #399 — the step NUMBER is text on a `/10` wash, not plate ink
+                // and not a mark: `-text` rung. The border keeps the fill rung.
+                isComplete && "border-primary bg-primary/10 text-primary-text",
+                !isActive && !isComplete && "border-border-strong text-muted-foreground",
+                isClickable ? "cursor-pointer" : "cursor-default",
+              )}
+            >
+              {isComplete ? <Check className="size-4" aria-hidden="true" /> : index + 1}
+            </button>
+            <span className="flex min-w-0 flex-col">
+              <span
+                className={cn(
+                  "truncate text-sm font-medium",
+                  isActive ? "text-foreground" : "text-muted-foreground",
+                )}
+              >
+                {meta.title}
+              </span>
+              {meta.description && (
+                <span className="truncate text-xs text-muted-foreground">{meta.description}</span>
+              )}
+            </span>
+          </li>
+        );
+      })}
+    </ol>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// WizardStep (per-step content + validator)
+// ---------------------------------------------------------------------------
+
+export interface WizardStepProps extends HTMLAttributes<HTMLDivElement> {
+  /** This step's index (0-based) — must match its position in `steps`. */
+  step: number;
+  /** Run before advancing past this step. Return false to block. */
+  validate?: WizardValidator;
+}
+
+/**
+ * WizardStep — renders its children only when it is the active step, and
+ * registers its `validate` with the wizard while active. Receives focus on
+ * activation for keyboard users.
+ */
+export const WizardStep = forwardRef<HTMLDivElement, WizardStepProps>(function WizardStep(
+  { step, validate, className, children, ...props },
+  ref,
+) {
+  const { step: activeStep, baseId, setActiveValidator } = useWizard();
+  const isActive = step === activeStep;
+  const regionRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isActive) return;
+    setActiveValidator(validate);
+    // Move focus to the newly-revealed step for keyboard users.
+    regionRef.current?.focus();
+    return () => setActiveValidator(undefined);
+  }, [isActive, validate, setActiveValidator]);
+
+  if (!isActive) return null;
+
+  return (
+    <div
+      ref={(node) => {
+        regionRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      }}
+      role="group"
+      aria-labelledby={`${baseId}-step-${step}`}
+      tabIndex={-1}
+      className={cn("min-w-0 flex-1 focus-visible:outline-none", className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// WizardNav (Back / Next / Finish)
+// ---------------------------------------------------------------------------
+
+export interface WizardNavProps extends HTMLAttributes<HTMLDivElement> {
+  backLabel?: string;
+  nextLabel?: string;
+  finishLabel?: string;
+  /** Called when Finish is pressed on the last step. */
+  onFinish?: () => void;
+}
+
+/** WizardNav — Back / Next (or Finish on the last step) controls. */
+export const WizardNav = forwardRef<HTMLDivElement, WizardNavProps>(function WizardNav(
+  { backLabel = "Back", nextLabel = "Next", finishLabel = "Finish", onFinish, className, ...props },
+  ref,
+) {
+  const { isFirst, isLast, validating, next, prev } = useWizard();
+  return (
+    <div ref={ref} className={cn("flex items-center justify-between gap-2", className)} {...props}>
+      <Button type="button" variant="outline" onClick={prev} disabled={isFirst}>
+        {backLabel}
+      </Button>
+      {isLast ? (
+        <Button type="button" onClick={onFinish}>
+          {finishLabel}
+        </Button>
+      ) : (
+        <Button type="button" onClick={next} disabled={validating}>
+          {validating ? "Checking…" : nextLabel}
+        </Button>
+      )}
+    </div>
+  );
+});

package/src/decoration.stories.tsx

@@ -0,0 +1,236 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { DecorationProvider, type DecorationLevel } from "@elabs-ai/components-tokens";
+import { Button } from "./components/button";
+import { Card, CardContent, CardHeader, CardTitle } from "./components/card";
+import { Badge } from "./components/badge";
+import { Input } from "./components/input";
+
+/**
+ * Foundation/Decoration — the decoration DIAL (`--decoration`, 0–10), orthogonal
+ * to color. The SAME real `@elabs-ai/components-ui` components are rendered across the ramp.
+ *
+ * WHAT THE DIAL TOUCHES: backgrounds, and nothing else. It fades a drafting
+ * sheet in behind the page (faded, never flat — see `Fade` below) and, at 8–10,
+ * squares the large radii and goes shadowless. Charts additionally swap flat
+ * series fills for patterns at 8–10.
+ *
+ * WHAT IT NEVER TOUCHES: the inside of a control. The buttons, inputs and badges
+ * below render identically at decoration 10 and at 0 — no hatch, no
+ * drawn-not-filled plates. Texture inside an input is noise where someone is
+ * reading their own typing, and re-inking the six role fills collapsed them to
+ * one appearance, which used to force a whole compensating non-colour channel.
+ *
+ * It is hue-INDEPENDENT — flip the **theme** toolbar to see the dial on green,
+ * navy, light paper, etc. Any story can be swept via the **Decoration** toolbar
+ * global (or `globals=decoration:<0..10>`).
+ * Set it in code via `<DecorationProvider level={n}>`, a `data-decoration="n"`
+ * attribute, or `ThemeProvider`/`useDecoration` (document-level).
+ */
+const meta = {
+  title: "Foundations/Decoration",
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+} satisfies Meta;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+function Sample() {
+  return (
+    <Card className="w-64">
+      <CardHeader>
+        <CardTitle>Revenue</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        <p className="text-display font-semibold tracking-tight text-foreground">$48.2M</p>
+        <div className="flex gap-2">
+          <Badge>healthy</Badge>
+          <Badge variant="warning">degraded</Badge>
+        </div>
+        <Input placeholder="Filter services…" />
+        <div className="flex gap-2">
+          <Button>Save</Button>
+          <Button variant="outline">Cancel</Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+const LEVELS: DecorationLevel[] = [0, 4, 8, 10];
+
+export const Dial: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-start gap-8">
+      {LEVELS.map((level) => (
+        <div key={level} className="space-y-2">
+          <p className="font-mono text-meta uppercase tracking-wider text-muted-foreground">
+            decoration {level}
+          </p>
+          <DecorationProvider level={level}>
+            <Sample />
+          </DecorationProvider>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+const FADES = ["top", "bottom", "edges", "center"] as const;
+
+/**
+ * The GROUND FADE (`data-decoration-fade`) — an opt-in region gesture that fades
+ * the ambient graph paper out instead of ruling a region edge to edge. It paints
+ * the SAME `--deco-grid` on a decorative `::before` layer and masks THAT, so the ink
+ * still rides the dial (inert at decoration 0) and the region's own content is
+ * never masked — the text in each panel stays at full opacity.
+ *
+ * The fade OWNS its region's ground. Opaque surfaces are never ruled themselves —
+ * the ambient sheet is painted once, behind the page — so a nested surface can't
+ * punch a crisp, full-strength rectangle into the field that was just faded out
+ * (the third panel below nests a `bg-card`).
+ *
+ * Budget: it spends the region's one focal drafting gesture. For a one-off fade on
+ * a single element, use Tailwind's own `mask-t-from-*` / `mask-radial-*` utilities.
+ *
+ * Shipped in anger on `Patterns/Templates/Marketing`, whose hero band carries
+ * `data-decoration-fade="top"` so the sheet fades in behind the headline instead of
+ * starting on a hard ruled edge — that template, not this matrix, is the surface to
+ * judge the gesture on.
+ *
+ * Sweep it with the **Decoration** toolbar (this story pins the dial to 10 so the
+ * gesture is visible on every theme; at 0 the mask has nothing to reveal).
+ */
+export const Fade: Story = {
+  globals: { decoration: "10" },
+  render: () => (
+    <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+      {FADES.map((fade) => (
+        <div
+          key={fade}
+          data-decoration-fade={fade}
+          data-testid={`fade-${fade}`}
+          className="min-h-40 rounded-lg bg-card p-4 text-card-foreground"
+        >
+          <p className="text-subtitle font-medium">{fade}</p>
+          <p className="text-caption text-muted-foreground">
+            Content stays fully opaque — only the ground fades.
+          </p>
+          {fade === "edges" ? (
+            <div
+              data-testid="fade-nested-surface"
+              className="mt-3 rounded-md bg-card p-2 text-caption text-muted-foreground"
+            >
+              A nested surface does not re-rule the faded ground.
+            </div>
+          ) : null}
+        </div>
+      ))}
+    </div>
+  ),
+  /**
+   * Locks the #257 contract that a static reading of the CSS cannot: the mask
+   * belongs to a decorative `::before` layer, so the host's CHILDREN are never
+   * faded and the layer never swallows a click — and the faded region is ruled
+   * exactly once, host and descendants alike.
+   */
+  play: async ({ canvas }) => {
+    const host = canvas.getByTestId("fade-edges");
+
+    // The host itself is unmasked — otherwise its text would fade with the grid.
+    await expect(getComputedStyle(host).maskImage).toBe("none");
+
+    // The decorative layer exists, paints the dial-driven grid, and is inert.
+    const layer = getComputedStyle(host, "::before");
+    await expect(layer.content).not.toBe("none");
+    await expect(layer.pointerEvents).toBe("none");
+    await expect(layer.backgroundImage).toContain("gradient");
+
+    // Every child renders at full opacity.
+    for (const child of Array.from(host.children)) {
+      await expect(getComputedStyle(child).opacity).toBe("1");
+    }
+
+    // The faded host is not ALSO ruled crisply…
+    await expect(getComputedStyle(host).backgroundImage).toBe("none");
+    // …and neither is a surface nested inside it (no crisp patch in a faded field).
+    const nested = canvas.getByTestId("fade-nested-surface");
+    await expect(getComputedStyle(nested).backgroundImage).toBe("none");
+  },
+};
+
+/**
+ * The AMBIENT GROUND, as an executable lock. The sheet is painted exactly once —
+ * on a fixed, masked layer behind the page — so this asserts the three properties
+ * a static reading of the CSS cannot: the layer exists and carries the dial-driven
+ * grid, it is MASKED (never flat), and no opaque surface re-rules it on top.
+ *
+ * The dial is set from the toolbar global, which writes `data-decoration` on the
+ * preview root exactly as `ThemeProvider` does — a `DecorationProvider` wrapper
+ * would NOT reach `body`, which is why `Dial` above cannot stand in for this.
+ */
+export const AmbientGround: Story = {
+  globals: { decoration: "10" },
+  render: () => (
+    <Card className="w-64" data-testid="ground-card">
+      <CardHeader>
+        <CardTitle>On the sheet</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p className="text-caption text-muted-foreground">
+          An opaque panel covers the ground; it never re-rules it.
+        </p>
+      </CardContent>
+    </Card>
+  ),
+  play: async () => {
+    const ground = getComputedStyle(document.body, "::before");
+
+    // The sheet exists and carries the dial-driven grid…
+    await expect(ground.content).not.toBe("none");
+    await expect(ground.backgroundImage).toContain("gradient");
+    await expect(ground.position).toBe("fixed");
+    await expect(ground.pointerEvents).toBe("none");
+
+    // …and it is never flat: the layer itself is masked.
+    await expect(ground.maskImage).not.toBe("none");
+
+    // The host is unmasked, so the page's own content is never faded with it.
+    await expect(getComputedStyle(document.body).maskImage).toBe("none");
+  },
+};
+
+/**
+ * The control invariant, as an executable lock: at FULL decoration the dial must
+ * not have painted anything into a control. A `Button` keeps its solid role fill
+ * (no `background-image`), an `Input` keeps a clean ground, and a `Badge` keeps
+ * its own tone rather than collapsing to a drawn outline.
+ *
+ * This is the story to run when someone reintroduces a "drawn-not-filled" rule:
+ * it fails on the hatch, not on a screenshot review three weeks later.
+ */
+export const ControlsAreUntouched: Story = {
+  globals: { decoration: "10" },
+  render: () => (
+    <div data-testid="controls" className="flex flex-wrap items-center gap-3">
+      <Button data-testid="deco-button">Save</Button>
+      <Button variant="outline">Cancel</Button>
+      <Badge variant="warning">degraded</Badge>
+      <Input data-testid="deco-input" placeholder="Filter services…" className="w-48" />
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const button = canvas.getByTestId("deco-button");
+    const input = canvas.getByTestId("deco-input");
+
+    // No hatch, no texture: the dial paints backgrounds, never controls.
+    await expect(getComputedStyle(button).backgroundImage).toBe("none");
+    await expect(getComputedStyle(input).backgroundImage).toBe("none");
+
+    // And the role fill is still a real, opaque plate — not the old
+    // "transparent ground + hairline" drawn control.
+    await expect(getComputedStyle(button).backgroundColor).not.toBe("rgba(0, 0, 0, 0)");
+    await expect(getComputedStyle(button).backgroundColor).not.toBe("transparent");
+  },
+};