@morphika/webframe 0.1.0

package/components/blocks/TypewriterRichText.tsx

@@ -0,0 +1,464 @@
+"use client";
+
+/**
+ * TypewriterRichText — Single-phase typewriter that preserves rich text formatting.
+ *
+ * Walks the Portable Text AST directly and wraps each character (or word) in a
+ * <span> with a staggered opacity transition. The character spans live INSIDE
+ * the format wrappers (<strong>, <em>, <a>, etc.), so bold/italic/links are
+ * visible throughout the entire animation. No dual render, no swap, no overlay.
+ *
+ * Cursor tracking: The blinking cursor is positioned absolutely and follows the
+ * animation progress via a JS interval that matches the CSS transition timing.
+ * On each tick it reads the bounding rect of the current character span and
+ * repositions the cursor — zero React re-renders, pure DOM manipulation.
+ *
+ * Session 133 — Replaces the dual-phase TypewriterWrapper approach.
+ */
+
+import { useMemo, useRef, useEffect, useState, type CSSProperties } from "react";
+import type { TypewriterConfig } from "../../lib/animation/enter-types";
+import { TYPEWRITER_DEFAULTS } from "../../lib/animation/enter-types";
+import type { PortableTextContent, PortableTextBlock } from "../../lib/sanity/types";
+
+// ── Types ──
+
+interface TypewriterRichTextProps {
+  /** The Portable Text content from the text block */
+  portableText: PortableTextContent | undefined;
+  /** Typewriter configuration (speed, mode) */
+  config?: TypewriterConfig;
+  /** Whether the animation has been triggered (IntersectionObserver) */
+  entered: boolean;
+  /** Animation delay before first character (ms) */
+  startDelay?: number;
+  /** Show blinking cursor (default: true) */
+  showCursor?: boolean;
+  /** CSS class for the outer wrapper (text styling) */
+  className?: string;
+  /** Inline styles for the outer wrapper (text styling) */
+  style?: CSSProperties;
+  /** Callback when animation completes (after cursor pause) */
+  onComplete?: () => void;
+}
+
+// ── Mark resolution ──
+
+/** Resolve markDefs from a block for link marks */
+function getMarkDef(block: PortableTextBlock, markKey: string) {
+  return block.markDefs?.find((d) => d._key === markKey);
+}
+
+/**
+ * Wrap content in the appropriate mark elements.
+ * Handles nested marks by recursively wrapping.
+ */
+function wrapInMarks(
+  content: React.ReactNode,
+  marks: string[] | undefined,
+  block: PortableTextBlock,
+): React.ReactNode {
+  if (!marks || marks.length === 0) return content;
+
+  let result = content;
+  for (const mark of marks) {
+    switch (mark) {
+      case "strong":
+        result = <strong>{result}</strong>;
+        break;
+      case "em":
+        result = <em>{result}</em>;
+        break;
+      case "underline":
+        result = <span style={{ textDecoration: "underline" }}>{result}</span>;
+        break;
+      case "strike-through":
+      case "strikethrough":
+        result = <span style={{ textDecoration: "line-through" }}>{result}</span>;
+        break;
+      case "code":
+        result = <code>{result}</code>;
+        break;
+      default: {
+        // Check if it's a link (markDef reference)
+        const def = getMarkDef(block, mark);
+        if (def && def._type === "link" && def.href) {
+          result = (
+            <a
+              href={def.href as string}
+              target={(def.blank as boolean) ? "_blank" : undefined}
+              rel={(def.blank as boolean) ? "noopener noreferrer" : undefined}
+            >
+              {result}
+            </a>
+          );
+        }
+        break;
+      }
+    }
+  }
+  return result;
+}
+
+// ── Character splitting with mark groups ──
+
+interface CharUnit {
+  /** The character or word to display */
+  text: string;
+  /** Marks to apply (bold, italic, link keys, etc.) */
+  marks: string[] | undefined;
+  /** Parent block (for markDefs lookup) */
+  block: PortableTextBlock;
+  /** Whether this is a space character (for whiteSpace: pre) */
+  isSpace: boolean;
+}
+
+/**
+ * Flatten Portable Text blocks into a sequence of CharUnits.
+ * Each unit carries its marks so we can group consecutive same-mark
+ * characters under a single mark wrapper.
+ */
+function flattenToUnits(
+  blocks: PortableTextContent,
+  mode: "character" | "word",
+): CharUnit[] {
+  const units: CharUnit[] = [];
+
+  for (let bi = 0; bi < blocks.length; bi++) {
+    const block = blocks[bi];
+    if (!block.children) continue;
+
+    // Add a newline separator between blocks (except before first)
+    if (bi > 0 && units.length > 0) {
+      units.push({ text: "\n", marks: undefined, block, isSpace: true });
+    }
+
+    for (const child of block.children) {
+      if (child._type !== "span" || !child.text) continue;
+
+      if (mode === "word") {
+        const wordUnits = child.text.split(/(\s+)/).filter(Boolean);
+        for (const wu of wordUnits) {
+          units.push({
+            text: wu,
+            marks: child.marks,
+            block,
+            isSpace: /^\s+$/.test(wu),
+          });
+        }
+      } else {
+        for (const char of child.text) {
+          units.push({
+            text: char,
+            marks: child.marks,
+            block,
+            isSpace: char === " ",
+          });
+        }
+      }
+    }
+  }
+
+  return units;
+}
+
+// ── Mark grouping for efficient DOM ──
+
+/**
+ * Groups consecutive CharUnits with identical marks under the same wrapper.
+ * This prevents <strong>H</strong><strong>e</strong><strong>l</strong>...
+ * and instead produces <strong><span>H</span><span>e</span><span>l</span>...</strong>
+ */
+interface MarkGroup {
+  marks: string[] | undefined;
+  block: PortableTextBlock;
+  units: { text: string; isSpace: boolean; globalIndex: number }[];
+}
+
+function groupByMarks(flatUnits: CharUnit[]): MarkGroup[] {
+  const groups: MarkGroup[] = [];
+  let current: MarkGroup | null = null;
+
+  for (let i = 0; i < flatUnits.length; i++) {
+    const unit = flatUnits[i];
+    const marksKey = unit.marks?.join(",") ?? "";
+    const currentKey = current?.marks?.join(",") ?? "";
+    const sameBlock = current?.block === unit.block;
+    // Never merge into a newline group, and never merge newlines into a text group
+    const currentIsNewline = current?.units[0]?.text === "\n";
+
+    if (
+      current &&
+      !currentIsNewline &&
+      marksKey === currentKey &&
+      sameBlock &&
+      unit.text !== "\n"
+    ) {
+      current.units.push({ text: unit.text, isSpace: unit.isSpace, globalIndex: i });
+    } else {
+      current = {
+        marks: unit.marks,
+        block: unit.block,
+        units: [{ text: unit.text, isSpace: unit.isSpace, globalIndex: i }],
+      };
+      groups.push(current);
+    }
+  }
+
+  return groups;
+}
+
+// ── Block-level grouping for paragraphs ──
+
+interface BlockGroup {
+  blockKey: string;
+  blockStyle: string;
+  markGroups: MarkGroup[];
+}
+
+function groupByBlocks(
+  blocks: PortableTextContent,
+  allGroups: MarkGroup[],
+): BlockGroup[] {
+  const result: BlockGroup[] = [];
+  let groupIdx = 0;
+
+  for (const block of blocks) {
+    const blockGroups: MarkGroup[] = [];
+
+    while (groupIdx < allGroups.length) {
+      const group = allGroups[groupIdx];
+      // Check if this group's first unit is a newline (block separator)
+      if (group.units.length === 1 && group.units[0].text === "\n") {
+        groupIdx++;
+        break;
+      }
+      if (group.block !== block) break;
+      blockGroups.push(group);
+      groupIdx++;
+    }
+
+    if (blockGroups.length > 0) {
+      result.push({
+        blockKey: block._key,
+        blockStyle: block.style || "normal",
+        markGroups: blockGroups,
+      });
+    }
+  }
+
+  return result;
+}
+
+// ── Block element mapping ──
+
+function getBlockElement(style: string): "p" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "blockquote" {
+  switch (style) {
+    case "h1": return "h1";
+    case "h2": return "h2";
+    case "h3": return "h3";
+    case "h4": return "h4";
+    case "h5": return "h5";
+    case "h6": return "h6";
+    case "blockquote": return "blockquote";
+    default: return "p";
+  }
+}
+
+// ── Component ──
+
+export default function TypewriterRichText({
+  portableText,
+  config,
+  entered,
+  startDelay = 0,
+  showCursor = true,
+  className,
+  style,
+  onComplete,
+}: TypewriterRichTextProps) {
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const cursorRef = useRef<HTMLSpanElement>(null);
+
+  // Merge config with defaults
+  const speed = config?.speed ?? TYPEWRITER_DEFAULTS.speed;
+  const mode = config?.mode ?? TYPEWRITER_DEFAULTS.mode;
+
+  // Convert speed (chars/sec) to delay between units (ms)
+  const unitDelay = Math.round(1000 / speed);
+  const unitDuration = mode === "word" ? 150 : 80;
+
+  // Flatten content into character/word units
+  const flatUnits = useMemo(
+    () => (portableText ? flattenToUnits(portableText, mode) : []),
+    [portableText, mode],
+  );
+
+  // Group consecutive same-mark units for efficient DOM
+  const markGroups = useMemo(() => groupByMarks(flatUnits), [flatUnits]);
+
+  // Group into block-level paragraphs
+  const blockGroups = useMemo(
+    () => (portableText ? groupByBlocks(portableText, markGroups) : []),
+    [portableText, markGroups],
+  );
+
+  // Total character count (excluding newlines)
+  const totalChars = useMemo(
+    () => flatUnits.filter((u) => u.text !== "\n").length,
+    [flatUnits],
+  );
+
+  // Timing
+  const typingEndTime = startDelay + totalChars * unitDelay + unitDuration;
+  const cursorPause = 600;
+  const totalDuration = typingEndTime + cursorPause;
+
+  // Track completion (controls cursor visibility)
+  const [completed, setCompleted] = useState(false);
+
+  // ── Completion timer: fires onComplete after total animation duration ──
+  useEffect(() => {
+    if (!entered) return;
+    const timer = setTimeout(() => {
+      setCompleted(true);
+      onComplete?.();
+    }, totalDuration);
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [entered]);
+
+  // ── Cursor tracking: position cursor via JS interval, zero re-renders ──
+  useEffect(() => {
+    if (!entered || !showCursor) return;
+
+    const wrapper = wrapperRef.current;
+    const cursor = cursorRef.current;
+    if (!wrapper || !cursor) return;
+
+    let count = 0;
+    let delayTimer: ReturnType<typeof setTimeout> | null = null;
+    let intervalTimer: ReturnType<typeof setInterval> | null = null;
+    let blinkTimer: ReturnType<typeof setTimeout> | null = null;
+
+    // Position cursor next to a character span
+    function positionCursor() {
+      if (!wrapper || !cursor) return;
+
+      const targetIdx = Math.max(0, count - 1);
+      const charEl = wrapper.querySelector(
+        `[data-char-idx="${targetIdx}"]`,
+      ) as HTMLElement | null;
+
+      if (charEl) {
+        const wrapperRect = wrapper.getBoundingClientRect();
+        const charRect = charEl.getBoundingClientRect();
+        cursor.style.position = "absolute";
+        cursor.style.left = `${charRect.right - wrapperRect.left}px`;
+        cursor.style.top = `${charRect.top - wrapperRect.top}px`;
+        cursor.style.opacity = "1";
+      }
+    }
+
+    // Wait for startDelay, then advance cursor every unitDelay
+    delayTimer = setTimeout(() => {
+      cursor.style.opacity = "1";
+      positionCursor();
+
+      intervalTimer = setInterval(() => {
+        count++;
+        if (count >= totalChars) {
+          if (intervalTimer) clearInterval(intervalTimer);
+          intervalTimer = null;
+          positionCursor();
+          // Start blinking, then hide after cursorPause
+          cursor.style.animation = `typewriter-cursor-blink 800ms step-end infinite`;
+          blinkTimer = setTimeout(() => {
+            cursor.style.opacity = "0";
+            cursor.style.animation = "none";
+          }, cursorPause);
+          return;
+        }
+        positionCursor();
+      }, unitDelay);
+    }, startDelay);
+
+    return () => {
+      if (delayTimer) clearTimeout(delayTimer);
+      if (intervalTimer) clearInterval(intervalTimer);
+      if (blinkTimer) clearTimeout(blinkTimer);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [entered]);
+
+  // Nothing to render
+  if (!portableText || flatUnits.length === 0) return null;
+
+  return (
+    <div
+      ref={wrapperRef}
+      className={`${className || ""} space-y-[0.75em]`.trim()}
+      style={{ ...style, position: "relative" }}
+      data-typewriter-rich
+    >
+      {blockGroups.map((bg) => {
+        const Tag = getBlockElement(bg.blockStyle);
+        return (
+          <Tag key={bg.blockKey}>
+            {bg.markGroups.map((mg, mgIdx) => {
+              const innerSpans = mg.units.map((unit) => (
+                <span
+                  key={unit.globalIndex}
+                  data-char-idx={unit.globalIndex}
+                  aria-hidden="true"
+                  style={{
+                    opacity: entered ? 1 : 0,
+                    transition: entered
+                      ? `opacity ${unitDuration}ms ease-out ${startDelay + unit.globalIndex * unitDelay}ms`
+                      : "none",
+                    whiteSpace: unit.isSpace ? "pre" : undefined,
+                  }}
+                >
+                  {unit.text}
+                </span>
+              ));
+
+              return (
+                <span key={mgIdx}>
+                  {wrapInMarks(<>{innerSpans}</>, mg.marks, mg.block)}
+                </span>
+              );
+            })}
+          </Tag>
+        );
+      })}
+
+      {/* Cursor — positioned absolutely, tracked by JS interval */}
+      {showCursor && !completed && (
+        <span
+          ref={cursorRef}
+          className="typewriter-cursor"
+          style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            opacity: 0,
+            fontWeight: 100,
+            pointerEvents: "none",
+          }}
+          aria-hidden="true"
+        >
+          |
+        </span>
+      )}
+
+      {/* Screen reader accessible text */}
+      <span className="sr-only">
+        {flatUnits
+          .map((u) => u.text)
+          .join("")
+          .replace(/\n/g, " ")}
+      </span>
+    </div>
+  );
+}

package/components/blocks/TypewriterWrapper.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+/**
+ * TypewriterWrapper — single-phase typewriter reveal for textBlock content.
+ *
+ * Renders the actual rich text (PortableText) with each character individually
+ * animated via opacity transitions. All formatting (bold, italic, links) is
+ * preserved throughout the animation — no plain-text degradation, no swap.
+ *
+ * Architecture: One DOM tree. TypewriterRichText walks the Portable Text AST
+ * and wraps each character in a <span> inside the appropriate mark wrappers.
+ * Characters fade in sequentially with staggered CSS transition delays.
+ * When complete, the cursor blinks briefly and is removed.
+ *
+ * Uses IntersectionObserver with above-the-fold detection (same pattern as
+ * EnterAnimationWrapper).
+ *
+ * prefers-reduced-motion: shows rich text immediately with full opacity, no animation.
+ * Builder mode: not animated (builder never renders this component).
+ *
+ * Session 121 — Original two-phase typewriter.
+ * Session 133 — Rewritten as single-phase (TypewriterRichText). Removed
+ *   extractPlainText, plain-text overlay, visibility swap, Phase 1/Phase 2.
+ *   All formatting now preserved during animation.
+ */
+
+import { useRef, useEffect, useState, useCallback, type CSSProperties } from "react";
+import type { TypewriterConfig } from "../../lib/animation/enter-types";
+import type { PortableTextContent } from "../../lib/sanity/types";
+import TypewriterRichText from "./TypewriterRichText";
+
+// ── Count total characters in PortableText (for empty check) ──
+
+function hasTextContent(portableText: PortableTextContent | undefined): boolean {
+  if (!portableText || portableText.length === 0) return false;
+  return portableText.some(
+    (block) =>
+      block.children?.some(
+        (child) => child._type === "span" && child.text && child.text.length > 0,
+      ),
+  );
+}
+
+// ── Component ──
+
+interface TypewriterWrapperProps {
+  /** The Portable Text content from the text block */
+  portableText: PortableTextContent | undefined;
+  /** Typewriter configuration (speed, mode) */
+  config?: TypewriterConfig;
+  /** The fully rendered rich text (PortableText output) — fallback for reduced motion */
+  children: React.ReactNode;
+  /** Animation delay from enter animation config */
+  delay?: number;
+  /** CSS class for text styling (from getTextBlockStyles) */
+  textClassName?: string;
+  /** Inline styles for text styling (from getTextBlockStyles) */
+  textStyle?: CSSProperties;
+}
+
+export default function TypewriterWrapper({
+  portableText,
+  config,
+  children,
+  delay = 0,
+  textClassName,
+  textStyle,
+}: TypewriterWrapperProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [hasEntered, setHasEntered] = useState(false);
+  const [typewriterDone, setTypewriterDone] = useState(false);
+
+  // ── IntersectionObserver ──
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || hasEntered) return;
+
+    // Respect prefers-reduced-motion: skip animation entirely
+    if (
+      typeof window !== "undefined" &&
+      window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    ) {
+      setHasEntered(true);
+      setTypewriterDone(true);
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setHasEntered(true);
+          observer.disconnect();
+        }
+      },
+      { threshold: 0.15 },
+    );
+
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [hasEntered]);
+
+  const handleComplete = useCallback(() => {
+    setTypewriterDone(true);
+  }, []);
+
+  // If no text content, render children directly (PortableText fallback)
+  if (!hasTextContent(portableText)) {
+    return <>{children}</>;
+  }
+
+  // prefers-reduced-motion: show the standard PortableText immediately
+  if (
+    typeof window !== "undefined" &&
+    typewriterDone &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  ) {
+    return (
+      <div
+        ref={ref}
+        data-enter-animation="typewriter"
+        data-entered=""
+      >
+        {children}
+      </div>
+    );
+  }
+
+  // Normal flow: TypewriterRichText stays rendered even after completion.
+  // After animation finishes all chars are opacity:1 and the cursor is removed,
+  // so the visual output is identical to PortableText — no swap, no layout jump.
+  return (
+    <div
+      ref={ref}
+      data-enter-animation="typewriter"
+      data-entered={hasEntered || typewriterDone ? "" : undefined}
+    >
+      <TypewriterRichText
+        portableText={portableText}
+        config={config}
+        entered={hasEntered}
+        startDelay={delay}
+        showCursor={!typewriterDone}
+        className={textClassName}
+        style={textStyle}
+        onComplete={handleComplete}
+      />
+    </div>
+  );
+}