@hraness/design-kit 0.31.1

package/src/mockups/client.tsx

@@ -0,0 +1,415 @@
+"use client";
+
+import {
+  type CSSProperties,
+  type KeyboardEvent,
+  type ReactNode,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+
+import { joinMockupClasses, type MockupTheme } from "./core.js";
+
+/*
+ * Interactive shells for the code-built mockups. They hold selection state
+ * and nothing else: every surface is a render function over plain props, so
+ * the same surface renders statically in a film or a server page.
+ */
+
+// React warns about useLayoutEffect during server rendering; these shells
+// measure only in the browser.
+const useIsomorphicLayoutEffect: typeof useLayoutEffect = typeof document === "undefined" ? () => undefined : useLayoutEffect;
+
+function assertUniqueIds(items: readonly Readonly<{ id: string }>[], what: string): void {
+  if (items.length === 0) throw new RangeError(`${what} needs at least one entry.`);
+  const seen = new Set<string>();
+  for (const item of items) {
+    if (typeof item.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/u.test(item.id)) {
+      throw new TypeError(`${what} ids must be lowercase letters, digits, and dashes: ${JSON.stringify(item.id)}`);
+    }
+    if (seen.has(item.id)) throw new RangeError(`${what} ids must be unique: ${item.id}`);
+    seen.add(item.id);
+  }
+}
+
+function itemAt<T>(items: readonly T[], index: number, what: string): T {
+  const item = items[index];
+  if (item === undefined) throw new RangeError(`${what} has no entry at ${String(index)}.`);
+  return item;
+}
+
+function assertCaption(caption: string, component: string): void {
+  if (typeof caption !== "string" || caption.trim() === "") {
+    throw new TypeError(`${component} needs a caption that says the picture is an illustration.`);
+  }
+}
+
+/** Arrow, Home, and End move between tabs, as in the WAI-ARIA tabs pattern. */
+function nextTabIndex(key: string, index: number, count: number): number | undefined {
+  if (key === "ArrowRight" || key === "ArrowDown") return (index + 1) % count;
+  if (key === "ArrowLeft" || key === "ArrowUp") return (index - 1 + count) % count;
+  if (key === "Home") return 0;
+  if (key === "End") return count - 1;
+  return undefined;
+}
+
+/* ------------------------------------------------------------------ */
+/* FitToWidth                                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Lays its child out at no less than `minWidth` pixels and scales it down to
+ * fit a narrower container, so a desktop mockup stays whole on a phone
+ * instead of reflowing into something no product looks like.
+ */
+export function FitToWidth({ children, className, minWidth = 400 }: Readonly<{ children: ReactNode; minWidth?: number; className?: string }>) {
+  if (!(minWidth > 0)) throw new RangeError("FitToWidth minWidth must be positive.");
+  const outer = useRef<HTMLDivElement>(null);
+  const inner = useRef<HTMLDivElement>(null);
+  const [fit, setFit] = useState<Readonly<{ width: number; scale: number; height: number }> | null>(null);
+
+  useIsomorphicLayoutEffect(() => {
+    const stage = outer.current;
+    const content = inner.current;
+    if (stage === null || content === null || typeof ResizeObserver === "undefined") return undefined;
+    const measure = () => {
+      const available = stage.clientWidth;
+      if (available <= 0) return;
+      const width = Math.max(available, minWidth);
+      const scale = available / width;
+      const height = content.offsetHeight * scale;
+      setFit((current) =>
+        current !== null && current.width === width && current.scale === scale && current.height === height ? current : { height, scale, width });
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(stage);
+    observer.observe(content);
+    return () => observer.disconnect();
+  }, [minWidth]);
+
+  const scaled = fit !== null && fit.scale < 1;
+  return (
+    <div className={joinMockupClasses("hkm-fit", className)} ref={outer} style={scaled ? { height: fit.height } : undefined}>
+      <div
+        className="hkm-fit-inner"
+        data-hkm-scaled={scaled ? "" : undefined}
+        ref={inner}
+        style={scaled ? { transform: `scale(${fit.scale})`, width: fit.width } : undefined}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* ModeShowcase                                                        */
+/* ------------------------------------------------------------------ */
+
+/** One choice on a showcase axis. `hint` says in one sentence what the choice does. */
+export type ShowcaseChoice<I extends string> = Readonly<{ id: I; label: string; hint: string }>;
+
+/** What a surface's render function receives. */
+export type ShowcaseState<M extends string, O extends string = string> = Readonly<{
+  mode: M;
+  /** The mode before the last change; equals `mode` until the first change. */
+  previousMode: M;
+  option: O | undefined;
+  /** False on first paint, true after the first user change, so the first paint never animates. */
+  animated: boolean;
+  theme: MockupTheme | undefined;
+}>;
+
+/** One tab in a showcase. `render` returns a mockup from `@hraness/design-kit/mockups` or a product skin. */
+export type ShowcaseSurface<S extends string, M extends string, O extends string = string> = Readonly<{
+  id: S;
+  label: string;
+  render: (state: ShowcaseState<M, O>) => ReactNode;
+}>;
+
+export type ModeShowcaseProps<S extends string, M extends string, O extends string = string> = Readonly<{
+  surfaces: readonly ShowcaseSurface<S, M, O>[];
+  modes: readonly ShowcaseChoice<M>[];
+  /** Label before the mode buttons, such as "Show AI text as". */
+  modeLabel?: string;
+  /** An optional second axis, such as sensitivity. */
+  options?: readonly ShowcaseChoice<O>[];
+  optionLabel?: string;
+  /** Modes in which the option axis does nothing; its buttons are disabled then. */
+  optionInactiveModes?: readonly M[];
+  initial?: Readonly<{ surface?: S; mode?: M; option?: O }>;
+  /** A live line under the stage that says what the current state shows. */
+  status?: (state: Readonly<{ surface: S; mode: M; option: O | undefined }>) => ReactNode;
+  /** Required. Say it is an illustration, such as "Illustration. Names and text are made up." */
+  caption: string;
+  /** Page-window height in CSS pixels at full scale. */
+  height?: number;
+  /** Narrowest layout width before the stage scales down. */
+  minWidth?: number;
+  theme?: MockupTheme;
+  /** Accessible name for the whole figure. Defaults to "Illustration of <surface>". */
+  label?: (surface: ShowcaseSurface<S, M, O>) => string;
+  className?: string;
+}>;
+
+/**
+ * An interactive illustration: tabs pick a surface, a segmented control picks
+ * a mode, and an optional second control picks an option. Tabs follow the
+ * WAI-ARIA tabs pattern with automatic activation; mode and option buttons are
+ * toggle buttons in labelled groups.
+ */
+export function ModeShowcase<S extends string, M extends string, O extends string = string>({
+  caption,
+  className,
+  height = 440,
+  initial,
+  label,
+  minWidth = 400,
+  modeLabel = "Mode",
+  modes,
+  optionInactiveModes = [],
+  optionLabel = "Option",
+  options,
+  status,
+  surfaces,
+  theme,
+}: ModeShowcaseProps<S, M, O>) {
+  assertUniqueIds(surfaces, "ModeShowcase surface");
+  assertUniqueIds(modes, "ModeShowcase mode");
+  if (options !== undefined) assertUniqueIds(options, "ModeShowcase option");
+  assertCaption(caption, "ModeShowcase");
+  if (!(height > 0)) throw new RangeError("ModeShowcase height must be positive.");
+
+  const id = useId();
+  const firstSurface = surfaces.find((surface) => surface.id === initial?.surface) ?? itemAt(surfaces, 0, "ModeShowcase surfaces");
+  const firstMode = modes.find((mode) => mode.id === initial?.mode) ?? itemAt(modes, 0, "ModeShowcase modes");
+  const firstOption = options === undefined ? undefined : (options.find((option) => option.id === initial?.option) ?? itemAt(options, 0, "ModeShowcase options"));
+  const [surfaceId, setSurfaceId] = useState<S>(firstSurface.id);
+  const [mode, setMode] = useState<M>(firstMode.id);
+  const [previousMode, setPreviousMode] = useState<M>(firstMode.id);
+  const [option, setOption] = useState<O | undefined>(firstOption?.id);
+  const [animated, setAnimated] = useState(false);
+  const tabs = useRef(new Map<S, HTMLButtonElement>());
+
+  const surface = surfaces.find((entry) => entry.id === surfaceId) ?? itemAt(surfaces, 0, "ModeShowcase surfaces");
+  const modeChoice = modes.find((entry) => entry.id === mode) ?? itemAt(modes, 0, "ModeShowcase modes");
+  const optionChoice = options?.find((entry) => entry.id === option);
+  const optionInactive = optionInactiveModes.includes(mode);
+
+  const chooseMode = (next: M) => {
+    if (next === mode) return;
+    setPreviousMode(mode);
+    setMode(next);
+    setAnimated(true);
+  };
+  const chooseOption = (next: O) => {
+    if (next === option) return;
+    setOption(next);
+    setAnimated(true);
+  };
+  const onTabKey = (event: KeyboardEvent<HTMLButtonElement>) => {
+    const index = surfaces.findIndex((entry) => entry.id === surface.id);
+    const next = nextTabIndex(event.key, index, surfaces.length);
+    if (next === undefined) return;
+    event.preventDefault();
+    const target = itemAt(surfaces, next, "ModeShowcase surfaces").id;
+    setSurfaceId(target);
+    tabs.current.get(target)?.focus();
+  };
+
+  const statusNode = status?.({ mode, option, surface: surface.id });
+  return (
+    <figure
+      aria-label={label?.(surface) ?? `Illustration of ${surface.label.toLowerCase()}`}
+      className={joinMockupClasses("hkm-showcase", className)}
+      data-hkm-theme={theme}
+      data-nosnippet=""
+    >
+      <div className="hkm-showcase-controls">
+        {surfaces.length > 1 ? (
+          <div aria-label="Surface" className="hkm-tabs" role="tablist">
+            {surfaces.map((entry) => (
+              <button
+                aria-controls={`${id}-panel`}
+                aria-selected={entry.id === surface.id}
+                className="hkm-tab"
+                id={`${id}-tab-${entry.id}`}
+                key={entry.id}
+                onClick={() => setSurfaceId(entry.id)}
+                onKeyDown={onTabKey}
+                ref={(element) => {
+                  if (element === null) tabs.current.delete(entry.id);
+                  else tabs.current.set(entry.id, element);
+                }}
+                role="tab"
+                tabIndex={entry.id === surface.id ? 0 : -1}
+                type="button"
+              >
+                {entry.label}
+              </button>
+            ))}
+          </div>
+        ) : null}
+        <div className="hkm-showcase-settings">
+          <div className="hkm-showcase-row">
+            <span className="hkm-showcase-label" id={`${id}-mode`}>{modeLabel}</span>
+            <div aria-labelledby={`${id}-mode`} className="hkm-segmented" role="group">
+              {modes.map((entry) => (
+                <button aria-pressed={entry.id === mode} key={entry.id} onClick={() => chooseMode(entry.id)} type="button">
+                  {entry.label}
+                </button>
+              ))}
+            </div>
+          </div>
+          {options === undefined ? null : (
+            <div className="hkm-showcase-row">
+              <span className="hkm-showcase-label" id={`${id}-option`}>{optionLabel}</span>
+              <div aria-labelledby={`${id}-option`} className="hkm-segmented" role="group">
+                {options.map((entry) => (
+                  <button aria-pressed={entry.id === option} disabled={optionInactive} key={entry.id} onClick={() => chooseOption(entry.id)} type="button">
+                    {entry.label}
+                  </button>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+        <p className="hkm-showcase-hint">
+          {modeChoice.hint}
+          {optionChoice === undefined || optionInactive ? null : ` ${optionChoice.hint}`}
+        </p>
+      </div>
+      <div
+        aria-labelledby={surfaces.length > 1 ? `${id}-tab-${surface.id}` : undefined}
+        className="hkm-showcase-stage"
+        data-hkm-animated={animated ? "" : undefined}
+        data-hkm-from={animated ? previousMode : undefined}
+        id={`${id}-panel`}
+        role={surfaces.length > 1 ? "tabpanel" : undefined}
+        style={{ "--hkm-page-height": `${height}px` } as CSSProperties}
+      >
+        <FitToWidth minWidth={minWidth}>
+          {surface.render({ animated, mode, option, previousMode, theme })}
+        </FitToWidth>
+      </div>
+      <figcaption className="hkm-showcase-caption">
+        {statusNode === undefined ? null : <span aria-live="polite" className="hkm-showcase-status">{statusNode}</span>}
+        <span>{caption}</span>
+      </figcaption>
+    </figure>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* StepThrough                                                         */
+/* ------------------------------------------------------------------ */
+
+/** One step in a step-through. `render` gets whether transitions may run. */
+export type ThroughStep = Readonly<{
+  id: string;
+  label: string;
+  /** One sentence under the stage that says what this step shows. */
+  hint?: string;
+  render: (state: Readonly<{ animated: boolean; theme: MockupTheme | undefined }>) => ReactNode;
+}>;
+
+/**
+ * Walks a flow one step at a time: numbered step tabs, Back and Next buttons,
+ * and a live hint. The keyboard model matches `ModeShowcase`.
+ */
+export function StepThrough({
+  caption,
+  className,
+  initial,
+  label = "Steps",
+  minWidth = 400,
+  steps,
+  theme,
+}: Readonly<{
+  steps: readonly ThroughStep[];
+  caption: string;
+  initial?: string;
+  label?: string;
+  minWidth?: number;
+  theme?: MockupTheme;
+  className?: string;
+}>) {
+  assertUniqueIds(steps, "StepThrough step");
+  assertCaption(caption, "StepThrough");
+  const id = useId();
+  const [index, setIndex] = useState(() => Math.max(0, steps.findIndex((step) => step.id === initial)));
+  const [animated, setAnimated] = useState(false);
+  const tabs = useRef(new Map<number, HTMLButtonElement>());
+  const current = Math.min(index, steps.length - 1);
+  const step = itemAt(steps, current, "StepThrough steps");
+
+  const go = (next: number, focus = false) => {
+    if (next < 0 || next >= steps.length || next === current) return;
+    setIndex(next);
+    setAnimated(true);
+    if (focus) tabs.current.get(next)?.focus();
+  };
+  const onTabKey = (event: KeyboardEvent<HTMLButtonElement>) => {
+    const next = nextTabIndex(event.key, current, steps.length);
+    if (next === undefined) return;
+    event.preventDefault();
+    go(next, true);
+  };
+
+  return (
+    <figure aria-label={`Illustration: ${label.toLowerCase()}`} className={joinMockupClasses("hkm-showcase", "hkm-steps", className)} data-hkm-theme={theme} data-nosnippet="">
+      <div className="hkm-showcase-controls">
+        <div aria-label={label} className="hkm-tabs hkm-step-tabs" role="tablist">
+          {steps.map((entry, position) => (
+            <button
+              aria-controls={`${id}-panel`}
+              aria-selected={position === current}
+              className="hkm-tab"
+              data-hkm-done={position < current ? "" : undefined}
+              id={`${id}-tab-${entry.id}`}
+              key={entry.id}
+              onClick={() => go(position)}
+              onKeyDown={onTabKey}
+              ref={(element) => {
+                if (element === null) tabs.current.delete(position);
+                else tabs.current.set(position, element);
+              }}
+              role="tab"
+              tabIndex={position === current ? 0 : -1}
+              type="button"
+            >
+              <span aria-hidden="true" className="hkm-step-number">{position + 1}</span>
+              {entry.label}
+            </button>
+          ))}
+        </div>
+      </div>
+      <div
+        aria-labelledby={`${id}-tab-${step.id}`}
+        className="hkm-showcase-stage"
+        data-hkm-animated={animated ? "" : undefined}
+        id={`${id}-panel`}
+        role="tabpanel"
+      >
+        <FitToWidth minWidth={minWidth}>{step.render({ animated, theme })}</FitToWidth>
+      </div>
+      <div className="hkm-step-nav">
+        <button className="hkm-step-button" disabled={current === 0} onClick={() => go(current - 1)} type="button">
+          Back
+        </button>
+        <span aria-live="polite" className="hkm-showcase-status">
+          Step {current + 1} of {steps.length}{step.hint === undefined ? "" : `. ${step.hint}`}
+        </span>
+        <button className="hkm-step-button" data-hkm-primary="" disabled={current === steps.length - 1} onClick={() => go(current + 1)} type="button">
+          Next
+        </button>
+      </div>
+      <figcaption className="hkm-showcase-caption">
+        <span>{caption}</span>
+      </figcaption>
+    </figure>
+  );
+}