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

package/src/lifeline/index.ts

@@ -0,0 +1,42 @@
+export { Lifeline } from "./lifeline"
+export { LifelineMarkerColumn } from "./lifeline-marker"
+export { useLifelineScroll } from "./use-lifeline-scroll"
+export {
+  CompanyIcon,
+  registerCompanyIcons,
+  type CompanyIconEntry,
+  type CompanyIconId,
+} from "./company-icon"
+export { LifelineLegend } from "./lifeline-legend"
+export {
+  LifelineShell,
+  LifelineNav,
+  LifelineStage,
+  LifelineFooter,
+} from "./lifeline-shell"
+export {
+  defineLifeline,
+  localizeLifelineMarkers,
+  LIFELINE_CURRENT_YEAR,
+  type LifelineBirthday,
+  type LifelineMilestone,
+  type LifelineMilestones,
+  type LifelineRecord,
+  type LifelineTextOverrides,
+} from "./lifeline-data"
+
+export type {
+  LifelineCompany,
+  LifelineEvent,
+  LifelineEventEffect,
+  LifelineEventImage,
+  LifelineEventObject,
+  LifelineEventSegment,
+  LifelineLegendItem,
+  LifelineMarker,
+  LifelineMetPerson,
+  LifelineMentor,
+  LifelineMode,
+  LifelinePhoto,
+  LifelineProps,
+} from "./types"

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("")}`
+}