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

package/src/lifeline/lifeline-vertical.tsx

@@ -0,0 +1,482 @@
+"use client"
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+} from "react"
+import { LifelineFilmIcon as Film, LifelineImageIcon as ImageIcon } from "./lifeline-icons"
+import { cn } from "../lib/cn"
+import { CompanyIcon } from "./company-icon"
+import {
+  getLifelineEventEffect,
+  getLifelineEventImage,
+  getLifelineEventKey,
+  LifelineEventText,
+} from "./lifeline-event"
+import { useLifelineFireworks } from "./lifeline-fireworks"
+import {
+  LifelineLightbox,
+  type LifelineLightboxStart,
+} from "./lifeline-lightbox"
+import { aggregateLifelinePeople, LifelinePeople } from "./lifeline-people"
+import { LifelinePhotoCard } from "./lifeline-photos"
+import type { LifelineEvent, LifelineMarker, LifelineProps } from "./types"
+import { getMarkerHeight, hasMarkerContent, seededUnit } from "./lifeline-utils"
+import { useLifelineIntro } from "./use-lifeline-intro"
+import { useLifelineVerticalScroll } from "./use-lifeline-vertical-scroll"
+
+const GRID_CLASS = "grid grid-cols-[2.5rem_1rem_1fr] gap-x-3"
+const RAIL_LEFT = "calc(2.5rem + 0.75rem + 0.5rem)"
+
+/**
+ * Above this many entries the delay-armed intro fades would promote
+ * every entry to a compositor layer at once and crash mobile Safari's
+ * compositor. Long timelines fade entries in as they enter the
+ * viewport during the auto-scroll instead — same look, but only a
+ * handful of live animations at any moment.
+ */
+const MAX_ARMED_ENTRIES = 80
+
+function RailTick() {
+  return (
+    <span
+      aria-hidden="true"
+      className="block h-px w-[10px] bg-fg-quaternary transition-colors duration-300"
+    />
+  )
+}
+
+/**
+ * One event line. Touch layouts have no hover reveal, so an event with
+ * attached media becomes tappable: the media expands into the lightbox
+ * from the event's text, framed by the poster image's real aspect.
+ */
+function LifelineVerticalEvent({ event }: { event: LifelineEvent }) {
+  const fireworks = useLifelineFireworks()
+  const image = getLifelineEventImage(event)
+  const effect = getLifelineEventEffect(event)
+  const textRef = useRef<HTMLParagraphElement>(null)
+  const aspectRef = useRef(3 / 4)
+  const [lightboxStart, setLightboxStart] =
+    useState<LifelineLightboxStart | null>(null)
+
+  // The event text has no card geometry — synthesize a small seed
+  // centered on the text, carrying the media's aspect so the lightbox
+  // expands into the right frame.
+  const measureText = useCallback((): LifelineLightboxStart | null => {
+    const el = textRef.current
+    if (!el) return null
+    const rect = el.getBoundingClientRect()
+    const w = 96
+    return {
+      cx: rect.left + rect.width / 2,
+      cy: rect.top + rect.height / 2,
+      w,
+      h: w * aspectRef.current,
+    }
+  }, [])
+
+  const openMedia = () => {
+    if (!image || lightboxStart) return
+    // The poster sets the frame; for videos it shares the clip's aspect.
+    const probe = new window.Image()
+    probe.src = image.src
+    const open = () => {
+      if (probe.naturalWidth > 0) {
+        aspectRef.current = probe.naturalHeight / probe.naturalWidth
+      }
+      setLightboxStart(measureText())
+    }
+    if (probe.complete) {
+      open()
+    } else {
+      probe.onload = open
+      probe.onerror = open
+    }
+  }
+
+  return (
+    <>
+      <p
+        ref={textRef}
+        className={cn(
+          "max-w-[18rem] text-left text-[14px] leading-[1.55] tracking-[-0.01em]",
+          (image || effect) && "cursor-pointer",
+        )}
+        onClick={
+          image
+            ? openMedia
+            : effect && fireworks
+              ? () => fireworks.launch(effect)
+              : undefined
+        }
+      >
+        <LifelineEventText event={event} />
+        {image && (
+          // Glued to the last word with a no-break space so the icon
+          // can never wrap onto a line of its own.
+          <span className="whitespace-nowrap">
+            {" "}
+            {image.video ? (
+              <Film
+                className="ml-0.5 inline-block h-3 w-3 -translate-y-px text-fg-quaternary transition-colors duration-300"
+                strokeWidth={1.75}
+                aria-hidden="true"
+              />
+            ) : (
+              <ImageIcon
+                className="ml-0.5 inline-block h-3 w-3 -translate-y-px text-fg-quaternary transition-colors duration-300"
+                strokeWidth={1.75}
+                aria-hidden="true"
+              />
+            )}
+          </span>
+        )}
+      </p>
+      {lightboxStart && image && (
+        <LifelineLightbox
+          photo={image}
+          rotate={0}
+          start={lightboxStart}
+          getHome={measureText}
+          onClosed={() => setLightboxStart(null)}
+        />
+      )}
+    </>
+  )
+}
+
+const LifelineVerticalEntry = forwardRef<
+  HTMLLIElement,
+  {
+    marker: LifelineMarker
+    birthYear: number
+    animateIntro?: boolean
+    introDelay?: number
+    introDuration?: number
+    revealPending?: boolean
+  }
+>(function LifelineVerticalEntry(
+  {
+    marker,
+    birthYear,
+    animateIntro = false,
+    introDelay = 0,
+    introDuration = 420,
+    revealPending = false,
+  },
+  ref,
+) {
+  const age = marker.age ?? marker.year - birthYear
+  const people = aggregateLifelinePeople(marker)
+  const photos = marker.photos ?? []
+  const hasContent = hasMarkerContent(marker) || photos.length > 0
+  // Fresh tilts per visit; stacked neighbors lean apart.
+  const [photoTilts] = useState(() =>
+    (marker.photos ?? []).map((photo, index) => {
+      const unit = seededUnit(`${photo.src}:${index}`)
+      const sign =
+        (marker.photos?.length ?? 0) > 1
+          ? index % 2 === 0
+            ? -1
+            : 1
+          : unit > 0.5
+            ? 1
+            : -1
+      return sign * (2 + seededUnit(`${photo.src}:${index}:tilt`) * 4)
+    }),
+  )
+
+  return (
+    <li
+      ref={ref}
+      className={hasContent ? "pb-10" : "pb-3"}
+      aria-label={marker.label ?? `${marker.year}`}
+    >
+      <div
+        className={cn(
+          animateIntro && "lifeline-marker-intro",
+          revealPending && "opacity-0",
+        )}
+        style={{
+          animationDelay: animateIntro ? `${introDelay}ms` : undefined,
+          ...(animateIntro
+            ? ({
+                "--lifeline-marker-fade-ms": `${introDuration}ms`,
+              } as CSSProperties)
+            : {}),
+        }}
+      >
+        <div className={`${GRID_CLASS} items-center`}>
+          <p className="text-right text-[11px] font-medium leading-4 tabular-nums text-fg-tertiary transition-colors duration-300">
+            {age}
+          </p>
+
+          <div className="flex items-center justify-center">
+            <RailTick />
+          </div>
+
+          <p className="whitespace-nowrap text-[15px] font-medium leading-5 tabular-nums text-fg-secondary transition-colors duration-300">
+            {marker.label ?? marker.year}
+          </p>
+        </div>
+
+        {hasContent && (
+          <div className={`${GRID_CLASS} mt-6`}>
+            <div aria-hidden="true" />
+            <div aria-hidden="true" />
+            <div className="min-w-0 text-fg-secondary transition-colors duration-300">
+              {marker.badges && marker.badges.length > 0 && (
+                <div className="mb-3 flex items-center justify-start gap-2">
+                  {marker.badges.map((badge) => (
+                    // eslint-disable-next-line @next/next/no-img-element
+                    <img
+                      key={badge.src}
+                      src={badge.src}
+                      alt={badge.alt}
+                      className="h-6 w-6 object-contain opacity-80"
+                    />
+                  ))}
+                </div>
+              )}
+
+              {marker.companies && marker.companies.length > 0 && (
+                <div className="mb-2 flex items-center justify-start gap-1.5">
+                  {marker.companies.map((company) => (
+                    <CompanyIcon
+                      key={company.id}
+                      id={company.id}
+                      label={company.name}
+                      className="opacity-70"
+                    />
+                  ))}
+                </div>
+              )}
+
+              {marker.events.length > 0 && (
+                <div className="space-y-4">
+                  {marker.events.map((event, index) => (
+                    <LifelineVerticalEvent
+                      key={getLifelineEventKey(event, index)}
+                      event={event}
+                    />
+                  ))}
+                </div>
+              )}
+
+              {photos.length > 0 && (
+                <div className="mt-6 flex flex-wrap items-start">
+                  {photos.map((photo, index) => (
+                    <LifelinePhotoCard
+                      key={`${photo.src}-${index}`}
+                      photo={photo}
+                      rotate={photo.rotate ?? photoTilts[index] ?? 0}
+                      width={160}
+                      className={cn(
+                        "relative",
+                        index > 0 && "-ml-8 mt-6",
+                      )}
+                    />
+                  ))}
+                </div>
+              )}
+
+              {people.length > 0 && (
+                <div className="mt-6 border-t border-border-secondary pt-5 transition-colors duration-300">
+                  <LifelinePeople people={people} allowWrap />
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
+    </li>
+  )
+})
+
+export function LifelineVertical({
+  markers,
+  birthYear,
+  title = "Lifeline",
+  mode = "auto",
+}: LifelineProps) {
+  // Only an explicit `mode` embeds the vertical layout. `"auto"` measures
+  // scrollability on desktop, but the mobile layout *is* a vertical
+  // scroller inside a scrolling stage, so that test would read every
+  // full-page timeline as embedded and drop its intro.
+  const isEmbed = mode === "embed"
+  const heights = useMemo(
+    () =>
+      markers.map((marker, index) =>
+        getMarkerHeight(marker, markers[index + 1]?.year),
+      ),
+    [markers],
+  )
+
+  const intro = useLifelineIntro(heights)
+  const isIntroAnimating = intro.shouldPlay && intro.isPlaying
+
+  // Warm the event media posters during idle — the tap-to-open
+  // lightbox measures its frame from these, and a cold fetch at tap
+  // time reads as lag.
+  useEffect(() => {
+    const sources: string[] = []
+    for (const marker of markers) {
+      for (const event of marker.events) {
+        const image = getLifelineEventImage(event)
+        if (image) sources.push(image.src)
+      }
+    }
+    if (sources.length === 0) return
+
+    const warm = () => {
+      sources.forEach((src) => {
+        const image = new window.Image()
+        image.src = src
+      })
+    }
+
+    if (typeof window.requestIdleCallback === "function") {
+      const handle = window.requestIdleCallback(warm)
+      return () => window.cancelIdleCallback(handle)
+    }
+    const timeout = window.setTimeout(warm, 2000)
+    return () => window.clearTimeout(timeout)
+  }, [markers])
+
+  const { sectionRef, setEntryRef, isLayoutReady } = useLifelineVerticalScroll(
+    markers.length,
+    {
+      isEmbed,
+      introLocked: isIntroAnimating,
+      introAnimating: isIntroAnimating,
+      // Embedded, the sweep would play out unseen below the fold — and
+      // lock the module's own scroller while doing it.
+      introSkipped: !intro.shouldPlay || isEmbed,
+      introRailMs: intro.railDuration,
+      introGetTrackProgress: intro.getTrackProgressAtTime,
+      onIntroScrollStart: intro.startIntroTimer,
+      onIntroSettleComplete: intro.completeIntro,
+    },
+  )
+
+  const showIntro = isIntroAnimating && isLayoutReady && !isEmbed
+  const revealOnScroll = markers.length > MAX_ARMED_ENTRIES
+  const animateEntries = showIntro && !revealOnScroll
+
+  // Rail-synced fades for long timelines: entries render hidden and
+  // each one fades in the moment the rail tip (--lifeline-intro-progress,
+  // written every frame by the intro scroll) crosses its position —
+  // desktop's choreography, but each entry drops its animation (and
+  // compositor layer) as soon as its fade finishes.
+  useEffect(() => {
+    if (!showIntro || !revealOnScroll) return
+    const section = sectionRef.current
+    const ol = section?.querySelector("ol")
+    if (!section || !ol) return
+
+    const entries = Array.from(ol.children) as HTMLElement[]
+    const targets = entries.map(
+      (li) => li.firstElementChild as HTMLElement | null,
+    )
+
+    const onAnimationEnd = (event: AnimationEvent) => {
+      if (event.animationName !== "lifeline-marker-in") return
+      ;(event.target as HTMLElement).classList.remove("lifeline-marker-intro")
+    }
+    section.addEventListener("animationend", onAnimationEnd)
+
+    let next = 0
+    let frame = 0
+    const tick = () => {
+      const progress = parseFloat(
+        section.style.getPropertyValue("--lifeline-intro-progress") || "0",
+      )
+      const tip = progress * ol.offsetHeight
+
+      while (next < entries.length && entries[next].offsetTop <= tip) {
+        const el = targets[next]
+        if (el) {
+          el.classList.remove("opacity-0")
+          el.classList.add("lifeline-marker-intro")
+        }
+        next++
+      }
+
+      if (next < entries.length) {
+        frame = requestAnimationFrame(tick)
+      }
+    }
+    frame = requestAnimationFrame(tick)
+
+    return () => {
+      cancelAnimationFrame(frame)
+      section.removeEventListener("animationend", onAnimationEnd)
+      targets.forEach((el) => {
+        el?.classList.remove("opacity-0", "lifeline-marker-intro")
+      })
+    }
+  }, [showIntro, revealOnScroll, sectionRef])
+
+  const introStyle = {
+    "--lifeline-labels-ms": `${intro.labelsDuration}ms`,
+    "--lifeline-rail-ms": `${intro.railDuration}ms`,
+  } as CSSProperties
+
+  return (
+    <article
+      ref={sectionRef}
+      aria-label={title}
+      className={cn(
+        "relative select-none px-6 pb-10 pt-4 [&_a]:cursor-pointer",
+        !isLayoutReady && "invisible",
+      )}
+      style={showIntro ? introStyle : undefined}
+    >
+      <div className={cn(`${GRID_CLASS} mb-6 items-end`, showIntro && "lifeline-labels-intro")}>
+        <p className="text-right text-[11px] font-medium leading-4 tracking-[0.08em] text-fg-tertiary transition-colors duration-300">
+          Age
+        </p>
+        <div aria-hidden="true" />
+        <p className="text-[11px] font-medium leading-5 tracking-[0.08em] text-fg-tertiary transition-colors duration-300">
+          Years
+        </p>
+      </div>
+
+      <div className="relative">
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute bottom-0 top-0 overflow-hidden -translate-x-1/2"
+          style={{ left: RAIL_LEFT, width: 1 }}
+        >
+          <div
+            className={cn(
+              "h-full w-px border-l border-dashed border-border-primary transition-colors duration-300",
+              showIntro && "lifeline-rail-intro-vertical",
+            )}
+          />
+        </div>
+
+        <ol className="relative">
+          {markers.map((marker, index) => (
+            <LifelineVerticalEntry
+              key={marker.id}
+              ref={(node) => setEntryRef(index, node)}
+              marker={marker}
+              birthYear={birthYear}
+              animateIntro={animateEntries}
+              revealPending={showIntro && revealOnScroll}
+              introDelay={intro.getMarkerDelay(index)}
+              introDuration={intro.getMarkerFadeDuration(index)}
+            />
+          ))}
+        </ol>
+      </div>
+    </article>
+  )
+}

package/src/lifeline/lifeline.tsx

@@ -0,0 +1,69 @@
+"use client"
+
+import { useLayoutEffect, useState } from "react"
+import { cn } from "../lib/cn"
+import { LifelineDesktop } from "./lifeline-desktop"
+import { LifelineFireworksProvider } from "./lifeline-fireworks"
+import { LifelineVertical } from "./lifeline-vertical"
+import { LIFELINE_MOBILE_BREAKPOINT } from "./lifeline-layout"
+import type { LifelineProps } from "./types"
+
+/**
+ * `lifeline-typeset` sets `--lifeline-font` from the host sans stack.
+ * Override `--lifeline-font` to typeset the timeline in something else.
+ */
+export function Lifeline(props: LifelineProps) {
+  const [isMobile, setIsMobile] = useState<boolean | null>(null)
+
+  useLayoutEffect(() => {
+    // Matches Tailwind's md: breakpoint so JS and CSS can never disagree.
+    const query = window.matchMedia(
+      `(min-width: ${LIFELINE_MOBILE_BREAKPOINT}px)`,
+    )
+    const update = () => setIsMobile(!query.matches)
+
+    update()
+    query.addEventListener("change", update)
+    return () => query.removeEventListener("change", update)
+  }, [])
+
+  if (isMobile === null) {
+    return <div className="invisible h-full" aria-hidden="true" />
+  }
+
+  if (isMobile) {
+    return (
+      <LifelineFireworksProvider>
+        {/*
+          Embedded, the vertical timeline gets its own bounded scroller:
+          the consumer's height lands here, and this element becomes the
+          scroll parent the vertical hook looks for. Native overscroll
+          chaining then releases to the page at either end, which is
+          exactly the embed contract. Page mode is left alone — the host's
+          own scroller owns it there, and `h-full` would only fight it.
+        */}
+        <div
+          className={
+            props.mode === "embed"
+              ? cn(
+                  "lifeline-typeset h-full overflow-y-auto pt-5",
+                  props.className,
+                )
+              : "lifeline-typeset pt-5"
+          }
+        >
+          <LifelineVertical {...props} />
+        </div>
+      </LifelineFireworksProvider>
+    )
+  }
+
+  return (
+    <LifelineFireworksProvider>
+      <LifelineDesktop
+        {...props}
+        className={cn("lifeline-typeset pt-5", props.className)}
+      />
+    </LifelineFireworksProvider>
+  )
+}

package/src/lifeline/types.ts

@@ -0,0 +1,112 @@
+import type { CompanyIconId } from "./company-icon"
+
+
+export interface LifelineMentor {
+  name: string
+  role?: string
+  color?: string
+  photo?: string
+}
+
+export interface LifelineMetPerson {
+  name: string
+  photo?: string
+}
+
+export interface LifelineCompany {
+  id: CompanyIconId
+  name: string
+}
+
+export type LifelineEventSegment =
+  | { type: "text"; value: string }
+  | { type: "link"; value: string; href: string }
+
+export interface LifelineEventImage {
+  src: string
+  alt: string
+  /** Optional mp4/webm — hover shows this (muted, looping) with src as fallback. */
+  video?: string
+}
+
+/**
+ * An always-visible photo/video card that floats over the timeline,
+ * anchored to its marker's position and scrolling with the track —
+ * scattered, tilted, and draggable, like photos loose in a notebook.
+ */
+export interface LifelinePhoto extends LifelineEventImage {
+  /** 0..1 across the marker's slot; defaults to a seeded scatter. */
+  x?: number
+  /** Pixels below the rail; defaults to a seeded scatter. */
+  y?: number
+  /** Degrees; defaults to a seeded tilt. */
+  rotate?: number
+  /** Card width in pixels. Default 180. */
+  width?: number
+}
+
+export type LifelineEventEffect = "fireworks" | "fireworks-argentina"
+
+/**
+ * Object form lets an event carry a cursor-following hover image
+ * and/or a click-triggered easter egg effect.
+ */
+export interface LifelineEventObject {
+  text: string | LifelineEventSegment[]
+  image?: LifelineEventImage
+  effect?: LifelineEventEffect
+}
+
+export type LifelineEvent =
+  | string
+  | LifelineEventSegment[]
+  | LifelineEventObject
+
+export interface LifelineMarker {
+  id: string
+  /** Position on the numeric axis — a year, or any sequential unit (e.g. tournament day). */
+  year: number
+  /** Shown above the label; defaults to year - birthYear. Strings allowed for round tags etc. */
+  age?: number | string
+  /** Shown in place of the raw year — e.g. "Jun 16" on a day-based timeline. */
+  label?: string
+  events: LifelineEvent[]
+  /** Small emblems (team shields etc.) rendered above the events. */
+  badges?: { src: string; alt: string }[]
+  /** Floating media cards anchored to this marker's stretch of the timeline. */
+  photos?: LifelinePhoto[]
+  companies?: LifelineCompany[]
+  mentors?: LifelineMentor[]
+  met?: LifelineMetPerson[]
+}
+
+/**
+ * A legend entry maps one of the two people slots to a subject-appropriate
+ * label — "Mentors" for a person, "Presidents" for a nation.
+ */
+export interface LifelineLegendItem {
+  type: "mentor" | "met"
+  label: string
+}
+
+/**
+ * How the timeline relates to the page around it.
+ *
+ * - `"page"` — the Lifeline *is* the page. It owns the wheel and the
+ *   arrow keys, and nothing scrolls behind it.
+ * - `"embed"` — the Lifeline is one module in a scrolling page. Wheel
+ *   over it scrubs the rail, and at either end of the rail the wheel is
+ *   handed back so the page carries on scrolling.
+ * - `"auto"` — measured at runtime: page mode only when the timeline
+ *   covers most of the viewport *and* there is nothing behind it left to
+ *   scroll. Anything else is treated as embedded.
+ */
+export type LifelineMode = "auto" | "page" | "embed"
+
+export interface LifelineProps {
+  markers: LifelineMarker[]
+  birthYear: number
+  className?: string
+  title?: string
+  mode?: LifelineMode
+}