@boyernick/standard-ui-react 0.1.1-canary.9 → 0.2.0

package/src/lifeline/lifeline-data.ts

@@ -0,0 +1,97 @@
+import type {
+  LifelineEvent,
+  LifelineLegendItem,
+  LifelineMarker,
+} from "./types"
+
+export const LIFELINE_CURRENT_YEAR = 2026
+
+export type LifelineMilestone = Omit<LifelineMarker, "year">
+export type LifelineMilestones = Record<number, LifelineMilestone>
+
+export interface LifelineBirthday {
+  month: number
+  day: number
+}
+
+export interface LifelineRecord {
+  slug: string
+  name: string
+  birthYear: number
+  birthday?: LifelineBirthday
+  /** Last year on the timeline. Omit for living people. */
+  endYear?: number
+  description: string
+  /** People-legend labels; defaults to Mentors / Met in person. */
+  legend?: LifelineLegendItem[]
+  markers: LifelineMarker[]
+}
+
+interface DefineLifelineInput {
+  slug: string
+  name: string
+  birthYear: number
+  birthday?: LifelineBirthday
+  endYear?: number
+  description: string
+  legend?: LifelineLegendItem[]
+  milestones: LifelineMilestones
+}
+
+/**
+ * Translated event texts keyed by year, aligned by index with the
+ * source milestone's events. Only the text is swapped — images,
+ * effects, mentors, and structure stay single-sourced.
+ */
+export type LifelineTextOverrides = Record<number, string[]>
+
+export function localizeLifelineMarkers(
+  markers: LifelineMarker[],
+  texts: LifelineTextOverrides,
+): LifelineMarker[] {
+  return markers.map((marker) => {
+    const translated = texts[marker.year]
+    if (!translated) return marker
+
+    const events: LifelineEvent[] = marker.events.map((event, index) => {
+      const text = translated[index]
+      if (text === undefined) return event
+      if (typeof event === "string") return text
+      if (Array.isArray(event)) return event
+      return { ...event, text }
+    })
+
+    return { ...marker, events }
+  })
+}
+
+export function defineLifeline(input: DefineLifelineInput): LifelineRecord {
+  const { milestones, ...record } = input
+  const lastYear = input.endYear ?? LIFELINE_CURRENT_YEAR
+  const markers: LifelineMarker[] = []
+  const today = new Date()
+
+  for (let year = input.birthYear; year <= lastYear; year++) {
+    const milestone = milestones[year]
+    const birthdayPending =
+      year === LIFELINE_CURRENT_YEAR &&
+      input.birthday &&
+      (today.getMonth() + 1 < input.birthday.month ||
+        (today.getMonth() + 1 === input.birthday.month &&
+          today.getDate() < input.birthday.day))
+    const age = birthdayPending ? year - input.birthYear - 1 : undefined
+
+    markers.push(
+      milestone
+        ? { year, ...(age !== undefined && { age }), ...milestone }
+        : {
+            id: `year-${year}`,
+            year,
+            events: [],
+            ...(age !== undefined && { age }),
+          },
+    )
+  }
+
+  return { ...record, markers }
+}

package/src/lifeline/lifeline-desktop.tsx

@@ -0,0 +1,204 @@
+"use client"
+
+import { useMemo, type CSSProperties } from "react"
+import { cn } from "../lib/cn"
+import { focusRing, focusRingBorder } from "../lib/focus"
+import {
+  LifelineStickyLabels,
+  LIFELINE_STICKY_SHIELD_WIDTH,
+} from "./lifeline-labels"
+import { LifelineMarkerColumn } from "./lifeline-marker"
+import type { LifelineEventImage, LifelineProps } from "./types"
+import { getLifelineEventImage } from "./lifeline-event"
+import { LifelineHoverImageProvider } from "./lifeline-hover-image"
+import { LifelineFloatingPhotos } from "./lifeline-photos"
+import { useLifelineIntro } from "./use-lifeline-intro"
+import { useLifelineScroll } from "./use-lifeline-scroll"
+import { getMarkerWidth } from "./lifeline-utils"
+
+export function LifelineDesktop({
+  markers,
+  birthYear,
+  className,
+  title = "Lifeline",
+  mode = "auto",
+}: LifelineProps) {
+  const widths = useMemo(
+    () =>
+      markers.map((marker, index) =>
+        getMarkerWidth(marker, markers[index + 1]?.year),
+      ),
+    [markers],
+  )
+
+  // Left edge of each marker's slot within the track — anchors for the
+  // floating photo cards.
+  const offsets = useMemo(() => {
+    const result: number[] = []
+    let sum = 0
+    for (const width of widths) {
+      result.push(sum)
+      sum += width
+    }
+    return result
+  }, [widths])
+
+  const hoverImages = useMemo(() => {
+    const images: LifelineEventImage[] = []
+    for (const marker of markers) {
+      for (const event of marker.events) {
+        const image = getLifelineEventImage(event)
+        if (image) images.push(image)
+      }
+    }
+    return images
+  }, [markers])
+
+  const intro = useLifelineIntro(widths)
+  const isIntroAnimating = intro.shouldPlay && intro.isPlaying
+
+  const {
+    sectionRef,
+    trackRef,
+    labelsRef,
+    setMarkerRef,
+    isLayoutReady,
+    isEmbed,
+    introArmed,
+  } = useLifelineScroll(markers.length, {
+    mode,
+    introLocked: isIntroAnimating,
+    introAnimating: isIntroAnimating,
+    introSkipped: !intro.shouldPlay,
+    introRailMs: intro.railDuration,
+    introGetTrackProgress: intro.getTrackProgressAtTime,
+    onIntroScrollStart: intro.startIntroTimer,
+    onIntroSettleComplete: intro.completeIntro,
+  })
+
+  // Embedded, the open waits for the module to come into view: the marker
+  // fades are CSS animations that start the moment their class lands, so
+  // applying it early would spend them below the fold.
+  const introWaitingInView = isEmbed && intro.shouldPlay && !introArmed
+  const showIntro = isIntroAnimating && isLayoutReady && !introWaitingInView
+
+  const trackWidth =
+    LIFELINE_STICKY_SHIELD_WIDTH + widths.reduce((sum, width) => sum + width, 0)
+
+  const introStyle = {
+    "--lifeline-labels-ms": `${intro.labelsDuration}ms`,
+    "--lifeline-rail-ms": `${intro.railDuration}ms`,
+  } as CSSProperties
+
+  return (
+    <section
+      ref={sectionRef}
+      data-lifeline-mode={isEmbed ? "embed" : "page"}
+      // Embedded, the module needs a tab stop to be operable at all — a
+      // page-mode lifeline is reached just by scrolling to it.
+      tabIndex={isEmbed ? 0 : undefined}
+      className={cn(
+        "relative h-full min-h-0 select-none overflow-hidden [&_a]:cursor-pointer",
+        // `pan-y` lets the browser start a vertical page scroll on the
+        // first frame instead of waiting on the JS axis lock; horizontal
+        // panning stays ours.
+        isEmbed &&
+          cn("touch-pan-y", focusRingBorder, focusRing),
+        // Hold it blank rather than showing a settled timeline that then
+        // resets itself to play the intro. Below the fold there is nothing
+        // to see anyway, and the arming margin means it fills in before it
+        // reaches the reader.
+        (!isLayoutReady || introWaitingInView) && "invisible",
+        className,
+      )}
+      aria-label={title}
+      style={showIntro ? introStyle : undefined}
+    >
+      <LifelineHoverImageProvider preload={hoverImages}>
+      {/*
+        Centered — but `safe center` where the browser understands it, which
+        matters once the height is the consumer's to choose. A track taller
+        than its box would otherwise overflow equally top and bottom, and
+        since the section clips, the first thing lost is the row nearest the
+        top: the Age/Years label column and the year labels. `safe` falls
+        back to start-alignment exactly in that case, so the labels and the
+        rail stay put and only the tail of a long column clips. Declared
+        inline so browsers without it simply keep the `items-center` class.
+      */}
+      <div
+        className="flex h-full items-center overflow-hidden"
+        style={isEmbed ? { alignItems: "safe center" } : undefined}
+      >
+        <div
+          ref={trackRef}
+          className="relative flex w-max items-start will-change-transform [--lifeline-people-top:calc(14.5rem+40px)] [--lifeline-rail:5rem]"
+          style={{ width: trackWidth }}
+        >
+          {/*
+            LIFELINE_STICKY_SHIELD_WIDTH reserves this column at the head of
+            the track, and the column has to actually paint it: once the
+            track scrolls, marker text passes underneath and would otherwise
+            read straight through "Age" and "Years".
+
+            `bg-background-primary` to match the framing the shell puts
+            around this — reframe the page on a different surface and this
+            wants overriding with it. The transition is not decoration
+            either: without it the shield snaps between the two while the
+            page behind it is still crossfading, which flashes a hard box
+            for the length of a theme switch. 300ms on the default curve is
+            what `LifelineShell` fades on, so the two move as one.
+          */}
+          <div
+            ref={labelsRef}
+            className="lifeline-labels shrink-0 bg-background-primary transition-colors duration-300 will-change-transform"
+            style={{ width: LIFELINE_STICKY_SHIELD_WIDTH }}
+          >
+            <div className={cn(showIntro && "lifeline-labels-intro")}>
+              <LifelineStickyLabels />
+            </div>
+          </div>
+
+          <div className="relative">
+            <div
+              aria-hidden="true"
+              className="pointer-events-none absolute inset-x-0 top-[var(--lifeline-rail)] h-px overflow-hidden"
+            >
+              <div
+                className={cn(
+                  "h-px w-full border-t border-dashed border-border-primary transition-colors duration-300",
+                  showIntro && "lifeline-rail-intro",
+                )}
+              />
+            </div>
+
+            <div className="relative flex items-start">
+              {markers.map((marker, index) => (
+                <LifelineMarkerColumn
+                  key={marker.id}
+                  ref={(node) => setMarkerRef(index, node)}
+                  marker={marker}
+                  birthYear={birthYear}
+                  minWidth={widths[index]}
+                  animateIntro={showIntro}
+                  introDelay={intro.getMarkerDelay(index)}
+                  introDuration={intro.getMarkerFadeDuration(index)}
+                />
+              ))}
+            </div>
+
+            <LifelineFloatingPhotos
+              markers={markers}
+              offsets={offsets}
+              widths={widths}
+              animateIntro={showIntro}
+              getIntroDelay={intro.getMarkerDelay}
+              getIntroDuration={intro.getMarkerFadeDuration}
+            />
+          </div>
+        </div>
+      </div>
+
+      </LifelineHoverImageProvider>
+    </section>
+  )
+}

package/src/lifeline/lifeline-event.tsx

@@ -0,0 +1,108 @@
+import type {
+  LifelineEvent,
+  LifelineEventEffect,
+  LifelineEventImage,
+  LifelineEventSegment,
+} from "./types"
+
+function getEventContent(
+  event: LifelineEvent,
+): string | LifelineEventSegment[] {
+  if (typeof event === "object" && !Array.isArray(event) && "text" in event) {
+    return event.text
+  }
+
+  return event
+}
+
+export function getLifelineEventImage(
+  event: LifelineEvent,
+): LifelineEventImage | undefined {
+  if (typeof event === "object" && !Array.isArray(event) && "image" in event) {
+    return event.image
+  }
+
+  return undefined
+}
+
+export function getLifelineEventEffect(
+  event: LifelineEvent,
+): LifelineEventEffect | undefined {
+  if (typeof event === "object" && !Array.isArray(event) && "effect" in event) {
+    return event.effect
+  }
+
+  return undefined
+}
+
+export function LifelineEventText({
+  event,
+  className,
+}: {
+  event: LifelineEvent
+  className?: string
+}) {
+  const content = getEventContent(event)
+
+  if (typeof content === "string") {
+    return <span className={className}>{content}</span>
+  }
+
+  return (
+    <span className={className}>
+      {content.map((segment, index) =>
+        segment.type === "link" ? (
+          <a
+            key={index}
+            href={segment.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-inherit underline decoration-fg-quaternary underline-offset-2 transition-colors duration-300 group-hover:text-fg-primary group-hover:decoration-fg-tertiary"
+          >
+            {segment.value}
+          </a>
+        ) : (
+          <span key={index}>{segment.value}</span>
+        ),
+      )}
+    </span>
+  )
+}
+
+/** Always-visible media embedded in the timeline (image.inline). */
+export function LifelineEventMedia({
+  media,
+  className,
+}: {
+  media: LifelineEventImage
+  className?: string
+}) {
+  if (media.video) {
+    return (
+      <video
+        src={media.video}
+        poster={media.src}
+        autoPlay
+        muted
+        loop
+        playsInline
+        preload="metadata"
+        aria-label={media.alt}
+        className={className}
+      />
+    )
+  }
+
+  return (
+    // eslint-disable-next-line @next/next/no-img-element
+    <img src={media.src} alt={media.alt} loading="lazy" className={className} />
+  )
+}
+
+export function getLifelineEventKey(event: LifelineEvent, index: number) {
+  const content = getEventContent(event)
+
+  if (typeof content === "string") return `${index}-${content}`
+
+  return `${index}-${content.map((segment) => segment.value).join("")}`
+}

package/src/lifeline/lifeline-fireworks.tsx

@@ -0,0 +1,302 @@
+"use client"
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react"
+import type { LifelineEventEffect } from "./types"
+
+/** Tweak these */
+const DURATION_S = 7.5
+const MAX_DPR = 1.5
+/** Wait for the theme cross-fade before the first burst. */
+const NIGHTFALL_MS = 400
+
+type Palette = [number[], number[], number[]]
+
+const PALETTES: Record<LifelineEventEffect, Palette> = {
+  // Old Glory red / white / blue
+  fireworks: [
+    [0.9, 0.15, 0.25],
+    [1.0, 1.0, 1.0],
+    [0.25, 0.45, 0.95],
+  ],
+  // celeste / white / pale celeste
+  "fireworks-argentina": [
+    [0.45, 0.75, 0.98],
+    [1.0, 1.0, 1.0],
+    [0.7, 0.87, 1.0],
+  ],
+}
+
+const VERTEX_SHADER = `
+attribute vec2 a_pos;
+void main() {
+  gl_Position = vec4(a_pos, 0.0, 1.0);
+}
+`
+
+/**
+ * Additive point-glow fireworks in Old Glory red, white, and blue,
+ * composited over a night-sky scrim via premultiplied canvas alpha.
+ */
+const FRAGMENT_SHADER = `
+precision highp float;
+
+uniform vec2 u_res;
+uniform float u_time;
+uniform float u_dur;
+uniform vec3 u_c0;
+uniform vec3 u_c1;
+uniform vec3 u_c2;
+
+#define TAU 6.28318530718
+#define N_FIREWORKS 10
+#define N_PARTICLES 42
+
+float hash(float n) {
+  return fract(sin(n) * 43758.5453123);
+}
+
+vec3 palette(float m) {
+  if (m < 0.5) return u_c0;
+  if (m < 1.5) return u_c1;
+  return u_c2;
+}
+
+void main() {
+  vec2 uv = (gl_FragCoord.xy - 0.5 * u_res) / u_res.y;
+  float t = u_time;
+  float env = smoothstep(0.0, 0.5, t) * (1.0 - smoothstep(u_dur - 1.0, u_dur, t));
+
+  vec3 col = vec3(0.0);
+
+  for (int i = 0; i < N_FIREWORKS; i++) {
+    float fi = float(i);
+    float t0 = 0.35 + fi * (u_dur - 2.8) / float(N_FIREWORKS) + hash(fi * 7.31) * 0.3;
+    // No flow control in the loop — some WebGL1 driver translations
+    // mishandle continue, so inactive bursts multiply to zero instead.
+    float active = step(t0, t) * step(t, t0 + 1.8);
+    float lt = clamp((t - t0) / 1.8, 0.0, 1.0);
+
+    vec2 center = vec2((hash(fi * 3.7) - 0.5) * 1.6, -0.05 + hash(fi * 9.1) * 0.5);
+    vec3 base = palette(mod(fi, 3.0)); // strict red / white / blue rotation
+    // Ramp in fast so overlapping particles at ignition don't stack
+    // into a blown-out ball, then decay.
+    float fade = exp(-lt * 4.0) * min(1.0, lt * 6.0);
+
+    for (int j = 0; j < N_PARTICLES; j++) {
+      float fj = float(j);
+      float angle = (fj / float(N_PARTICLES)) * TAU + hash(fi * 100.0 + fj) * 0.15;
+      float speed = 0.16 + 0.22 * hash(fj * 7.77 + fi * 31.3);
+
+      vec2 p = center + vec2(cos(angle), sin(angle)) * speed * sqrt(lt);
+      p.y -= 0.09 * lt * lt; // gravity
+
+      float d = max(length(uv - p), 0.004);
+      float sparkle = 0.7 + 0.3 * sin(30.0 * lt + fj * 1.7);
+      col += base * active * fade * sparkle * 0.0006 / (d * d);
+    }
+  }
+
+  col = clamp(col * env, 0.0, 1.0);
+  float spark = max(col.r, max(col.g, col.b));
+  float scrim = 0.45 * env;
+  gl_FragColor = vec4(col, max(spark, scrim));
+}
+`
+
+interface LifelineFireworksApi {
+  launch: (effect: LifelineEventEffect) => void
+}
+
+const LifelineFireworksContext = createContext<LifelineFireworksApi | null>(
+  null,
+)
+
+export function useLifelineFireworks() {
+  return useContext(LifelineFireworksContext)
+}
+
+function FireworksCanvas({
+  palette,
+  onDone,
+}: {
+  palette: Palette
+  onDone: () => void
+}) {
+  const paletteRef = useRef(palette)
+  paletteRef.current = palette
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const onDoneRef = useRef(onDone)
+  onDoneRef.current = onDone
+
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) return
+
+    const gl = canvas.getContext("webgl", {
+      alpha: true,
+      premultipliedAlpha: true,
+      antialias: false,
+    })
+    if (!gl) {
+      onDoneRef.current()
+      return
+    }
+
+    const compile = (type: number, source: string) => {
+      const shader = gl.createShader(type)!
+      gl.shaderSource(shader, source)
+      gl.compileShader(shader)
+      if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        console.warn("fireworks shader:", gl.getShaderInfoLog(shader))
+      }
+      return shader
+    }
+
+    const program = gl.createProgram()!
+    gl.attachShader(program, compile(gl.VERTEX_SHADER, VERTEX_SHADER))
+    gl.attachShader(program, compile(gl.FRAGMENT_SHADER, FRAGMENT_SHADER))
+    gl.linkProgram(program)
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+      console.warn("fireworks link:", gl.getProgramInfoLog(program))
+      onDoneRef.current()
+      return
+    }
+    gl.useProgram(program)
+
+    const buffer = gl.createBuffer()
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      new Float32Array([-1, -1, 3, -1, -1, 3]),
+      gl.STATIC_DRAW,
+    )
+    const aPos = gl.getAttribLocation(program, "a_pos")
+    gl.enableVertexAttribArray(aPos)
+    gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0)
+
+    const uRes = gl.getUniformLocation(program, "u_res")
+    const uTime = gl.getUniformLocation(program, "u_time")
+    const uDur = gl.getUniformLocation(program, "u_dur")
+
+    const [c0, c1, c2] = paletteRef.current
+    gl.uniform3f(gl.getUniformLocation(program, "u_c0"), c0[0], c0[1], c0[2])
+    gl.uniform3f(gl.getUniformLocation(program, "u_c1"), c1[0], c1[1], c1[2])
+    gl.uniform3f(gl.getUniformLocation(program, "u_c2"), c2[0], c2[1], c2[2])
+
+    const resize = () => {
+      const dpr = Math.min(window.devicePixelRatio || 1, MAX_DPR)
+      canvas.width = Math.round(window.innerWidth * dpr)
+      canvas.height = Math.round(window.innerHeight * dpr)
+      gl.viewport(0, 0, canvas.width, canvas.height)
+    }
+    resize()
+    window.addEventListener("resize", resize)
+
+    let frame = 0
+    const start = performance.now()
+
+    const step = (now: number) => {
+      const t = (now - start) / 1000
+      if (t >= DURATION_S) {
+        onDoneRef.current()
+        return
+      }
+
+      gl.uniform2f(uRes, canvas.width, canvas.height)
+      gl.uniform1f(uTime, t)
+      gl.uniform1f(uDur, DURATION_S)
+      gl.clearColor(0, 0, 0, 0)
+      gl.clear(gl.COLOR_BUFFER_BIT)
+      gl.drawArrays(gl.TRIANGLES, 0, 3)
+
+      frame = requestAnimationFrame(step)
+    }
+    frame = requestAnimationFrame(step)
+
+    return () => {
+      cancelAnimationFrame(frame)
+      window.removeEventListener("resize", resize)
+      // No manual loseContext: StrictMode re-runs this effect on the
+      // same canvas, and a lost context can never compile again.
+    }
+  }, [])
+
+  return (
+    <canvas
+      ref={canvasRef}
+      aria-hidden="true"
+      className="pointer-events-none fixed inset-0 z-[70] h-full w-full"
+    />
+  )
+}
+
+function isDarkDocument() {
+  return document.documentElement.classList.contains("dark")
+}
+
+function setDocumentDark(dark: boolean) {
+  document.documentElement.classList.toggle("dark", dark)
+}
+
+export function LifelineFireworksProvider({
+  children,
+}: {
+  children: ReactNode
+}) {
+  const [playing, setPlaying] = useState(false)
+  const [effect, setEffect] = useState<LifelineEventEffect>("fireworks")
+  const restoreThemeRef = useRef<"light" | null>(null)
+  const nightfallRef = useRef(0)
+  const playingRef = useRef(false)
+  playingRef.current = playing
+
+  useEffect(() => {
+    return () => window.clearTimeout(nightfallRef.current)
+  }, [])
+
+  const launch = useCallback((nextEffect: LifelineEventEffect) => {
+    if (playingRef.current) return
+    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return
+
+    setEffect(nextEffect)
+
+    // Fireworks belong in the dark: switch a light page to dark for
+    // the show, and restore afterwards.
+    if (!isDarkDocument()) {
+      restoreThemeRef.current = "light"
+      setDocumentDark(true)
+      window.clearTimeout(nightfallRef.current)
+      nightfallRef.current = window.setTimeout(
+        () => setPlaying(true),
+        NIGHTFALL_MS,
+      )
+      return
+    }
+
+    restoreThemeRef.current = null
+    setPlaying(true)
+  }, [])
+
+  const done = useCallback(() => {
+    setPlaying(false)
+    if (restoreThemeRef.current) {
+      setDocumentDark(false)
+      restoreThemeRef.current = null
+    }
+  }, [])
+
+  return (
+    <LifelineFireworksContext.Provider value={{ launch }}>
+      {children}
+      {playing && <FireworksCanvas palette={PALETTES[effect]} onDone={done} />}
+    </LifelineFireworksContext.Provider>
+  )
+}