@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/typography/MotionReveal.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import { m, useScroll, useTransform } from "motion/react";
+import type { MotionValue } from "motion/react";
+import { useRef } from "react";
+import { useMotionSafe } from "../../motion/primitives";
+
+/**
+ * MotionReveal — the mid-page motion text, sibling to <WordReveal/>.
+ *
+ * <WordReveal/> is the full-drama hero claim: a 150vh pinned track whose words
+ * fill from blur on the ride up, deliberately reserved for one claim per page
+ * (its own docblock says so, and a second one on a page stacks 150vh of dead
+ * scroll behind the footer). That grammar is wrong for a supporting claim —
+ * the testimonial wall, a quoted voice — where the copy must read the moment
+ * it is on screen and the page must keep moving.
+ *
+ * So this is the same idea at band scale, and NOT pinned: the words deepen in
+ * order from muted to full ink as the line rides up the viewport, and they are
+ * legible from the first frame — pure colour interpolation, no opacity or blur,
+ * so the reveal steers the eye and never gates the message. The finished state
+ * is reached by the time the line is mid-viewport; the track adds no height.
+ * This is the treatment the reference gallery documents for "supporting claims
+ * mid-page where legibility must be unconditional".
+ *
+ * Motion is scroll-linked per word; under `prefers-reduced-motion` — or with no
+ * JS at all — the text renders in full ink immediately. `.word` comes from
+ * styles/word-reveal.css and already carries both fallbacks:
+ *
+ *   @media (prefers-reduced-motion: reduce) { .word { opacity/transform/filter: … } }
+ *   html.no-js .word { … }
+ *
+ * Wiring (in the consuming app): the word-reveal sheet must be imported, which
+ * <WordReveal/> already requires —
+ *   globals.css  @import "@digithings-ai/ui/styles/word-reveal.css";
+ */
+const REVEAL_END = 0.86;
+const WORD_SPAN = 0.2;
+
+function wordWindow(index: number, total: number): [number, number] {
+  const start = (index / Math.max(1, total - 1)) * Math.max(0, REVEAL_END - WORD_SPAN);
+  return [start, start + WORD_SPAN];
+}
+
+function RevealWord({
+  index,
+  total,
+  text,
+  progress,
+}: {
+  index: number;
+  total: number;
+  text: string;
+  progress: MotionValue<number>;
+}) {
+  const [start, end] = wordWindow(index, total);
+  const mix = useTransform(progress, [start, end], [0, 100]);
+  const color = useTransform(
+    mix,
+    (v) => `color-mix(in srgb, var(--ink) ${v.toFixed(1)}%, var(--ink-mute))`,
+  );
+
+  return (
+    <m.span className="word" style={{ color }}>
+      {text}
+    </m.span>
+  );
+}
+
+export type MotionRevealProps = {
+  /** The copy to spell out — split on whitespace; each word deepens in turn. */
+  text: string;
+  /** Extra classes on the inline wrapper. */
+  className?: string;
+};
+
+export function MotionReveal({ text, className }: MotionRevealProps) {
+  const trackRef = useRef<HTMLSpanElement | null>(null);
+  // useMotionSafe(), not a raw reduced-motion read: SSR cannot know the media
+  // query, so the server pass must always take the animated branch and the
+  // real preference resolves one effect-tick later — the same hydration-safe
+  // pattern <WordReveal/> uses (#2244).
+  const safe = useMotionSafe();
+  // The line's own ride: 0 when its top crosses 92% of the viewport, 1 by the
+  // time its bottom reaches 55% — i.e. fully spelled out around mid-viewport,
+  // and the element is never pinned, so the band keeps its natural height.
+  const { scrollYProgress } = useScroll({
+    target: trackRef,
+    offset: ["start 0.92", "end 0.55"],
+  });
+  const words = text.split(" ");
+
+  return (
+    <m.span ref={trackRef} className={className}>
+      {safe
+        ? words.map((word, idx) => (
+            <RevealWord
+              key={`${word}-${idx}`}
+              index={idx}
+              total={words.length}
+              text={word}
+              progress={scrollYProgress}
+            />
+          ))
+        : text}
+    </m.span>
+  );
+}

package/src/components/typography/TypewriterReveal.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+import { m, useMotionValueEvent, useScroll } from "motion/react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useMotionSafe } from "../../motion/primitives";
+
+/**
+ * TypewriterReveal — the copy types itself out as the line rides up the page.
+ *
+ * The sibling of <WordReveal/> and <MotionReveal/>, and the third answer to the
+ * same question: how does long copy earn attention on scroll?
+ *
+ *   <WordReveal/>     pinned, 150vh of track, words fill from blur. One per page.
+ *   <MotionReveal/>   unpinned, words deepen in colour in order. Supporting claims.
+ *   <TypewriterReveal/> unpinned, characters appear in order, with a caret.
+ *
+ * Not pinned, and that is deliberate: a typed quote that held the viewport for a
+ * screen and a half would be a performance the reader has to wait out. This one
+ * types as the line travels, so the page never stops, and it finishes around
+ * mid-viewport.
+ *
+ * **Layout.** Revealing characters would normally reflow the paragraph on every
+ * tick, so the full text is laid out once in a hidden ghost and the typed copy is
+ * drawn over it. The box is therefore the size of the finished quote from the
+ * first frame — nothing on the page below ever moves.
+ *
+ * **Accessibility.** The visual layers are `aria-hidden`; the full text is
+ * exposed once, in a visually-hidden node. So a screen reader reads the finished
+ * quote, never a partial one, and the caret is decorative throughout.
+ *
+ * **Fallbacks.** Under `prefers-reduced-motion` — or with no JS — the component
+ * renders the whole line, untyped and without a caret. `useMotionSafe()`, not a
+ * raw media-query read: SSR cannot know the preference, so the server pass always
+ * takes the plain branch and the real one resolves a tick later (the same
+ * hydration-safe pattern as its siblings, #2244).
+ *
+ * Wiring (in the consuming app): the word-reveal sheet carries this component's
+ * few rules too —
+ *   globals.css  @import "@digithings-ai/ui/styles/word-reveal.css";
+ */
+
+/** Where in the element's travel the typing runs. */
+const REVEAL_START = 0.04;
+const REVEAL_END = 0.72;
+
+export type TypewriterRevealProps = {
+  /** The copy to type out. */
+  text: string;
+  /** Extra classes on the inline wrapper. */
+  className?: string;
+};
+
+export function TypewriterReveal({ text, className }: TypewriterRevealProps) {
+  const trackRef = useRef<HTMLSpanElement | null>(null);
+  const safe = useMotionSafe();
+  // 0 when the line's top reaches the bottom edge of the viewport, 1 once its
+  // bottom has climbed to the middle. Starting at the element's first pixel of
+  // visibility is what keeps the collapse from the full copy to an empty one
+  // off-screen, so a reader never sees the text vanish and retype.
+  const { scrollYProgress } = useScroll({
+    target: trackRef,
+    offset: ["start end", "end center"],
+  });
+  // The server — and the first client frame — render the whole line, so there is
+  // never a blank quote in the HTML and nothing to hydrate-mismatch against.
+  const [shown, setShown] = useState(text.length);
+
+  const advance = useCallback(
+    (progress: number) => {
+      const travel = Math.max(0.0001, REVEAL_END - REVEAL_START);
+      const t = Math.min(1, Math.max(0, (progress - REVEAL_START) / travel));
+      setShown(Math.round(t * text.length));
+    },
+    [text.length],
+  );
+
+  // Read the current position once on mount as well as on every change: a line
+  // that is already past its reveal window when the page loads should be whole,
+  // not waiting for a scroll that may never come.
+  useEffect(() => {
+    advance(scrollYProgress.get());
+  }, [advance, scrollYProgress]);
+
+  useMotionValueEvent(scrollYProgress, "change", advance);
+
+  const typed = safe ? text.slice(0, shown) : text;
+  const typing = safe && shown < text.length;
+
+  return (
+    <m.span ref={trackRef} className={`tw${className ? ` ${className}` : ""}`}>
+      <span className="tw-ghost" aria-hidden="true">
+        {text}
+      </span>
+      <span className="tw-live" aria-hidden="true">
+        {typed}
+        {typing ? <span className="tw-caret" /> : null}
+      </span>
+      <span className="tw-sr">{text}</span>
+    </m.span>
+  );
+}

package/src/components/typography/WordReveal.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { m, useScroll, useTransform } from "motion/react";
+import type { MotionValue } from "motion/react";
+import { useRef } from "react";
+import { useMotionSafe } from "../../motion/primitives";
+
+/**
+ * WordReveal — the full-drama pinned-blur reveal promoted from the design
+ * reference (typography/word-reveal). Reserved for the one hero claim per page:
+ * words fill from blur as the line rides up the viewport — the reveal starts
+ * as soon as the line enters and completes by the time it reaches
+ * mid-viewport, where a short sticky hold gives the finished claim one beat
+ * before the page flows on. It can never scroll away half-read. Under
+ * `prefers-reduced-motion` — or with no JS at all (`html.no-js`) — the final
+ * text renders statically, fully legible, with no empty scroll gap.
+ *
+ * The pinned-track / display-line / `.word` mechanics live in
+ * styles/word-reveal.css (kept CSS per the migrate-vs-leave rule: the 150vh
+ * track, the sticky pin, and the reduced-motion + no-JS fallbacks). This
+ * component carries the scroll→opacity/blur mapping and the token-backed
+ * kicker/title utilities.
+ *
+ * Client component — scroll progress + per-word transforms. Motion via `m`
+ * under a MotionProvider (LazyMotion). Wiring (in the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/word-reveal.css";
+ *                 @source "<path-to>/packages/ui/src/components/typography";
+ */
+
+/**
+ * Timing against ["start end", "start start"] scroll progress (0 = the track's
+ * top enters the viewport bottom, 1 = it reaches the viewport top, which is
+ * the instant the sticky pin engages with the line at mid-viewport):
+ * the line's own top clears the viewport bottom around ~0.4, so words start
+ * filling the moment the line is visible (REVEAL_START) and every word is
+ * fully legible by REVEAL_END ≈ the mid-viewport pin. The pinned remainder of
+ * the track (track height − 100vh) is a short hold, not reveal time.
+ */
+const REVEAL_START = 0.4;
+const REVEAL_END = 0.98;
+const WORD_SPAN = 0.18;
+
+function wordWindow(index: number, total: number): [number, number] {
+  const start =
+    REVEAL_START +
+    (index / Math.max(1, total - 1)) * (REVEAL_END - WORD_SPAN - REVEAL_START);
+  return [start, start + WORD_SPAN];
+}
+
+function RevealWord({
+  index,
+  total,
+  text,
+  progress,
+}: {
+  index: number;
+  total: number;
+  text: string;
+  progress: MotionValue<number>;
+}) {
+  const [start, end] = wordWindow(index, total);
+  // Function transforms only: a numeric range-map on opacity gets compiled by
+  // Motion into a native view()-timeline animation, whose enter/exit progress
+  // cannot express this pinned-track mapping (it rises then holds). Arbitrary
+  // functions are uncompilable, which pins every value to the JS scroll path.
+  const wordProgress = (p: number) => Math.min(1, Math.max(0, (p - start) / (end - start)));
+  const opacity = useTransform(progress, (p) => 0.08 + wordProgress(p) * 0.92);
+  const y = useTransform(progress, (p) => (1 - wordProgress(p)) * 7);
+  const filter = useTransform(progress, (p) => `blur(${(1 - wordProgress(p)) * 10}px)`);
+
+  return (
+    <m.span className="word" style={{ opacity, y, filter }}>
+      {text}
+    </m.span>
+  );
+}
+
+export type WordRevealProps = {
+  /** The claim to reveal — split on whitespace; each word animates in turn. */
+  text: string;
+  /** Optional mono kicker above the line. */
+  kicker?: string;
+  /** Optional serif title above the line. */
+  title?: string;
+  /** Anchor id on the block wrapper. */
+  id?: string;
+  /** Extra classes on the block wrapper. */
+  className?: string;
+};
+
+export function WordReveal({ text, kicker, title, id, className }: WordRevealProps) {
+  const trackRef = useRef<HTMLDivElement | null>(null);
+  // useMotionSafe(), not raw useReducedMotion(): SSR can't know the real media
+  // query, and motion/react's hook seeds its `useState` from a synchronously-
+  // read matchMedia value on the client's very first render -- so a real
+  // reduced-motion user's first hydration render (`reduced=true`, the `text`
+  // branch below) structurally disagreed with SSR's motion-safe default
+  // (`reduced=false`/null, the words.map() branch), throwing a hydration
+  // mismatch (#2244). useMotionSafe() reports motion-safe on that first
+  // render on both server and client, then resolves the real preference one
+  // effect-tick later -- the same hydration-safe pattern <Reveal/> already uses.
+  const reduced = !useMotionSafe();
+  // 0 = track top enters the viewport bottom; 1 = track top reaches the
+  // viewport top (the sticky pin engages, line at mid-viewport). The reveal
+  // maps onto the line's entry ride — see the timing note above.
+  const { scrollYProgress } = useScroll({
+    target: trackRef,
+    offset: ["start end", "start start"],
+  });
+  const words = text.split(" ");
+
+  return (
+    <div id={id} className={className}>
+      {kicker ? (
+        <p className="font-mono text-[0.8rem] tracking-[0.02em] text-accent">{kicker}</p>
+      ) : null}
+      {title ? (
+        <h2 className="mt-[0.4rem] font-display text-[clamp(1.5rem,3vw,2.3rem)] font-normal leading-[1.12] tracking-[-0.01em] text-ink">
+          {title}
+        </h2>
+      ) : null}
+      <div className={`wr-track${reduced ? " is-static" : ""}`} ref={trackRef}>
+        <div className="wr-sticky">
+          <p className="word-line" aria-label={text}>
+            <span aria-hidden="true">
+              {reduced
+                ? text
+                : words.map((word, idx) => (
+                    <RevealWord
+                      key={`${word}-${idx}`}
+                      index={idx}
+                      total={words.length}
+                      text={word}
+                      progress={scrollYProgress}
+                    />
+                  ))}
+            </span>
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}