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

package/src/lifeline/use-lifeline-vertical-scroll.ts

@@ -0,0 +1,271 @@
+"use client"
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react"
+import { clamp } from "./lifeline-utils"
+
+function getScrollParent(element: HTMLElement | null): HTMLElement | null {
+  let node = element?.parentElement ?? null
+
+  while (node) {
+    const { overflowY } = window.getComputedStyle(node)
+    if (overflowY === "auto" || overflowY === "scroll" || overflowY === "overlay") {
+      return node
+    }
+    node = node.parentElement
+  }
+
+  // Nothing on the way up scrolls, so the document does — which is the
+  // ordinary case for a page-mode timeline in a page that just scrolls.
+  // Returning null here left the whole rail `invisible` with no error.
+  return (document.scrollingElement as HTMLElement | null) ?? null
+}
+
+interface LifelineVerticalScrollOptions {
+  /**
+   * Embedded, the timeline opens at its start rather than where a skipped
+   * intro would have settled it — the reader is arriving at a module in a
+   * page, not returning to a timeline that already played.
+   */
+  isEmbed?: boolean
+  introLocked?: boolean
+  introAnimating?: boolean
+  introSkipped?: boolean
+  introRailMs?: number
+  introGetTrackProgress?: (elapsedMs: number) => number
+  onIntroSettleComplete?: () => void
+  onIntroScrollStart?: () => void
+}
+
+export function useLifelineVerticalScroll(
+  markerCount: number,
+  options: LifelineVerticalScrollOptions = {},
+) {
+  const sectionRef = useRef<HTMLElement>(null)
+  const entryRefs = useRef<(HTMLLIElement | null)[]>([])
+  const maxScrollRef = useRef(0)
+  const scrollParentRef = useRef<HTMLElement | null>(null)
+  const initialized = useRef(false)
+  const introLockedRef = useRef(options.introLocked ?? false)
+  const introAnimatingRef = useRef(options.introAnimating ?? false)
+  const introSkippedRef = useRef(options.introSkipped ?? false)
+  const isEmbedRef = useRef(options.isEmbed ?? false)
+  const onIntroSettleCompleteRef = useRef(options.onIntroSettleComplete)
+  const onIntroScrollStartRef = useRef(options.onIntroScrollStart)
+  const introGetTrackProgressRef = useRef(options.introGetTrackProgress)
+  const introStartedRef = useRef(false)
+  const introScrollId = useRef(0)
+  const introScrollStart = useRef(0)
+  const introWasAnimatingRef = useRef(false)
+  const scheduleMeasureRef = useRef<() => void>(() => {})
+  const [isLayoutReady, setIsLayoutReady] = useState(false)
+
+  introLockedRef.current = options.introLocked ?? false
+  introAnimatingRef.current = options.introAnimating ?? false
+  introSkippedRef.current = options.introSkipped ?? false
+  isEmbedRef.current = options.isEmbed ?? false
+  onIntroSettleCompleteRef.current = options.onIntroSettleComplete
+  onIntroScrollStartRef.current = options.onIntroScrollStart
+  introGetTrackProgressRef.current = options.introGetTrackProgress
+
+  const setEntryRef = useCallback((index: number, node: HTMLLIElement | null) => {
+    entryRefs.current[index] = node
+
+    if (index === markerCount - 1 && node) {
+      scheduleMeasureRef.current()
+    }
+  }, [markerCount])
+
+  const applyScroll = useCallback((value: number) => {
+    const scrollParent = scrollParentRef.current
+    if (!scrollParent) return
+
+    scrollParent.scrollTop = clamp(value, 0, maxScrollRef.current)
+  }, [])
+
+  const measureLayout = useCallback(() => {
+    const section = sectionRef.current
+    if (!section) return 0
+
+    const scrollParent = getScrollParent(section)
+    scrollParentRef.current = scrollParent
+
+    if (!scrollParent) return 0
+
+    const heights = entryRefs.current.map((entry) => entry?.offsetHeight ?? 0)
+    if (heights.length < markerCount || heights.some((height) => height <= 0)) {
+      return 0
+    }
+
+    const max = Math.max(0, scrollParent.scrollHeight - scrollParent.clientHeight)
+    maxScrollRef.current = max
+
+    return max
+  }, [markerCount])
+
+  useLayoutEffect(() => {
+    entryRefs.current.length = markerCount
+  }, [markerCount])
+
+  useLayoutEffect(() => {
+    const max = measureLayout()
+
+    const scrollParent = scrollParentRef.current
+    if (!scrollParent) return
+
+    if (!initialized.current) {
+      scrollParent.scrollTop =
+        introSkippedRef.current && !isEmbedRef.current ? max : 0
+      initialized.current = true
+    }
+
+    setIsLayoutReady(entryRefs.current.every((entry) => Boolean(entry)))
+    // Sync initial position once before first paint; resize uses measure().
+  }, [])
+
+  useEffect(() => {
+    if (!isLayoutReady) return
+    if (options.introSkipped || !options.introAnimating) {
+      cancelAnimationFrame(introScrollId.current)
+      introScrollId.current = 0
+      introStartedRef.current = false
+      return
+    }
+
+    introWasAnimatingRef.current = true
+    const railMs = options.introRailMs ?? 3200
+
+    const step = (now: number) => {
+      const max = maxScrollRef.current
+
+      if (!introStartedRef.current) {
+        introStartedRef.current = true
+        introScrollStart.current = now
+        onIntroScrollStartRef.current?.()
+        sectionRef.current?.style.setProperty("--lifeline-intro-progress", "0")
+        if (max > 0) applyScroll(0)
+      }
+
+      const elapsed = now - introScrollStart.current
+      const progress = introGetTrackProgressRef.current
+        ? clamp(introGetTrackProgressRef.current(elapsed), 0, 1)
+        : clamp(elapsed / railMs, 0, 1)
+
+      sectionRef.current?.style.setProperty(
+        "--lifeline-intro-progress",
+        String(progress),
+      )
+
+      if (max > 0) {
+        applyScroll(progress * max)
+      }
+
+      if (progress < 1) {
+        introScrollId.current = requestAnimationFrame(step)
+        return
+      }
+
+      sectionRef.current?.style.setProperty("--lifeline-intro-progress", "1")
+      if (max > 0) applyScroll(max)
+      introScrollId.current = 0
+    }
+
+    introScrollId.current = requestAnimationFrame(step)
+
+    return () => {
+      cancelAnimationFrame(introScrollId.current)
+      introScrollId.current = 0
+      introStartedRef.current = false
+    }
+  }, [
+    applyScroll,
+    isLayoutReady,
+    options.introAnimating,
+    options.introRailMs,
+    options.introSkipped,
+  ])
+
+  useEffect(() => {
+    if (options.introSkipped) return
+    if (options.introAnimating) return
+    if (!introWasAnimatingRef.current) return
+
+    introWasAnimatingRef.current = false
+    sectionRef.current?.style.removeProperty("--lifeline-intro-progress")
+    onIntroSettleCompleteRef.current?.()
+  }, [options.introAnimating, options.introSkipped])
+
+  useEffect(() => {
+    const section = sectionRef.current
+    if (!section) return
+
+    let frameId = 0
+    let resizeObserver: ResizeObserver | null = null
+
+    const measure = () => {
+      measureLayout()
+
+      const scrollParent = scrollParentRef.current
+      if (!scrollParent) return
+
+      if (!(introAnimatingRef.current && introStartedRef.current)) {
+        scrollParent.scrollTop = clamp(
+          scrollParent.scrollTop,
+          0,
+          maxScrollRef.current,
+        )
+      }
+
+      setIsLayoutReady(
+        entryRefs.current.length === markerCount &&
+          entryRefs.current.every((entry) => Boolean(entry)),
+      )
+    }
+
+    const scheduleMeasure = () => {
+      cancelAnimationFrame(frameId)
+      frameId = requestAnimationFrame(measure)
+    }
+
+    scheduleMeasureRef.current = scheduleMeasure
+
+    scheduleMeasure()
+    frameId = requestAnimationFrame(() => {
+      measure()
+      requestAnimationFrame(measure)
+    })
+
+    resizeObserver = new ResizeObserver(scheduleMeasure)
+    resizeObserver.observe(section)
+
+    window.addEventListener("resize", scheduleMeasure)
+
+    const isScrollLocked = () =>
+      introLockedRef.current && introStartedRef.current
+
+    const preventScroll = (event: Event) => {
+      if (!isScrollLocked()) return
+      event.preventDefault()
+    }
+
+    const scrollParent = getScrollParent(section)
+    scrollParentRef.current = scrollParent
+
+    scrollParent?.addEventListener("wheel", preventScroll, { passive: false })
+    scrollParent?.addEventListener("touchmove", preventScroll, { passive: false })
+
+    return () => {
+      cancelAnimationFrame(frameId)
+      resizeObserver?.disconnect()
+      window.removeEventListener("resize", scheduleMeasure)
+      scrollParent?.removeEventListener("wheel", preventScroll)
+      scrollParent?.removeEventListener("touchmove", preventScroll)
+      initialized.current = false
+    }
+  }, [markerCount, measureLayout])
+
+  return {
+    sectionRef,
+    setEntryRef,
+    isLayoutReady,
+  }
+}

package/src/menubar.tsx

@@ -10,9 +10,16 @@ export const Menubar = ({ className, ...props }: MenubarProps) => (
   <BaseMenubar
     className={cn(
       "inline-flex items-center gap-0.5 rounded-lg border border-border-primary bg-background-secondary p-0.5",
-      "[&_button]:inline-flex [&_button]:h-8 [&_button]:cursor-pointer [&_button]:items-center [&_button]:justify-center [&_button]:gap-1.5 [&_button]:rounded-md [&_button]:px-2.5 [&_button]:text-sm [&_button]:text-fg-secondary [&_button]:outline-none",
+      // Base UI sets data-orientation and handles the arrow keys, but the
+      // layout is ours: without this a vertical menubar still renders as a
+      // row, so the prop looks supported and does nothing.
+      "data-[orientation=vertical]:flex-col data-[orientation=vertical]:items-stretch",
+      "data-[orientation=vertical]:[&_button]:justify-start",
+      "[&_button]:inline-flex [&_button]:h-8 [&_button]:cursor-pointer [&_button]:items-center [&_button]:justify-center [&_button]:gap-1.5 [&_button]:rounded-md [&_button]:px-2.5 [&_button]:text-sm [&_button]:text-fg-secondary",
+      // focusRingBorder + focusRing, scoped to child Menu triggers
+      "[&_button]:border [&_button]:border-transparent",
+      "[&_button]:outline-none [&_button]:focus-visible:border-ring [&_button]:focus-visible:ring-[3px] [&_button]:focus-visible:ring-offset-1 [&_button]:focus-visible:ring-offset-background-primary [&_button]:focus-visible:ring-ring/20",
       "[&_button]:hover:bg-background-tertiary [&_button]:hover:text-fg-primary",
-      "[&_button]:focus-visible:border-ring [&_button]:focus-visible:ring-[3px] [&_button]:focus-visible:ring-offset-1 [&_button]:focus-visible:ring-offset-background-primary [&_button]:focus-visible:ring-ring/20",
       "[&_button]:data-popup-open:bg-background-tertiary [&_button]:data-popup-open:text-fg-primary",
       "[&_button]:data-disabled:cursor-not-allowed [&_button]:data-disabled:opacity-50",
       className,

package/src/minimap.tsx

@@ -0,0 +1,296 @@
+"use client"
+
+import { cva, type VariantProps } from "class-variance-authority"
+import {
+  type ComponentProps,
+  type FocusEvent,
+  type KeyboardEvent,
+  type MouseEvent,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react"
+import { cn } from "./lib/cn"
+import {
+  Tooltip,
+  TooltipPopup,
+  TooltipPortal,
+  TooltipPositioner,
+  TooltipProvider,
+  TooltipTrigger,
+} from "./tooltip"
+
+const minimapVariants = cva("z-20 w-8", {
+  variants: {
+    position: {
+      fixed:
+        "fixed left-10 top-1/2 max-h-[min(70vh,32.5rem)] -translate-y-1/2 max-[1120px]:hidden",
+      inline: "relative",
+    },
+  },
+  defaultVariants: {
+    position: "fixed",
+  },
+})
+
+export type MinimapSection = {
+  /** The id of the section heading or landmark to scroll to. */
+  id: string
+  /** The accessible name and tooltip shown for the section. */
+  label: string
+}
+
+export type MinimapProps = Omit<ComponentProps<"nav">, "children"> &
+  VariantProps<typeof minimapVariants> & {
+    /** Ordered destinations represented by the ticks. */
+    sections: readonly MinimapSection[]
+    /** Controlled active section id. */
+    activeId?: string | null
+    /** Initial active section id when uncontrolled. */
+    defaultActiveId?: string | null
+    /** Called when observation or selection changes the active section. */
+    onActiveChange?: (id: string) => void
+    /** Optional scroll container used by the section observer. */
+    root?: Element | Document | null
+    /** Intersection observer margin used to choose the active section. */
+    rootMargin?: string
+    /** Scroll behavior used after a tick is selected. */
+    scrollBehavior?: ScrollBehavior
+    /** Delay before a section label appears on hover, in milliseconds. */
+    tooltipDelay?: number
+  }
+
+export const Minimap = ({
+  sections,
+  activeId,
+  defaultActiveId,
+  onActiveChange,
+  root = null,
+  rootMargin = "-20% 0px -68% 0px",
+  scrollBehavior = "smooth",
+  tooltipDelay = 100,
+  position,
+  className,
+  "aria-label": ariaLabel = "Page sections",
+  ...props
+}: MinimapProps) => {
+  const [uncontrolledActiveId, setUncontrolledActiveId] = useState<
+    string | null
+  >(() => defaultActiveId ?? sections[0]?.id ?? null)
+  const currentActiveId =
+    activeId !== undefined ? activeId : uncontrolledActiveId
+  const activeIndex = sections.findIndex(
+    (section) => section.id === currentActiveId,
+  )
+  const tabbableIndex = activeIndex >= 0 ? activeIndex : 0
+  const currentActiveIdRef = useRef(currentActiveId)
+  const [pointerIndex, setPointerIndex] = useState<number | null>(null)
+  const [focusIndex, setFocusIndex] = useState<number | null>(null)
+  const emphasizedIndex = pointerIndex ?? focusIndex
+
+  const handleListMouseLeave = () => setPointerIndex(null)
+
+  const handleListBlur = (event: FocusEvent<HTMLOListElement>) => {
+    const next = event.relatedTarget
+    if (next instanceof Node && event.currentTarget.contains(next)) return
+    setFocusIndex(null)
+  }
+
+  useEffect(() => {
+    currentActiveIdRef.current = currentActiveId
+  }, [currentActiveId])
+
+  const commitActiveId = useCallback(
+    (nextId: string) => {
+      const changed = currentActiveIdRef.current !== nextId
+      currentActiveIdRef.current = nextId
+
+      if (activeId === undefined) setUncontrolledActiveId(nextId)
+      if (changed) onActiveChange?.(nextId)
+    },
+    [activeId, onActiveChange],
+  )
+
+  useEffect(() => {
+    const elements = sections
+      .map((section) => document.getElementById(section.id))
+      .filter((element): element is HTMLElement => Boolean(element))
+
+    if (!elements.length) return
+
+    const getActiveElementId = () => {
+      const rootRect =
+        root instanceof Element ? root.getBoundingClientRect() : null
+      const activationLine = rootRect
+        ? rootRect.top + rootRect.height * 0.2
+        : window.innerHeight * 0.2
+      let nextId = elements[0]?.id
+
+      elements.forEach((element) => {
+        if (element.getBoundingClientRect().top <= activationLine) {
+          nextId = element.id
+        }
+      })
+
+      return nextId
+    }
+
+    const observer = new IntersectionObserver(
+      () => {
+        const nextId = getActiveElementId()
+        if (nextId) commitActiveId(nextId)
+      },
+      {
+        root,
+        rootMargin,
+        threshold: [0, 0.1, 1],
+      },
+    )
+
+    elements.forEach((element) => observer.observe(element))
+
+    const frame = requestAnimationFrame(() => {
+      const nextId = getActiveElementId()
+      if (nextId) commitActiveId(nextId)
+    })
+
+    return () => {
+      cancelAnimationFrame(frame)
+      observer.disconnect()
+    }
+  }, [commitActiveId, root, rootMargin, sections])
+
+  const selectSection = useCallback(
+    (section: MinimapSection) => {
+      const target = document.getElementById(section.id)
+      if (!target) return
+
+      commitActiveId(section.id)
+      const prefersReducedMotion = window.matchMedia(
+        "(prefers-reduced-motion: reduce)",
+      ).matches
+
+      const behavior = prefersReducedMotion ? "auto" : scrollBehavior
+
+      if (root instanceof Element) {
+        const rootRect = root.getBoundingClientRect()
+        const targetRect = target.getBoundingClientRect()
+        const scrollMarginTop = Number.parseFloat(
+          getComputedStyle(target).scrollMarginTop,
+        )
+
+        root.scrollTo({
+          top:
+            root.scrollTop +
+            targetRect.top -
+            rootRect.top -
+            (Number.isFinite(scrollMarginTop) ? scrollMarginTop : 0),
+          behavior,
+        })
+        return
+      }
+
+      target.scrollIntoView({ behavior, block: "start" })
+    },
+    [commitActiveId, root, scrollBehavior],
+  )
+
+  const handleKeyDown = (
+    event: KeyboardEvent<HTMLButtonElement>,
+    index: number,
+  ) => {
+    let nextIndex: number | null = null
+
+    if (event.key === "ArrowDown") nextIndex = Math.min(index + 1, sections.length - 1)
+    if (event.key === "ArrowUp") nextIndex = Math.max(index - 1, 0)
+    if (event.key === "Home") nextIndex = 0
+    if (event.key === "End") nextIndex = sections.length - 1
+    if (nextIndex === null || nextIndex === index) return
+
+    event.preventDefault()
+    const nextSection = sections[nextIndex]
+    const buttons = event.currentTarget
+      .closest("ol")
+      ?.querySelectorAll<HTMLButtonElement>("[data-minimap-mark]")
+
+    buttons?.[nextIndex]?.focus()
+    if (nextSection) selectSection(nextSection)
+  }
+
+  if (sections.length < 2) return null
+
+  return (
+    <TooltipProvider delay={tooltipDelay}>
+      <nav
+        aria-label={ariaLabel}
+        className={cn(minimapVariants({ position }), className)}
+        {...props}
+      >
+        <ol
+          className="flex max-h-[min(70vh,32.5rem)] w-full list-none flex-col items-start justify-center gap-0.5 p-0"
+          onMouseLeave={handleListMouseLeave}
+          onBlur={handleListBlur}
+        >
+          {sections.map((section, index) => {
+            const isActive = section.id === currentActiveId
+            const isEmphasized = index === emphasizedIndex
+            const isNeighbor =
+              emphasizedIndex !== null &&
+              Math.abs(index - emphasizedIndex) === 1
+
+            return (
+              <li
+                key={section.id}
+                className="relative flex w-full shrink-0 justify-start"
+                onMouseEnter={() => setPointerIndex(index)}
+              >
+                <Tooltip>
+                  <TooltipTrigger
+                    render={
+                      <button
+                        type="button"
+                        aria-label={section.label}
+                        aria-current={isActive ? "location" : undefined}
+                        data-minimap-mark
+                        tabIndex={index === tabbableIndex ? 0 : -1}
+                        className="flex h-2 w-full cursor-pointer items-center justify-start border-0 bg-transparent p-0 outline-none"
+                        onClick={(event: MouseEvent<HTMLButtonElement>) => {
+                          selectSection(section)
+                          if (event.detail > 0) event.currentTarget.blur()
+                        }}
+                        onFocus={() => setFocusIndex(index)}
+                        onKeyDown={(event: KeyboardEvent<HTMLButtonElement>) =>
+                          handleKeyDown(event, index)
+                        }
+                      >
+                        <span
+                          aria-hidden
+                          className={cn(
+                            "block h-0.5 w-2 origin-left rounded-full bg-fg-primary/20",
+                            "transition-[width,background-color] duration-[var(--duration-sm)] ease-enter motion-reduce:transition-none",
+                            isEmphasized && "w-6 bg-fg-primary",
+                            isNeighbor && "w-4",
+                          )}
+                        />
+                      </button>
+                    }
+                  />
+                  <TooltipPortal>
+                    <TooltipPositioner side="right" sideOffset={14}>
+                      <TooltipPopup className="font-medium">
+                        {section.label}
+                      </TooltipPopup>
+                    </TooltipPositioner>
+                  </TooltipPortal>
+                </Tooltip>
+              </li>
+            )
+          })}
+        </ol>
+      </nav>
+    </TooltipProvider>
+  )
+}
+
+export { minimapVariants }