@digithings-ai/ui 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,368 @@
+/**
+ * Squarified treemap partition — the packing behind `ModuleGrid`.
+ *
+ * Splits a W×H box into one rectangle per weight, in order, with areas ∝
+ * weights and a worst-aspect-first row choice so tiles stay squarish as they
+ * reflow. Pure in `(weights, W, H)`, so the same focus always draws the same
+ * mosaic. Framework-free so it can be unit-tested without a DOM.
+ *
+ * Focusing a tile re-solves the whole partition, so tiles change neighbours
+ * freely instead of stretching their row-mates: proportions live in the
+ * weights, not in row membership. The render insets each rect by half of the
+ * gutter.
+ */
+export interface TreemapRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export function treemapAreas(weights: number[], W: number, H: number): TreemapRect[] {
+  const total = weights.reduce((acc, w) => acc + w, 0) || 1;
+  const scale = (W * H) / total;
+  const items = weights.map((w, i) => ({ area: w * scale, i }));
+  const out: TreemapRect[] = new Array(weights.length);
+  const rowArea = (row: { area: number }[]) => row.reduce((acc, r) => acc + r.area, 0);
+  const worst = (row: { area: number }[], side: number) => {
+    const s = rowArea(row);
+    const hi = Math.max(...row.map((r) => r.area));
+    const lo = Math.min(...row.map((r) => r.area));
+    return Math.max((side * side * hi) / (s * s) || 0, (s * s) / (side * side * lo) || 0);
+  };
+  const layRow = (
+    row: { area: number; i: number }[],
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+    horizontal: boolean,
+  ) => {
+    const s = rowArea(row);
+    if (horizontal) {
+      const rh = s / w;
+      let rx = x;
+      row.forEach((r) => {
+        const rw = r.area / rh;
+        out[r.i] = { x: rx, y, w: rw, h: rh };
+        rx += rw;
+      });
+      return { x, y: y + rh, w, h: h - rh };
+    }
+    const cw = s / h;
+    let ry = y;
+    row.forEach((r) => {
+      const rh = r.area / cw;
+      out[r.i] = { x, y: ry, w: cw, h: rh };
+      ry += rh;
+    });
+    return { x: x + cw, y, w: w - cw, h };
+  };
+  let x = 0;
+  let y = 0;
+  let w = W;
+  let h = H;
+  let row: { area: number; i: number }[] = [];
+  const rest = [...items];
+  while (rest.length > 0) {
+    /* The row spans the SHORTEST side of the remaining box: a wide remainder
+       packs a vertical column (full height), a tall remainder a horizontal
+       strip (full width). Spanning the longest side instead reads better in
+       prose but draws full-width slivers for every light tile past the first
+       row (measured: eleven tiles, ten of them 1216px-wide slivers) — the
+       `worst` metric above only agrees with the layout when the two share
+       this orientation. */
+    const horizontal = w < h;
+    const side = Math.min(w, h);
+    const next = rest[0];
+    if (row.length === 0 || worst([...row, next], side) <= worst(row, side)) {
+      row.push(next);
+      rest.shift();
+    } else {
+      ({ x, y, w, h } = layRow(row, x, y, w, h, horizontal));
+      row = [];
+    }
+  }
+  if (row.length > 0) layRow(row, x, y, w, h, w < h);
+  return out;
+}
+
+/**
+ * Anchor-focused solve (v18): the focused tile grows in place while the rest
+ * reflow around it.
+ *
+ * The owner found the full re-solve hard to follow — the open module jumped
+ * to a new spot every step. So the rest layout (`rest`, solved with
+ * unfocused weights) is the stable map: the focused tile keeps its rest
+ * top-left (clamped into the box when its grown size would overflow) and the
+ * non-focused tiles repack into the four regions around it (top / bottom /
+ * left / right strips), each region filled by its own constrained solve.
+ * Tiles are assigned to the region holding their rest centre, so a tile stays
+ * near its resting zone; within a region, weight ratios stay exact. Global
+ * cross-region proportions are approximate rather than exact — followability
+ * won that trade. Pure in its inputs; covered in `treemap.test.ts`.
+ */
+export interface TreemapMins {
+  minW: number;
+  minH: number;
+}
+
+/**
+ * Constrained solve: every tile's weight first covers its minimum area
+ * outright (margin 1.5x for aspect slop), then one pure partition, then a
+ * short gentle polish for packing-geometry residuals.
+ *
+ * Deliberately NOT an iterative weight chase: when several tiles violate at
+ * once, joint multiplicative lifts freeze their ratios and can starve a
+ * small tile forever (measured live: a roadmap tile ended 101px wide against
+ * a 184px minimum while the loop insisted it was "lifting" it). Direct
+ * floors cannot freeze — areas always match weights exactly — so the minimums
+ * hold jointly whenever the box can fit them. Past that (a box smaller than
+ * every minimum combined) it degrades best-effort: still a full partition,
+ * still finite, still no overlaps.
+ *
+ * Squarified packing assumes descending weights, but boosts, floors and
+ * measured top-ups can invert the LOC order (a floored roadmap can outweigh
+ * digiquant), which degrades aspect quality into slivers — measured live as
+ * 107px-wide resting tiles with clipped titles beside a 776px focused one.
+ * So every solve sorts descending first and maps rects back; packing quality
+ * never depends on focus luck. The sort is stable, so equal weights keep
+ * their LOC order.
+ *
+ * The landing mosaic uses this to guarantee the owner's floor: every tile
+ * wide enough for its title + version with padding, every focused tile large
+ * enough for its detail. Minimums are in cell space (the render insets the
+ * gutter afterwards), so callers inflate them by the gutter.
+ */
+export function treemapAreasConstrained(
+  weights: number[],
+  W: number,
+  H: number,
+  mins: TreemapMins[],
+  maxIters = 3,
+): TreemapRect[] {
+  const total = weights.reduce((acc, w) => acc + w, 0) || 1;
+  const boxArea = Math.max(W * H, 1);
+  const order = weights.map((_, i) => i).sort((a, b) => weights[b] - weights[a]);
+  const sorted = order.map((i) => weights[i]);
+  const sortedMins = order.map((i) => mins[i]);
+  const floored = sorted.map((w, k) => {
+    const m = sortedMins[k];
+    if (!m) return w;
+    return Math.max(w, ((m.minW * m.minH * 1.5) / boxArea) * total);
+  });
+  const lifted = [...floored];
+  const solveAll = () => treemapAreas(lifted, W, H);
+  let sortedRects = solveAll();
+  for (let k = 0; k < maxIters; k++) {
+    let clean = true;
+    for (let s = 0; s < sortedRects.length; s++) {
+      const m = sortedMins[s];
+      if (!m) continue;
+      const r = sortedRects[s];
+      if (r.w < m.minW || r.h < m.minH) {
+        clean = false;
+        lifted[s] *= 1.3;
+      }
+    }
+    if (clean) break;
+    sortedRects = solveAll();
+  }
+  const out: TreemapRect[] = new Array(weights.length);
+  sortedRects.forEach((r, s) => {
+    out[order[s]] = r;
+  });
+  return out;
+}
+
+/**
+ * Anchor-focused solve: the focused tile keeps its rest top-left and grows
+ * to `focusedSize` (clamped into the box); every other tile repacks into the
+ * strips around it. See the `TreemapMins` docblock above for the why.
+ *
+ * Tiles go to the strip holding their rest centre (nearest strip wins ties
+ * and covers centres swallowed by the grown focused rect); each strip is
+ * filled by its own constrained solve, so weight ratios hold within a strip.
+ * A strip only receives a tile when it is at least that tile's minimum, so a
+ * focused card cannot leave a neighbour a sliver with a clipped title. A
+ * strip nothing can use is folded back into the focused card. When the
+ * requested focus size still starves a neighbour, the focus shrinks toward
+ * its own minimum until the others fit, and only then gives up (best-effort,
+ * still a full partition, never overlaps, never NaNs).
+ */
+export function treemapAnchored(
+  weights: number[],
+  W: number,
+  H: number,
+  mins: TreemapMins[],
+  rest: TreemapRect[],
+  focusIndex: number,
+  focusedSize: { w: number; h: number },
+): TreemapRect[] {
+  const anchor = rest[focusIndex];
+  if (!anchor) return treemapAreasConstrained(weights, W, H, mins);
+  const focusMin = mins[focusIndex] ?? { minW: 0, minH: 0 };
+  const floorW = Math.min(Math.max(focusMin.minW, 0), W);
+  const floorH = Math.min(Math.max(focusMin.minH, 0), H);
+  const targetW = Math.min(Math.max(focusedSize.w, floorW), W);
+  const targetH = Math.min(Math.max(focusedSize.h, floorH), H);
+
+  interface Strip {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    side: "top" | "bottom" | "left" | "right";
+  }
+
+  const fits = (s: Strip, i: number) => {
+    const m = mins[i];
+    if (!m) return true;
+    return s.w + 0.5 >= m.minW && s.h + 0.5 >= m.minH;
+  };
+
+  const centre = (i: number) => {
+    const r = rest[i];
+    return { x: r.x + r.w / 2, y: r.y + r.h / 2 };
+  };
+  const contains = (s: Strip, p: { x: number; y: number }) =>
+    p.x >= s.x && p.x <= s.x + s.w && p.y >= s.y && p.y <= s.y + s.h;
+  const distance = (s: Strip, p: { x: number; y: number }) => {
+    const dx = Math.max(s.x - p.x, 0, p.x - (s.x + s.w));
+    const dy = Math.max(s.y - p.y, 0, p.y - (s.y + s.h));
+    return dx * dx + dy * dy;
+  };
+
+  const pack = (wantW: number, wantH: number) => {
+    let fw = Math.min(Math.max(wantW, floorW), W);
+    let fh = Math.min(Math.max(wantH, floorH), H);
+    let fx = Math.min(Math.max(anchor.x, 0), Math.max(W - fw, 0));
+    let fy = Math.min(Math.max(anchor.y, 0), Math.max(H - fh, 0));
+    const others = weights.map((_, i) => i).filter((i) => i !== focusIndex);
+
+    const build = (): Strip[] =>
+      (
+        [
+          { x: 0, y: 0, w: W, h: fy, side: "top" },
+          { x: 0, y: fy + fh, w: W, h: H - fy - fh, side: "bottom" },
+          { x: 0, y: fy, w: fx, h: fh, side: "left" },
+          { x: fx + fw, y: fy, w: W - fx - fw, h: fh, side: "right" },
+        ] as Strip[]
+      ).filter((s) => s.w > 4 && s.h > 4);
+
+    let strips = build();
+    for (let guard = 0; guard < 4 && strips.length > 0; guard++) {
+      const claimed = new Set<number>();
+      const buckets = strips.map(() => [] as number[]);
+      others.forEach((i) => {
+        let best = -1;
+        let bestScore: number | null = null;
+        strips.forEach((s, k) => {
+          if (!fits(s, i)) return;
+          const p = centre(i);
+          const score = contains(s, p) ? -1 : distance(s, p);
+          if (bestScore === null || score < bestScore) {
+            bestScore = score;
+            best = k;
+          }
+        });
+        if (best >= 0) {
+          buckets[best].push(i);
+          claimed.add(i);
+        }
+      });
+      const empty = strips.filter((_, k) => buckets[k].length === 0);
+      if (empty.length === 0 || claimed.size < others.length) break;
+      const sides = new Set(empty.map((s) => s.side));
+      if (sides.has("top")) {
+        fh += fy;
+        fy = 0;
+      }
+      if (sides.has("bottom")) fh = H - fy;
+      if (sides.has("left")) {
+        fw += fx;
+        fx = 0;
+      }
+      if (sides.has("right")) fw = W - fx;
+      fw = Math.min(Math.max(fw, floorW), W - fx);
+      fh = Math.min(Math.max(fh, floorH), H - fy);
+      strips = build();
+    }
+
+    const out: TreemapRect[] = new Array(weights.length);
+    out[focusIndex] = { x: fx, y: fy, w: fw, h: fh };
+    if (strips.length === 0) {
+      others.forEach((i) => {
+        out[i] = { ...out[focusIndex] };
+      });
+      return { rects: out, ok: others.length === 0 };
+    }
+
+    const buckets = strips.map(() => [] as number[]);
+    let ok = true;
+    others.forEach((i) => {
+      const p = centre(i);
+      let best = 0;
+      let bestScore: number | null = null;
+      let bestFit = 0;
+      let bestFitScore: number | null = null;
+      strips.forEach((s, k) => {
+        const score = contains(s, p) ? -1 : distance(s, p);
+        if (bestScore === null || score < bestScore) {
+          bestScore = score;
+          best = k;
+        }
+        if (!fits(s, i)) return;
+        if (bestFitScore === null || score < bestFitScore) {
+          bestFitScore = score;
+          bestFit = k;
+        }
+      });
+      if (bestFitScore === null) ok = false;
+      buckets[bestFitScore === null ? best : bestFit].push(i);
+    });
+
+    strips.forEach((s, k) => {
+      const members = buckets[k];
+      if (members.length === 0) return;
+      if (members.length === 1) {
+        const only = members[0];
+        out[only] = { x: s.x, y: s.y, w: s.w, h: s.h };
+        if (!fits(s, only)) ok = false;
+        return;
+      }
+      const sub = treemapAreasConstrained(
+        members.map((i) => weights[i]),
+        s.w,
+        s.h,
+        members.map((i) => mins[i]),
+      );
+      members.forEach((id, j) => {
+        const r = sub[j];
+        const m = mins[id];
+        out[id] = { x: s.x + r.x, y: s.y + r.y, w: r.w, h: r.h };
+        if (m && (r.w + 0.5 < m.minW || r.h + 0.5 < m.minH)) ok = false;
+      });
+    });
+
+    others.forEach((i) => {
+      out[i] ??= { ...out[focusIndex] };
+    });
+    return { rects: out, ok };
+  };
+
+  let best = pack(floorW, floorH);
+  let lo = 0;
+  let hi = 1;
+  for (let i = 0; i < 12; i++) {
+    const mid = (lo + hi) / 2;
+    const attempt = pack(floorW + (targetW - floorW) * mid, floorH + (targetH - floorH) * mid);
+    if (attempt.ok) {
+      best = attempt;
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return best.rects;
+}

package/src/components/deck/DeckStack.tsx

@@ -0,0 +1,243 @@
+"use client";
+
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  memo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { m, useMotionValueEvent, useScroll, useTransform } from "motion/react";
+import type { MotionStyle, MotionValue } from "motion/react";
+import { useMotionSafe } from "../../motion/primitives";
+
+/**
+ * DeckStack / DeckCard — the sticky stacking card deck promoted from the
+ * design reference (data/card-deck; the cavemen.dev pattern, #1450). Cards
+ * live in normal document flow as DIRECT children of one shared `.deck-slots`
+ * grid; on wide screens each card pins at a cascaded top offset
+ * (`--deck-top` + `--deck-peek` × `--stack-index`) and the next card slides
+ * up over it, so every buried card keeps a visible top edge — the next
+ * opaque card's coverage IS the seam (1px hairline, no drop shadow, no clip
+ * box, nothing ever cut off). Content is server-rendered, fully laid out,
+ * and readable top-to-bottom with no JS; the only JS enhancements are the
+ * recede transform (a slight scale-down while a card is covered) and the
+ * optional rail's active state. Below 901px the CSS drops sticky entirely
+ * and the cards simply appear in sequence. The deck knows nothing about
+ * card content.
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/deck.css";
+ *                 @source "<path-to>/packages/ui/src/components/deck";
+ */
+
+const WIDE_QUERY = "(min-width: 901px)";
+
+/* useSyncExternalStore keeps the media-query state hydration-safe: the server
+   snapshot is `false`, so wide-only inline transforms never appear in server
+   markup and the hydrated tree matches exactly. */
+function subscribeWide(callback: () => void) {
+  const mq = window.matchMedia(WIDE_QUERY);
+  mq.addEventListener("change", callback);
+  return () => mq.removeEventListener("change", callback);
+}
+const getWideSnapshot = () => window.matchMedia(WIDE_QUERY).matches;
+const getWideServerSnapshot = () => false;
+
+export type DeckCardProps = {
+  /** Card content — the deck stays content-agnostic. */
+  children: ReactNode;
+  /** Extra classes on the sticky card element — the app-dress hook. Both
+   *  unlayered app CSS and call-site token utilities outrank the card's
+   *  `@layer components` surface defaults in styles/deck.css. */
+  className?: string;
+  /** Injected by the parent DeckStack — never set manually. */
+  index?: number;
+  /** Injected by the parent DeckStack — never set manually. */
+  total?: number;
+  /** Injected by the parent DeckStack — never set manually. */
+  animate?: boolean;
+  /** Injected by the parent DeckStack — never set manually. */
+  progress?: MotionValue<number>;
+};
+
+type AnimatedDeckCardProps = {
+  children: ReactNode;
+  className?: string;
+  index: number;
+  total: number;
+  animate: boolean;
+  progress: MotionValue<number>;
+};
+
+function cardClass(className?: string): string {
+  return className ? `deck-card ${className}` : "deck-card";
+}
+
+/**
+ * One sticky card. While the next card's slot scrolls through, this card is
+ * being covered: it recedes slightly (scale only — a brightness dim read as
+ * grime on light-theme paper cards; user ruling #1450) so the stack reads
+ * as depth. Function transforms only — numeric range-maps get compiled to a
+ * native view() timeline that cannot express this mapping (see the word
+ * reveal components for the same pitfall).
+ */
+const AnimatedDeckCard = memo(function AnimatedDeckCard({
+  children,
+  className,
+  index,
+  total,
+  animate,
+  progress,
+}: AnimatedDeckCardProps) {
+  const cover = (p: number) => {
+    if (!animate || index >= total - 1) return 0;
+    const start = (index + 1) / total - 1 / total;
+    return Math.min(1, Math.max(0, (p - start) * total));
+  };
+  const scale = useTransform(progress, (p) => 1 - cover(p) * 0.05);
+
+  return (
+    <m.div
+      role="listitem"
+      className={cardClass(className)}
+      style={{ "--stack-index": index, scale, transformOrigin: "top center" } as MotionStyle}
+    >
+      {children}
+    </m.div>
+  );
+});
+
+export function DeckCard({ children, className, index, total, animate, progress }: DeckCardProps) {
+  if (progress === undefined || index === undefined || total === undefined) {
+    // Rendered outside a DeckStack: a plain (still sticky-capable) card with
+    // no recede transform.
+    return (
+      <div
+        role="listitem"
+        className={cardClass(className)}
+        style={{ "--stack-index": index ?? 0 } as CSSProperties}
+      >
+        {children}
+      </div>
+    );
+  }
+  return (
+    <AnimatedDeckCard
+      className={className}
+      index={index}
+      total={total}
+      animate={animate ?? false}
+      progress={progress}
+    >
+      {children}
+    </AnimatedDeckCard>
+  );
+}
+
+export type DeckStackProps = {
+  /** DeckCard children. They MUST render as the deck's direct children so
+   *  the sticky mechanics hold — a sticky element can never leave its
+   *  containing block, so a per-card wrapper would drag its card away as the
+   *  wrapper scrolls past (see styles/deck.css). */
+  children: ReactNode;
+  /** Accessible name for the card list. */
+  ariaLabel?: string;
+  /** Optional progress rail: one mono label per card, pinned beside the
+   *  stack on wide screens (the CSS hides it below 901px). Omit to render
+   *  the slots full-width with no side column. */
+  rail?: readonly string[];
+  /** Accessible name for the rail list. */
+  railAriaLabel?: string;
+  /** Extra classes on the outer wrapper (spacing utilities etc.). */
+  className?: string;
+};
+
+/**
+ * The deck container: owns the shared slots grid, scroll progress, and the
+ * optional side rail. Each DeckCard child is cloned with its stack index and
+ * the deck's scroll progress so it can drive its own recede transform.
+ */
+export function DeckStack({
+  children,
+  ariaLabel = "Card stack",
+  rail,
+  railAriaLabel = "Stack progress",
+  className,
+}: DeckStackProps) {
+  const deckRef = useRef<HTMLDivElement | null>(null);
+  // useMotionSafe(), not raw useReducedMotion() -- see WordReveal.tsx's fix
+  // comment (#2244) for the hydration-mismatch mechanism this avoids. `wide`
+  // defaults to false on the first render either way (useSyncExternalStore's
+  // own server-snapshot guard), which already short-circuits `animate` below
+  // to false regardless of `reduced` -- so this specific value never caused
+  // a mismatch in practice, but it's the same unsafe pattern and not worth
+  // leaving as an exception.
+  const reduced = !useMotionSafe();
+  const wide = useSyncExternalStore(subscribeWide, getWideSnapshot, getWideServerSnapshot);
+  const [active, setActive] = useState(0);
+
+  const cards = Children.toArray(children).filter(isValidElement) as ReactElement<DeckCardProps>[];
+  const total = cards.length;
+
+  const { scrollYProgress } = useScroll({
+    target: deckRef,
+    offset: ["start start", "end end"],
+  });
+
+  useMotionValueEvent(scrollYProgress, "change", (progress) => {
+    if (total === 0) return;
+    const idx = Math.min(total - 1, Math.max(0, Math.floor(progress * total)));
+    setActive(idx);
+  });
+
+  const animate = wide && !reduced;
+
+  const slots = (
+    <div className="deck-slots" role="list" aria-label={ariaLabel}>
+      {cards.map((card, index) =>
+        cloneElement(card, { index, total, animate, progress: scrollYProgress }),
+      )}
+    </div>
+  );
+
+  if (!rail || rail.length === 0) {
+    return (
+      <div ref={deckRef} className={className}>
+        {slots}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={deckRef}
+      className={
+        "grid grid-cols-[minmax(0,1fr)_220px] items-start gap-[1.2rem] max-[900px]:grid-cols-1" +
+        (className ? ` ${className}` : "")
+      }
+    >
+      {slots}
+      {/* The column wrapper stops short of the slots' tail runway (deck.css
+          .deck-rail-col) so the pinned rail releases with the last card
+          instead of hanging through the empty scroll-hold. */}
+      <div className="deck-rail-col">
+        <div className="deck-rail-pin">
+          <ol className="deck-rail" aria-label={railAriaLabel}>
+            {rail.map((label, idx) => (
+              <li key={`${label}-${idx}`} className={idx === active ? "on" : undefined}>
+                <span className="dot" />
+                <span className="name">{label}</span>
+              </li>
+            ))}
+          </ol>
+        </div>
+      </div>
+    </div>
+  );
+}