@passui/react 0.1.17 → 0.1.20

package/src/components/tooltip/tooltip-host.tsx

@@ -1,6 +1,6 @@
-import { AnimatePresence, motion } from "motion/react"
+import { AnimatePresence, motion, useReducedMotion } from "motion/react"
 import { spring } from "../../motion/transitions"
-import { useEffect, useState } from "react"
+import { useEffect, useId, useState } from "react"
 
 interface Tip {
     text: string
@@ -22,30 +22,33 @@ const MARGIN = 8
  */
 export function TooltipHost() {
     const [tip, setTip] = useState<Tip | null>(null)
+    const tooltipId = useId()
+    const reducedMotion = useReducedMotion()
 
     useEffect(() => {
-        if (
-            !window.matchMedia(
-                "(hover: hover) and (pointer: fine)"
-            ).matches
-        )
-            return
+        const canHover = window.matchMedia("(hover: hover) and (pointer: fine)").matches
         let timer: ReturnType<typeof setTimeout> | undefined
         let current: Element | null = null
         let lastShown = 0
+        let described: Element | null = null
+        let previousDescription: string | null = null
+
+        const restoreDescription = () => {
+            if (!described) return
+            if (previousDescription === null) described.removeAttribute("aria-describedby")
+            else described.setAttribute("aria-describedby", previousDescription)
+            described = null
+        }
 
         const show = (element: Element) => {
             const text = element.getAttribute("data-tooltip")
             if (!text) return
             const rect = element.getBoundingClientRect()
-            const above =
-                rect.bottom + 40 > window.innerHeight
+            const above = rect.bottom + 40 > window.innerHeight
             setTip({
                 text,
                 x: rect.left + rect.width / 2,
-                y: above
-                    ? rect.top - MARGIN
-                    : rect.bottom + MARGIN,
+                y: above ? rect.top - MARGIN : rect.bottom + MARGIN,
                 above,
             })
             lastShown = Date.now()
@@ -54,13 +57,12 @@ export function TooltipHost() {
             clearTimeout(timer)
             if (current) lastShown = Date.now()
             current = null
+            restoreDescription()
             setTip(null)
         }
         const onOver = (event: PointerEvent) => {
-            const element =
-                (event.target as Element | null)?.closest?.(
-                    "[data-tooltip]"
-                ) ?? null
+            if (!canHover) return
+            const element = (event.target as Element | null)?.closest?.("[data-tooltip]") ?? null
             if (element === current) return
             clearTimeout(timer)
             current = element
@@ -72,80 +74,81 @@ export function TooltipHost() {
             if (warm) show(element)
             else {
                 setTip(null)
-                timer = setTimeout(
-                    () =>
-                        current === element && show(element),
-                    DELAY
-                )
+                timer = setTimeout(() => current === element && show(element), DELAY)
             }
         }
+        const onFocus = (event: FocusEvent) => {
+            const element = (event.target as Element | null)?.closest?.("[data-tooltip]") ?? null
+            if (!element) return
+            hide()
+            current = element
+            described = element
+            previousDescription = element.getAttribute("aria-describedby")
+            element.setAttribute(
+                "aria-describedby",
+                [previousDescription, tooltipId].filter(Boolean).join(" ")
+            )
+            show(element)
+        }
+        const onBlur = (event: FocusEvent) => {
+            if (described && !described.contains(event.relatedTarget as Node | null)) hide()
+        }
 
-        window.document.addEventListener(
-            "pointerover",
-            onOver
-        )
-        window.document.addEventListener(
-            "pointerdown",
-            hide,
-            true
-        )
-        window.document.addEventListener(
-            "keydown",
-            hide,
-            true
-        )
+        window.document.addEventListener("pointerover", onOver)
+        window.document.addEventListener("focusin", onFocus)
+        window.document.addEventListener("focusout", onBlur)
+        window.document.addEventListener("pointerdown", hide, true)
+        window.document.addEventListener("keydown", hide, true)
         window.addEventListener("scroll", hide, true)
         window.addEventListener("blur", hide)
         return () => {
             clearTimeout(timer)
-            window.document.removeEventListener(
-                "pointerover",
-                onOver
-            )
-            window.document.removeEventListener(
-                "pointerdown",
-                hide,
-                true
-            )
-            window.document.removeEventListener(
-                "keydown",
-                hide,
-                true
-            )
+            restoreDescription()
+            window.document.removeEventListener("pointerover", onOver)
+            window.document.removeEventListener("focusin", onFocus)
+            window.document.removeEventListener("focusout", onBlur)
+            window.document.removeEventListener("pointerdown", hide, true)
+            window.document.removeEventListener("keydown", hide, true)
             window.removeEventListener("scroll", hide, true)
             window.removeEventListener("blur", hide)
         }
-    }, [])
+    }, [tooltipId])
 
     return (
         <AnimatePresence>
             {tip && (
                 <motion.div
+                    id={tooltipId}
                     key={tip.text + tip.x}
                     role="tooltip"
                     className="pointer-events-none fixed z-[80] max-w-[240px] rounded-md bg-inverse px-2.5 py-1.5 text-center text-caption leading-tight font-medium text-on-inverse shadow-lg"
                     style={{
-                        left: Math.min(
-                            Math.max(tip.x, 128),
-                            window.innerWidth - 128
-                        ),
+                        left: Math.min(Math.max(tip.x, 128), window.innerWidth - 128),
                         top: tip.y,
                         translateX: "-50%",
                         translateY: tip.above ? "-100%" : 0,
                     }}
-                    initial={{
-                        opacity: 0,
-                        scale: 0.92,
-                        y: tip.above ? 4 : -4,
-                    }}
+                    initial={
+                        reducedMotion
+                            ? false
+                            : {
+                                  opacity: 0,
+                                  scale: 0.92,
+                                  y: tip.above ? 4 : -4,
+                              }
+                    }
                     animate={{ opacity: 1, scale: 1, y: 0 }}
-                    exit={{
-                        opacity: 0,
-                        scale: 0.96,
-                        y: tip.above ? 2 : -2,
-                        transition: spring.snappy,
-                    }}
-                    transition={spring.snappy}
+                    exit={
+                        reducedMotion
+                            ? { opacity: 0 }
+                            : {
+                                  opacity: 0,
+                                  scale: 0.96,
+                                  y: tip.above ? 2 : -2,
+                                  transition: spring.snappy,
+                              }
+                    }
+                    transition={reducedMotion ? { duration: 0 } : spring.snappy}
                 >
                     {tip.text}
                 </motion.div>

package/src/components/view-controller/view-controller.tsx

@@ -19,11 +19,7 @@ const titleSizes = {
     compact: "text-[1.75rem] font-semibold tracking-tight",
 } as const
 
-export function ViewController({
-    heading,
-    className,
-    children,
-}: ViewControllerProps) {
+export function ViewController({ heading, className, children }: ViewControllerProps) {
     return (
         <article
             className={cn(
@@ -38,12 +34,7 @@ export function ViewController({
     )
 }
 
-function Heading({
-    title,
-    description,
-    action,
-    size = "default",
-}: HeadingProps) {
+function Heading({ title, description, action, size = "default" }: HeadingProps) {
     const centered = size === "compact"
     return (
         <>
@@ -53,22 +44,14 @@ function Heading({
                     centered && "justify-center text-center"
                 )}
             >
-                <h1
-                    className={cn(
-                        "min-w-0 wrap-anywhere",
-                        titleSizes[size]
-                    )}
-                >
-                    {title}
-                </h1>
+                <h1 className={cn("min-w-0 wrap-anywhere", titleSizes[size])}>{title}</h1>
                 {action}
             </div>
             {description && (
                 <p
                     className={cn(
                         "mt-2 max-w-prose text-subheadline leading-relaxed text-label-secondary",
-                        centered &&
-                            "mt-1 text-center text-[15px]"
+                        centered && "mt-1 text-center text-[15px]"
                     )}
                 >
                     {description}

package/src/components/wake-slider/wake-slider.tsx

@@ -0,0 +1,237 @@
+import { clampRange as clamp } from "../../lib/range-value"
+// Adapted from Bencho. See THIRD_PARTY_NOTICES.md for the MIT notice.
+import { type CSSProperties, useEffect, useRef, useState } from "react"
+import { useMediaQuery } from "../../hooks/use-media-query"
+import { cn } from "../../lib/class-names"
+
+/* ══ Wake slider ══════════════════════════════════════════
+   A range with no thumb: a row of thin bars, solid up to the
+   value and faint after it, with the reading beside them. Drag
+   anywhere along it. Drag slowly and the bars simply fill; drag
+   fast and every bar the value sweeps past springs up, taller the
+   faster you went, and settles back — a wake left behind the hand.
+
+   ── EACH BAR HOLDS A LITTLE ENERGY ──────────────────────
+   When the value crosses a bar, that bar takes energy from the
+   speed of the drag. Every frame all of it decays at the same
+   rate, so the bars crossed longest ago have fallen furthest: the
+   tallest ones are always at the hand and the run tails off
+   behind it. That falloff IS the wake; nothing draws it.
+
+   ── WRITTEN, NOT RENDERED ───────────────────────────────
+   The heights change every frame, so they go straight onto each
+   bar's transform from a ref. React renders when the value
+   changes, which is what the reading and the colours need, and
+   the loop runs only while some bar still has energy. */
+
+const H = 20 // a bar at rest, px
+
+export interface WakeSliderProps {
+    label: string
+    value?: number
+    defaultValue?: number
+    onChange?: (value: number) => void
+    bars?: number
+    wake?: number
+    disabled?: boolean
+    className?: string
+    formatValue?: (value: number) => string
+}
+
+export function WakeSlider({
+    label,
+    value: controlledValue,
+    defaultValue = 50,
+    onChange,
+    disabled = false,
+    className,
+    formatValue,
+    /* how many bars make the track */
+    bars = 36,
+    /* how high the wake rises, 0..100 */
+    wake = 60,
+}: WakeSliderProps) {
+    const n = Math.round(clamp(Number.isFinite(bars) ? bars : 36, 12, 64))
+    const reduced = useMediaQuery("(prefers-reduced-motion: reduce)")
+    const [value, setValue] = useState(() => clamp(controlledValue ?? defaultValue, 0, 100))
+    const track = useRef<HTMLDivElement | null>(null)
+    const els = useRef<(HTMLSpanElement | null)[]>([])
+    const st = useRef({
+        energy: new Float32Array(n),
+        down: false,
+        lastX: 0,
+        lastT: 0,
+        speed: 0,
+        raf: 0,
+        at: value / 100, // the value as a fraction, without React in the way
+        lastBar: -1,
+    })
+    const knob = useRef(wake)
+    knob.current = reduced ? 0 : clamp(wake, 0, 100)
+    useEffect(() => {
+        if (controlledValue === undefined) return
+        const next = clamp(controlledValue, 0, 100)
+        st.current.at = next / 100
+        setValue(next)
+    }, [controlledValue])
+
+    useEffect(() => {
+        if (!reduced) return
+        cancelAnimationFrame(st.current.raf)
+        st.current.raf = 0
+        st.current.energy.fill(0)
+        for (const bar of els.current) if (bar) bar.style.transform = "none"
+    }, [reduced])
+
+    /* a new bar count is a new row */
+    useEffect(() => {
+        st.current.energy = new Float32Array(n)
+    }, [n])
+
+    const loop = () => {
+        const s = st.current
+        if (s.raf) return
+        let prev = performance.now()
+        const run = (now: number) => {
+            const dt = Math.min(0.05, (now - prev) / 1000)
+            prev = now
+            let live = false
+            const fall = Math.exp(-dt * 6.5)
+            for (let i = 0; i < s.energy.length; i++) {
+                s.energy[i] *= fall
+                if (s.energy[i] < 0.002) s.energy[i] = 0
+                else live = true
+                const b = els.current[i]
+                /* up to 2.6 times as tall at the very top of the knob */
+                if (b) b.style.transform = `scaleY(${(1 + s.energy[i] * 1.6).toFixed(3)})`
+            }
+            s.raf = live ? requestAnimationFrame(run) : 0
+        }
+        s.raf = requestAnimationFrame(run)
+    }
+
+    useEffect(() => () => cancelAnimationFrame(st.current.raf), [])
+
+    /* move the value to a fraction, waking every bar it passes */
+    const to = (f: number, speed: number) => {
+        const s = st.current
+        f = clamp(f, 0, 1)
+        const from = s.at
+        s.at = f
+        const a = Math.round(from * (n - 1)),
+            b = Math.round(f * (n - 1))
+        /* how hard: the drag's speed in bars per second, through a
+       curve that saturates, scaled by the knob */
+        const push = (1 - Math.exp(-speed / 900)) * (knob.current / 60)
+        const lo = Math.min(a, b),
+            hi = Math.max(a, b)
+        for (let i = lo; i <= hi; i++) s.energy[i] = Math.max(s.energy[i], push)
+        if (b !== s.lastBar) {
+            s.lastBar = b
+        }
+        const next = Math.round(f * 100)
+        setValue(next)
+        onChange?.(next)
+        if (!reduced && knob.current > 0) loop()
+    }
+
+    const frac = (clientX: number) => {
+        const r = track.current!.getBoundingClientRect()
+        const fraction = r.width ? (clientX - r.left) / r.width : 0
+        return getComputedStyle(track.current!).direction === "rtl" ? 1 - fraction : fraction
+    }
+
+    const lit = Math.round((value / 100) * (n - 1))
+
+    return (
+        <div className={cn("passui-wake-slider not-typeset", disabled && "opacity-40", className)}>
+            <div
+                ref={track}
+                className="passui-wake-track"
+                role="slider"
+                tabIndex={disabled ? -1 : 0}
+                aria-label={label}
+                aria-disabled={disabled || undefined}
+                aria-valuetext={formatValue?.(value)}
+                aria-valuemin={0}
+                aria-valuemax={100}
+                aria-valuenow={value}
+                style={{ height: H * 2.6, "--wake-bars": n } as CSSProperties}
+                onPointerDown={(e) => {
+                    if (disabled || e.button !== 0) return
+                    e.currentTarget.focus()
+                    const s = st.current
+                    try {
+                        e.currentTarget.setPointerCapture(e.pointerId)
+                    } catch {
+                        /* a scripted pointer */
+                    }
+                    s.down = true
+                    s.lastX = e.clientX
+                    s.lastT = performance.now()
+                    s.speed = 0
+                    to(frac(e.clientX), 0)
+                }}
+                onPointerMove={(e) => {
+                    const s = st.current
+                    if (!s.down || disabled) return
+                    const now = performance.now()
+                    const dt = Math.max(0.008, (now - s.lastT) / 1000)
+                    /* speed in px per second, smoothed so one jittery frame
+             cannot fake a fling */
+                    const v = Math.abs(e.clientX - s.lastX) / dt
+                    s.speed = s.speed * 0.5 + v * 0.5
+                    s.lastX = e.clientX
+                    s.lastT = now
+                    to(frac(e.clientX), s.speed)
+                }}
+                onPointerUp={(e) => {
+                    st.current.down = false
+                    try {
+                        e.currentTarget.releasePointerCapture(e.pointerId)
+                    } catch {
+                        /* never captured */
+                    }
+                }}
+                onLostPointerCapture={() => {
+                    st.current.down = false
+                }}
+                onPointerCancel={() => {
+                    st.current.down = false
+                }}
+                onKeyDown={(e) => {
+                    if (disabled) return
+                    const step = e.shiftKey ? 10 : 1
+                    let next: number | null = null
+                    const rtl = getComputedStyle(e.currentTarget).direction === "rtl"
+                    if (e.key === "ArrowUp" || e.key === (rtl ? "ArrowLeft" : "ArrowRight"))
+                        next = value + step
+                    if (e.key === "ArrowDown" || e.key === (rtl ? "ArrowRight" : "ArrowLeft"))
+                        next = value - step
+                    if (e.key === "Home") next = 0
+                    if (e.key === "End") next = 100
+                    if (next === null) return
+                    e.preventDefault()
+                    /* a key press is a small, quick step: a little wake */
+                    to(clamp(next, 0, 100) / 100, 600)
+                }}
+            >
+                {Array.from({ length: n }, (_, i) => (
+                    <span
+                        key={i}
+                        ref={(b) => {
+                            els.current[i] = b
+                        }}
+                        aria-hidden="true"
+                        className="passui-wake-bar"
+                        data-on={(value > 0 && i <= lit) || undefined}
+                        style={{ height: H }}
+                    />
+                ))}
+            </div>
+            <span aria-hidden="true" className="passui-wake-value">
+                {formatValue?.(value) ?? value}
+            </span>
+        </div>
+    )
+}

package/src/hooks/scroll/minimize-decision.ts

@@ -1,9 +1,5 @@
 /** Programmatic restoration does not collapse chrome; reaching the top always restores it. */
-export function minimizeDecision(
-    top: number,
-    anchor: number,
-    userDriven: boolean
-): boolean | null {
+export function minimizeDecision(top: number, anchor: number, userDriven: boolean): boolean | null {
     if (top < 24) return false
     if (!userDriven) return null
     const delta = top - anchor

package/src/hooks/use-anchored-disclosure.ts

@@ -0,0 +1,23 @@
+import { useCallback, useEffect, useState } from "react"
+
+/** Keep the panel mounted until its material has returned to the trigger. */
+export function useAnchoredDisclosure(disabled = false) {
+    const [open, setOpen] = useState(false)
+    const [mounted, setMounted] = useState(false)
+    useEffect(() => {
+        if (disabled) setOpen(false)
+    }, [disabled])
+    const show = useCallback(() => {
+        setMounted(true)
+        setOpen(true)
+    }, [])
+    const toggle = useCallback(() => {
+        setMounted(true)
+        setOpen((current) => !current)
+    }, [])
+    const close = useCallback(() => setOpen(false), [])
+    const onExited = useCallback(() => {
+        if (!open || disabled) setMounted(false)
+    }, [open, disabled])
+    return { open: open && !disabled, mounted, show, toggle, close, onExited }
+}

package/src/hooks/use-anchored-placement.ts

@@ -1,8 +1,5 @@
 import { useLayoutEffect, useState } from "react"
-import {
-    type AnchoredPlacement,
-    placeAnchored,
-} from "../lib/anchored-placement"
+import { type AnchoredPlacement, placeAnchored } from "../lib/anchored-placement"
 
 /**
  * Places a panel of `width` and `needed` height under its anchor and
@@ -12,15 +9,15 @@ import {
 export function useAnchoredPlacement(
     anchor: HTMLElement,
     width: number,
-    needed: number
+    needed: number,
+    overlap = false
 ): AnchoredPlacement {
     const [placement, setPlacement] = useState(() =>
-        placeAnchored(anchor, width, needed)
+        placeAnchored(anchor, width, needed, 6, overlap)
     )
 
     useLayoutEffect(() => {
-        const replace = () =>
-            setPlacement(placeAnchored(anchor, width, needed))
+        const replace = () => setPlacement(placeAnchored(anchor, width, needed, 6, overlap))
         replace()
         const viewport = window.visualViewport
         viewport?.addEventListener("resize", replace)
@@ -31,13 +28,9 @@ export function useAnchoredPlacement(
             viewport?.removeEventListener("resize", replace)
             viewport?.removeEventListener("scroll", replace)
             window.removeEventListener("resize", replace)
-            window.removeEventListener(
-                "scroll",
-                replace,
-                true
-            )
+            window.removeEventListener("scroll", replace, true)
         }
-    }, [anchor, width, needed])
+    }, [anchor, width, needed, overlap])
 
     return placement
 }

package/src/hooks/use-dismiss.ts

@@ -1,5 +1,5 @@
 import { type RefObject, useEffect } from "react"
-import { ownsFloatingLayer } from "../lib/floating-layers"
+import { belongsToFloatingSurface, ownsFloatingLayer } from "../lib/floating-layers"
 
 /** Marks a floating layer (a pop-up list, a menu) whose clicks belong to what opened it. */
 export { FLOATING_LAYER } from "../lib/floating-layers"
@@ -19,39 +19,21 @@ export function useDismiss(
         const onPointerDown = (event: PointerEvent) => {
             const target = event.target as Element
             const surface = ref.current
-            if (
-                surface &&
-                (surface.contains(target) ||
-                    ownsFloatingLayer(surface, target))
-            )
-                return
+            if (surface && belongsToFloatingSurface(surface, target)) return
             onDismiss()
         }
         const onKeyDown = (event: KeyboardEvent) => {
             if (event.defaultPrevented) return
-            if (
-                ref.current &&
-                ownsFloatingLayer(
-                    ref.current,
-                    document.activeElement
-                )
-            )
-                return
+            if (ref.current && ownsFloatingLayer(ref.current, document.activeElement)) return
             if (event.key === "Escape") {
                 event.preventDefault()
                 onDismiss()
             }
         }
-        document.addEventListener(
-            "pointerdown",
-            onPointerDown
-        )
+        document.addEventListener("pointerdown", onPointerDown)
         window.addEventListener("keydown", onKeyDown)
         return () => {
-            document.removeEventListener(
-                "pointerdown",
-                onPointerDown
-            )
+            document.removeEventListener("pointerdown", onPointerDown)
             window.removeEventListener("keydown", onKeyDown)
         }
     }, [ref, active, onDismiss])

package/src/hooks/use-floating-dismiss.ts

@@ -0,0 +1,28 @@
+import { type RefObject, useEffect } from "react"
+import { isOutsideFloatingSurface } from "../lib/floating-layers"
+
+/** Dismiss an anchored portal without stealing focus from outside pointer interactions. */
+export function useFloatingDismiss(
+    surface: RefObject<HTMLElement | null>,
+    anchor: HTMLElement,
+    onDismiss: (restoreFocus: boolean) => void
+) {
+    useEffect(() => {
+        const onPointer = (event: PointerEvent) => {
+            if (isOutsideFloatingSurface(surface.current, anchor, event.target)) onDismiss(false)
+        }
+        const onFocus = (event: FocusEvent) => {
+            if (isOutsideFloatingSurface(surface.current, anchor, event.target)) onDismiss(false)
+        }
+        const onBlur = () => onDismiss(false)
+
+        document.addEventListener("pointerdown", onPointer, true)
+        document.addEventListener("focusin", onFocus, true)
+        window.addEventListener("blur", onBlur)
+        return () => {
+            document.removeEventListener("pointerdown", onPointer, true)
+            document.removeEventListener("focusin", onFocus, true)
+            window.removeEventListener("blur", onBlur)
+        }
+    }, [surface, anchor, onDismiss])
+}