@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/data-layout/Odometer.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { useInView, useReducedMotion } from "motion/react";
+
+/**
+ * Odometer — the mechanical digit-roll counter promoted from the design
+ * reference (data/odometer), the companion to the count-up <StatCounter/>.
+ * Each digit of a formatted figure is a 0–9 reel that rolls to its value the
+ * first time the figure scrolls into view, staggered left to right; non-digit
+ * characters ($ , . %) sit static between reels. The figure carries an
+ * aria-label so screen readers announce the value once — the reels are
+ * decorative.
+ *
+ * SSR ships every reel already settled on its final digit, so the number is
+ * readable with no JS and under reduced motion. When motion is allowed, an
+ * effect rewinds the strips to zero (transitions suspended), forces a reflow,
+ * and releases them — all imperative DOM writes, no per-frame React state.
+ *
+ * <OdometerStrip/> is the reference arrangement: a hairline-divided cell grid
+ * of labelled odometers (sibling-index hairlines keyed off data-cols in
+ * styles/data-layout.css, re-derived for the 2-up collapse below 720px).
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/data-layout.css";
+ *                 @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+export function Odometer({
+  value,
+  className,
+}: {
+  /** Formatted figure — "$1,284,000", "2.31", "98%" … */
+  value: string;
+  className?: string;
+}) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const inView = useInView(ref, { amount: 0.6, once: true });
+  // Deliberately raw useReducedMotion(), not useMotionSafe(): `reduced` here
+  // is only ever read inside the effect below, never in this component's
+  // JSX, so it carries no hydration risk regardless of which hook computes
+  // it -- and useMotionSafe() layers its own extra useState+useEffect (to
+  // stay safe for consumers that DO read it during render), which means an
+  // extra post-mount re-render per Odometer instance for no behavioral
+  // gain here. A #2244 hardening pass swapped this to useMotionSafe() for
+  // "no raw useReducedMotion() call sites left" consistency; reverted after
+  // that additional per-instance re-render traffic measurably raised
+  // digithings.ai's live hydration-error rate (roughly 60% of fresh loads
+  // with the swap, vs. roughly 20% without it, in a 14-trial sample). That
+  // ~20% is itself a residual, unresolved rate under --webpack, not zero --
+  // this revert removes one confirmed contributing factor, not the whole
+  // bug. See #2244 and #2256 for the full account.
+  const reduced = useReducedMotion();
+
+  // SSR ships the settled reels; once in view (and motion is allowed) rewind
+  // every strip to zero with transitions suspended, force a reflow so the
+  // rewind commits, then release each reel toward its data-final target.
+  useEffect(() => {
+    const node = ref.current;
+    if (!node || !inView || reduced) return;
+    const strips = Array.from(node.querySelectorAll<HTMLElement>(".odo-strip"));
+    if (strips.length === 0) return;
+    for (const strip of strips) {
+      strip.style.transitionProperty = "none";
+      strip.style.transform = "translateY(0)";
+    }
+    void node.offsetHeight; // commit the rewind before the transition re-engages
+    for (const strip of strips) {
+      strip.style.transitionProperty = "";
+      strip.style.transform = strip.dataset.final ?? "";
+    }
+  }, [inView, reduced]);
+
+  return (
+    <span
+      ref={ref}
+      className={`odo inline-flex items-end font-mono text-[1.7rem] leading-none tabular-nums text-ink${
+        className ? ` ${className}` : ""
+      }`}
+      aria-label={value}
+    >
+      {value.split("").map((c, i) =>
+        /[0-9]/.test(c) ? (
+          <span className="inline-block h-[1em] overflow-hidden" key={i} aria-hidden="true">
+            <span
+              className="odo-strip"
+              data-final={`translateY(${-Number(c) * 10}%)`}
+              style={{
+                transform: `translateY(${-Number(c) * 10}%)`,
+                transitionDelay: `${i * 55}ms`,
+              }}
+            >
+              {Array.from({ length: 10 }, (_, n) => (
+                <span className="h-[1em] text-center leading-[1em]" key={n}>
+                  {n}
+                </span>
+              ))}
+            </span>
+          </span>
+        ) : (
+          <span className="inline-block" key={i} aria-hidden="true">
+            {c}
+          </span>
+        ),
+      )}
+    </span>
+  );
+}
+
+export type OdometerStat = {
+  /** Formatted figure the reels land on — "$1,284,000", "2.31" … */
+  value: string;
+  /** Mono micro-caps label under the figure. */
+  label: string;
+};
+
+const COLS: Record<2 | 3 | 4, string> = {
+  2: "grid-cols-2",
+  3: "grid-cols-3",
+  4: "grid-cols-4",
+};
+
+export function OdometerStrip({
+  stats,
+  columns = 4,
+  className,
+}: {
+  stats: OdometerStat[];
+  /** Desktop stats per row (collapses to 2 below 720px). */
+  columns?: 2 | 3 | 4;
+  className?: string;
+}) {
+  return (
+    <div
+      data-cols={columns}
+      className={`odo-grid grid ${COLS[columns]} overflow-hidden rounded-none border border-hair bg-surface max-[720px]:grid-cols-2${
+        className ? ` ${className}` : ""
+      }`}
+    >
+      {stats.map((s) => (
+        <div className="odo-cell p-[1.3rem]" key={s.label}>
+          <Odometer value={s.value} />
+          <span className="mt-[0.55rem] block font-mono text-[0.6rem] uppercase tracking-[0.1em] text-ink-mute">
+            {s.label}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/data-layout/ProductFrame.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import { useLayoutEffect, useEffect, useRef, type ReactNode } from "react";
+
+/**
+ * ProductFrame — the "real surface, cropped" technique promoted from the
+ * design reference (layout-patterns/product-frame): a product screenshot is
+ * authored once on a FIXED artboard (800×300 by default), then scaled
+ * proportionally to fit its container so it never reflows and stays
+ * pixel-faithful at any width. CSS calc() can't derive a unitless scale from
+ * lengths, so a ResizeObserver measures the container and writes the factor
+ * straight to the node (no per-frame React state). With no JS the artboard
+ * renders unscaled inside the overflow-hidden frame — a crop, never a break.
+ * An optional overlay tag labels the crop. Content is children-driven.
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/data-layout.css";
+ *                 @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+
+/** useLayoutEffect on the client (no paint flash); useEffect on the server
+ *  so SSR never warns about layout effects. Initial HTML stays the overflow
+ *  crop at scale 1 until measurement runs after hydration. */
+const useIsoLayoutEffect =
+  typeof document !== "undefined" ? useLayoutEffect : useEffect;
+
+export type ProductFrameProps = {
+  /** Mono overlay tag naming the crop — "research · research". */
+  tag?: string;
+  /** Fixed artboard width the children are authored against (px). */
+  artboardWidth?: number;
+  /** Fixed artboard height — with width, sets the frame's aspect ratio (px). */
+  artboardHeight?: number;
+  className?: string;
+  children: ReactNode;
+};
+
+export function ProductFrame({
+  tag,
+  artboardWidth = 800,
+  artboardHeight = 300,
+  className,
+  children,
+}: ProductFrameProps) {
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+  const artboardRef = useRef<HTMLDivElement | null>(null);
+
+  // Measuring/writing before paint removes the unscaled flash; ResizeObserver
+  // still owns every subsequent resize. Server path uses useEffect (above).
+  useIsoLayoutEffect(() => {
+    const vp = viewportRef.current;
+    const art = artboardRef.current;
+    if (!vp || !art) return;
+    const apply = (w: number) => {
+      art.style.scale = String(Math.min(1, w / artboardWidth));
+    };
+    apply(vp.clientWidth);
+    const ro = new ResizeObserver((entries) => apply(entries[0].contentRect.width));
+    ro.observe(vp);
+    return () => ro.disconnect();
+  }, [artboardWidth]);
+
+  return (
+    <div
+      className={`pf-viewport${className ? ` ${className}` : ""}`}
+      ref={viewportRef}
+      style={{ aspectRatio: `${artboardWidth} / ${artboardHeight}` }}
+    >
+      <div
+        className="pf-artboard"
+        ref={artboardRef}
+        style={{ width: artboardWidth, height: artboardHeight }}
+      >
+        {children}
+      </div>
+      {tag ? <span className="pf-tag">{tag}</span> : null}
+    </div>
+  );
+}

package/src/components/data-layout/TestimonialWall.tsx

@@ -0,0 +1,139 @@
+/**
+ * TestimonialWall — the trust band promoted from the design reference
+ * (layout-patterns/testimonial-wall): a pull-quote wall over a quiet org
+ * lockup. Quote data comes in via props; the voice doctrine is the caller's
+ * contract — real numbers and real orgs only, phrased as `{Org} × {product}`,
+ * never invented. Attribution avatars are mono initials derived from the
+ * name; the optional org strip closes the band under a hairline. A quote may
+ * carry an `href` so a named customer's org links to its own public site, and
+ * `columns` drops the wall to two for a band holding two voices — or to one, to
+ * stack them. The quote body
+ * accepts a node, so a caller can hand it motion text (`<MotionReveal/>`) that
+ * spells the line out on scroll. Entirely
+ * token-backed utilities — no family CSS rules. Server component — no state.
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+import type { ReactNode } from "react";
+
+export type TestimonialQuote = {
+  /**
+   * The pull-quote itself. A string for plain copy; pass an element instead
+   * (e.g. `<MotionReveal text="…" />`) when the quote should spell itself out
+   * as it rides up the page. The primitive renders it as-is, so any inline
+   * motion text is the caller's choice, not the wall's.
+   */
+  quote: ReactNode;
+  /** Attributed name — initials are derived for the avatar disc. */
+  name: string;
+  /** Role line — "Systematic PM". */
+  role: string;
+  /** Organization — pairs with `lockup` as `{org} × {lockup}`. */
+  org: string;
+  /**
+   * Optional public site for the org. When present the org name renders as a
+   * link — for a named customer whose site is public, never for a quote whose
+   * attribution is only a role.
+   */
+  href?: string;
+};
+
+export type TestimonialWallProps = {
+  quotes: TestimonialQuote[];
+  /**
+   * Columns at the widest breakpoint (collapses to one below 820px). Default
+   * 3; use 2 for a wall holding two voices, so the row fills instead of
+   * leaving an empty third cell, or 1 to stack them — a band where each voice
+   * should be read on its own, at its own width, rather than compared.
+   */
+  columns?: 1 | 2 | 3;
+  /** Product half of the `{org} × {product}` lockup; omit to drop it. */
+  lockup?: string;
+  /** Org names for the quiet strip under the wall; omit to drop the strip. */
+  orgs?: string[];
+  /** Micro-caps label opening the org strip. */
+  orgsLabel?: string;
+  /** Accessible name for the org strip — "Illustrative organizations". */
+  orgsAriaLabel?: string;
+  className?: string;
+};
+
+const initials = (name: string) =>
+  name
+    .split(/[.\s]+/)
+    .filter(Boolean)
+    .map((p) => p[0])
+    .join("");
+
+export function TestimonialWall({
+  quotes,
+  columns = 3,
+  lockup,
+  orgs,
+  orgsLabel = "trusted by",
+  orgsAriaLabel = "Organizations",
+  className,
+}: TestimonialWallProps) {
+  return (
+    <div className={className}>
+      <div
+        className={`grid gap-[0.9rem] max-[820px]:grid-cols-1 ${
+          columns === 1 ? "grid-cols-1" : columns === 2 ? "grid-cols-2" : "grid-cols-3"
+        }`}
+      >
+        {quotes.map((q) => (
+          <figure
+            key={q.name}
+            className="m-0 flex flex-col justify-between gap-[1.1rem] rounded-none border border-hair bg-surface p-[1.3rem]"
+          >
+            <blockquote className="m-0 font-display font-normal text-[1.02rem] leading-[1.4] text-ink">
+              {q.quote}
+            </blockquote>
+            <figcaption className="flex items-center gap-[0.7rem]">
+              <span
+                className="flex size-[34px] flex-shrink-0 items-center justify-center rounded-none bg-accent-weak font-mono text-[0.62rem] tracking-[0.04em] text-accent"
+                aria-hidden="true"
+              >
+                {initials(q.name)}
+              </span>
+              <span className="flex min-w-0 flex-col">
+                <span className="font-mono text-[0.76rem] text-ink">{q.name}</span>
+                <span className="font-mono text-[0.62rem] text-ink-mute">
+                  {q.role} ·{" "}
+                  {q.href ? (
+                    <a
+                      className="underline-offset-[3px] hover:text-ink hover:underline"
+                      href={q.href}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                    >
+                      {q.org}
+                    </a>
+                  ) : (
+                    q.org
+                  )}
+                  {lockup ? <span className="text-accent"> × {lockup}</span> : null}
+                </span>
+              </span>
+            </figcaption>
+          </figure>
+        ))}
+      </div>
+
+      {orgs && orgs.length > 0 ? (
+        <div
+          className="mt-[1.4rem] flex flex-wrap items-center gap-x-[1.4rem] gap-y-[0.5rem] border-t border-hair pt-[1.1rem] font-mono text-[0.74rem] text-ink-soft"
+          aria-label={orgsAriaLabel}
+        >
+          <span className="text-[0.58rem] uppercase tracking-[0.1em] text-ink-mute">
+            {orgsLabel}
+          </span>
+          {orgs.map((o) => (
+            <span key={o}>{o}</span>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/data-layout/index.ts

@@ -0,0 +1,19 @@
+// data-layout family barrel (#1450) — re-exported from src/index.ts by the
+// wire stage. One css sheet for the family: styles/data-layout.css. CardRail is
+// utilities-only.
+export { Odometer, OdometerStrip, type OdometerStat } from "./Odometer";
+export { DotMatrixStat, type DotMatrixStatProps } from "./DotMatrixStat";
+export { BentoGrid, BentoCell, type BentoSpan } from "./BentoGrid";
+export { ProductFrame, type ProductFrameProps } from "./ProductFrame";
+export { CardRail, type CardRailProps } from "./CardRail";
+export { MediaFrame, type MediaFrameProps } from "./MediaFrame";
+export { FeatureCell, type FeatureCellProps } from "./FeatureCell";
+export { TestimonialWall, type TestimonialQuote, type TestimonialWallProps } from "./TestimonialWall";
+export { ModuleGrid, type ModuleGridItem, type ModuleGridProps } from "./ModuleGrid";
+export {
+  treemapAreas,
+  treemapAreasConstrained,
+  treemapAnchored,
+  type TreemapRect,
+  type TreemapMins,
+} from "./treemap";