@passui/react 0.1.17 → 0.1.20

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

@@ -0,0 +1,251 @@
+// Adapted from Bencho. See THIRD_PARTY_NOTICES.md for the MIT notice.
+import { type CSSProperties, useEffect, useRef } from "react"
+import { useMediaQuery } from "../../hooks/use-media-query"
+import { cn } from "../../lib/class-names"
+import { clampRange as clamp } from "../../lib/range-value"
+import { stepLiquid } from "./liquid-step"
+
+export interface SloshSliderProps {
+    label: string
+    value?: number
+    defaultValue?: number
+    onChange?: (value: number) => void
+    /** 0 is rigid; 100 is loose liquid. @default 15 */
+    viscosity?: number
+    /** How far the handle coasts after release, 0–100. @default 55 */
+    momentum?: number
+    /** Lean of the liquid's leading edge, 0–100. @default 45 */
+    tilt?: number
+    /** Track corner, from square to a pill, 0–20. @default 20 */
+    corner?: number
+    disabled?: boolean
+    className?: string
+    formatValue?: (value: number) => string
+}
+
+/* A slider whose value has mass.
+
+   The handle is rigid — it is under your finger and anything under a
+   finger that lags it is broken. The FILL is a second spring behind it,
+   softer and barely damped, so a fast drag throws it past the handle,
+   into the end stop, and rocks it back before it settles.
+
+   The tilt is what sells it as liquid. A bar that lags is a laggy bar;
+   a bar whose leading edge leans has a meniscus. Same lag, different object.
+
+   The loop writes geometry directly and parks as soon as it rests.
+   React receives only changed integer values for the application's state. */
+export function SloshSlider({
+    label,
+    value,
+    defaultValue = 62,
+    onChange,
+    viscosity = 15,
+    momentum = 55,
+    tilt = 45,
+    corner = 20,
+    disabled = false,
+    className,
+    formatValue,
+}: SloshSliderProps) {
+    const reduced = useMediaQuery("(prefers-reduced-motion: reduce)")
+    const track = useRef<HTMLDivElement>(null)
+    const fillEl = useRef<HTMLDivElement>(null)
+    const knobEl = useRef<HTMLDivElement>(null)
+    const initial = clamp(value ?? defaultValue, 0, 100)
+    const state = useRef({
+        value: initial,
+        handleVelocity: 0,
+        fill: initial,
+        velocity: 0,
+        held: false,
+        raf: 0,
+        previous: 0,
+        last: { value: initial, time: 0 },
+        notified: Math.round(initial),
+    })
+    const settings = useRef({ viscosity, momentum, tilt, reduced, onChange, formatValue })
+    settings.current = { viscosity, momentum, tilt, reduced, onChange, formatValue }
+    const run = useRef<() => void>(() => {})
+
+    useEffect(() => {
+        const s = state.current
+        const paint = () => {
+            if (!track.current || !fillEl.current || !knobEl.current) return
+            fillEl.current.style.width = `${s.fill.toFixed(2)}%`
+            knobEl.current.style.insetInlineStart = `${s.value.toFixed(2)}%`
+            /* Proportional to how fast the fill is actually moving: upright
+               at rest, so it cannot be decoration when nothing travels. */
+            const lean = settings.current.reduced
+                ? 0
+                : clamp((clamp(settings.current.tilt, 0, 100) / 100) * s.velocity * 3, -20, 20)
+            fillEl.current.style.setProperty("--slosh-lean", `${lean.toFixed(2)}px`)
+            const next = Math.round(s.value)
+            track.current.setAttribute("aria-valuenow", String(next))
+            const spoken = settings.current.formatValue?.(next)
+            if (spoken) track.current.setAttribute("aria-valuetext", spoken)
+            else track.current.removeAttribute("aria-valuetext")
+            if (s.notified !== next) {
+                s.notified = next
+                settings.current.onChange?.(next)
+            }
+        }
+        const tick = (time: number) => {
+            const dt = s.previous ? clamp((time - s.previous) / 16.67, 0, 2.5) : 1
+            s.previous = time
+            const knobs = settings.current
+            /* Friction is per frame, raised to dt: a dropped frame must
+               not double the deceleration. The release is a throw, not a stop. */
+            if (!s.held && s.handleVelocity) {
+                s.value += s.handleVelocity * dt
+                s.handleVelocity *= (0.86 + (clamp(knobs.momentum, 0, 100) / 100) * 0.115) ** dt
+                if (s.value <= 0 || s.value >= 100) {
+                    s.value = clamp(s.value, 0, 100)
+                    s.handleVelocity = 0
+                }
+                if (Math.abs(s.handleVelocity) < 0.01) s.handleVelocity = 0
+            }
+            const next = stepLiquid(s, s.value, knobs.reduced ? 0 : knobs.viscosity, dt)
+            s.fill = next.fill
+            s.velocity = next.velocity
+            paint()
+            if (!s.handleVelocity && !s.velocity && Math.abs(s.fill - s.value) < 0.02) {
+                s.raf = 0
+                s.previous = 0
+                return
+            }
+            s.raf = requestAnimationFrame(tick)
+        }
+        run.current = () => {
+            // The handle paints on the input event; it never waits for the fill.
+            paint()
+            if (!s.raf) s.raf = requestAnimationFrame(tick)
+        }
+        paint()
+        return () => {
+            cancelAnimationFrame(s.raf)
+            s.raf = 0
+            s.previous = 0
+        }
+    }, [])
+
+    // biome-ignore lint/correctness/useExhaustiveDependencies: Motion settings can wake a parked loop without changing its value.
+    useEffect(() => {
+        const s = state.current
+        if (value !== undefined && Math.round(clamp(value, 0, 100)) !== s.notified) {
+            s.value = clamp(value, 0, 100)
+            s.notified = Math.round(s.value)
+            s.handleVelocity = 0
+        }
+        if (reduced || disabled) {
+            s.handleVelocity = 0
+            s.held = false
+        }
+        run.current()
+    }, [value, reduced, disabled, viscosity, tilt, formatValue])
+
+    const readAt = (clientX: number) => {
+        const t = track.current
+        if (!t) return 0
+        const box = t.getBoundingClientRect()
+        const fraction = box.width ? (clientX - box.left) / box.width : 0
+        return clamp(
+            (getComputedStyle(t).direction === "rtl" ? 1 - fraction : fraction) * 100,
+            0,
+            100
+        )
+    }
+    const release = (cancelled = false) => {
+        const s = state.current
+        if (!s.held) return
+        s.held = false
+        /* Leaves along its measured velocity, capped so a full-track flick
+           does not simply pin it. A cancelled gesture never throws. */
+        s.handleVelocity = cancelled || reduced ? 0 : clamp(s.handleVelocity, -6, 6)
+        if (performance.now() - s.last.time > 100) s.handleVelocity = 0
+        run.current()
+    }
+    return (
+        <div
+            className={cn("passui-slosh-slider not-typeset", disabled && "opacity-40", className)}
+            style={{ "--slosh-radius": `${clamp(corner, 0, 20)}px` } as CSSProperties}
+        >
+            {/* Nothing but the track: the liquid is the value's motion, not a
+            second numeric readout that lags and overshoots beside it. */}
+            <div
+                ref={track}
+                className="passui-slosh-track"
+                role="slider"
+                tabIndex={disabled ? -1 : 0}
+                aria-label={label}
+                aria-disabled={disabled || undefined}
+                aria-valuemin={0}
+                aria-valuemax={100}
+                aria-valuenow={Math.round(initial)}
+                aria-valuetext={formatValue?.(Math.round(initial))}
+                onPointerDown={(event) => {
+                    if (disabled || event.button !== 0) return
+                    event.currentTarget.focus()
+                    event.currentTarget.setPointerCapture(event.pointerId)
+                    const s = state.current
+                    s.held = true
+                    s.handleVelocity = 0
+                    s.value = readAt(event.clientX)
+                    s.last = { value: s.value, time: performance.now() }
+                    run.current()
+                }}
+                onPointerMove={(event) => {
+                    const s = state.current
+                    if (!s.held || disabled) return
+                    const next = readAt(event.clientX),
+                        now = performance.now()
+                    /* Per frame, not per ms: the loop's release velocity must
+                   use the same unit as the spring. */
+                    s.handleVelocity =
+                        ((next - s.last.value) / Math.max(1, now - s.last.time)) * 16.67
+                    s.last = { value: next, time: now }
+                    s.value = next
+                    run.current()
+                }}
+                onPointerUp={() => release()}
+                onPointerCancel={() => release(true)}
+                onLostPointerCapture={() => release(true)}
+                onKeyDown={(event) => {
+                    if (disabled) return
+                    const s = state.current,
+                        step = event.shiftKey ? 10 : 2
+                    const rtl = getComputedStyle(event.currentTarget).direction === "rtl"
+                    const next =
+                        event.key === "ArrowUp" || event.key === (rtl ? "ArrowLeft" : "ArrowRight")
+                            ? s.value + step
+                            : event.key === "ArrowDown" ||
+                                event.key === (rtl ? "ArrowRight" : "ArrowLeft")
+                              ? s.value - step
+                              : event.key === "Home"
+                                ? 0
+                                : event.key === "End"
+                                  ? 100
+                                  : null
+                    if (next === null) return
+                    event.preventDefault()
+                    s.handleVelocity = 0
+                    s.value = clamp(next, 0, 100)
+                    run.current()
+                }}
+            >
+                <div
+                    aria-hidden="true"
+                    ref={fillEl}
+                    className="passui-slosh-fill"
+                    style={{ width: `${initial}%` }}
+                />
+                <div
+                    aria-hidden="true"
+                    ref={knobEl}
+                    className="passui-slosh-knob"
+                    style={{ insetInlineStart: `${initial}%` }}
+                />
+            </div>
+        </div>
+    )
+}

package/src/components/stat-tile/stat-tile.tsx

@@ -3,7 +3,7 @@ import { cn } from "../../lib/class-names"
 
 export type StatTileTone = "critical"
 
-type StatTileProps = {
+export interface StatTileProps {
     label: string
     value: number
     /** A quiet line under the number, like "3 signed in now". */
@@ -16,41 +16,20 @@ type StatTileProps = {
 }
 
 /** One number with its label, optionally a toggle. */
-export function StatTile({
-    label,
-    value,
-    caption,
-    tone,
-    onClick,
-    active = false,
-}: StatTileProps) {
+export function StatTile({ label, value, caption, tone, onClick, active = false }: StatTileProps) {
     const body = (
         <>
-            <span className="text-xs text-muted-foreground">
-                {label}
-            </span>
-            <span
-                className={cn(
-                    "text-lg font-semibold tabular-nums tracking-tight",
-                    tone === "critical" &&
-                        value > 0 &&
-                        "text-destructive"
-                )}
-            >
+            <span className="text-label-secondary">{label}</span>
+            <span className={cn("tabular-nums", tone === "critical" && value > 0 && "text-danger")}>
                 {value.toLocaleString("en-US")}
             </span>
-            {caption && (
-                <span className="text-xs text-muted-foreground">
-                    {caption}
-                </span>
-            )}
+            {caption && <span className="text-label-secondary">{caption}</span>}
         </>
     )
     const className =
-        "flex min-w-0 flex-col gap-1 rounded-2xl border border-border/35 bg-card p-4 text-left shadow-xs"
+        "flex min-w-0 flex-col gap-2 rounded-2xl border border-separator/35 bg-elevated p-4 text-left shadow-xs"
 
-    if (!onClick)
-        return <div className={className}>{body}</div>
+    if (!onClick) return <div className={className}>{body}</div>
     return (
         <button
             type="button"
@@ -58,8 +37,8 @@ export function StatTile({
             onClick={onClick}
             className={cn(
                 className,
-                "ring-1 ring-transparent transition-colors hover:bg-muted/60",
-                active && "bg-muted/70 ring-foreground/15"
+                "ring-1 ring-transparent transition-colors hover:bg-fill/60",
+                active && "bg-fill/70 ring-label/15"
             )}
         >
             {body}

package/src/components/status-indicator/status-indicator.tsx

@@ -1,3 +1,4 @@
+import type { HTMLAttributes, ReactNode } from "react"
 import { cn } from "../../lib/class-names"
 
 const dots = {
@@ -6,29 +7,21 @@ const dots = {
     offline: "bg-label-tertiary",
 } as const
 
-export function StatusIndicator({
-    state,
-    children,
-    className,
-    ...props
-}: React.HTMLAttributes<HTMLSpanElement> & {
-    state: keyof typeof dots
-    children: React.ReactNode
-}) {
+export type StatusIndicatorState = keyof typeof dots
+
+export interface StatusIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Visual treatment of the status dot. */
+    state: StatusIndicatorState
+    children: ReactNode
+}
+
+export function StatusIndicator({ state, children, className, ...props }: StatusIndicatorProps) {
     return (
         <span
-            className={cn(
-                "flex items-center gap-1.5 text-footnote text-label-tertiary",
-                className
-            )}
+            className={cn("flex items-center gap-1.5 text-footnote text-label-tertiary", className)}
             {...props}
         >
-            <span
-                className={cn(
-                    "size-[7px] rounded-full",
-                    dots[state]
-                )}
-            />
+            <span aria-hidden="true" className={cn("size-[7px] rounded-full", dots[state])} />
             {children}
         </span>
     )

package/src/components/stepper/rolling-digit.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useRef } from "react"
+import { useMediaQuery } from "../../hooks/use-media-query"
+
+/** Counts at a place retain carries: the tens column of 1284 targets 128. */
+export function digitAt(count: number) {
+    return ((Math.floor(count) % 10) + 10) % 10
+}
+
+export function advanceDigit(position: number, velocity: number, target: number, frames: number) {
+    const nextVelocity = (velocity + (target - position) * 0.16 * frames) * 0.7 ** frames
+    return { position: position + nextVelocity * frames, velocity: nextVelocity }
+}
+
+/** Three recycled cells keep the strip continuous through either side of zero. */
+export function RollingDigit({ count, place }: { count: number; place: number }) {
+    const strip = useRef<HTMLSpanElement>(null)
+    const state = useRef({ position: count, velocity: 0 })
+    const reduced = useMediaQuery("(prefers-reduced-motion: reduce)")
+    useEffect(() => {
+        let frame = 0
+        let previous = 0
+        let due = 0
+        const paint = (position: number, velocity: number) => {
+            const node = strip.current
+            if (!node) return
+            const base = Math.floor(position)
+            for (let index = 0; index < node.children.length; index++) {
+                node.children[index]!.textContent = String(digitAt(base + index - 1))
+            }
+            node.style.transform = `translateY(${(-(position - base + 1) * 100) / 3}%)`
+            node.style.filter = `blur(${Math.min(2, Math.abs(velocity) * 1.4)}px)`
+        }
+        if (reduced) {
+            state.current = { position: count, velocity: 0 }
+            paint(count, 0)
+            return
+        }
+        const tick = (now: number) => {
+            if (!due) due = now + place * 28
+            const frames = previous ? Math.min((now - previous) / (1000 / 60), 2) : 1
+            previous = now
+            if (now >= due) {
+                state.current = advanceDigit(
+                    state.current.position,
+                    state.current.velocity,
+                    count,
+                    frames
+                )
+                if (
+                    Math.abs(count - state.current.position) < 0.002 &&
+                    Math.abs(state.current.velocity) < 0.002
+                ) {
+                    state.current = { position: count, velocity: 0 }
+                    paint(count, 0)
+                    return
+                }
+                paint(state.current.position, state.current.velocity)
+            }
+            frame = requestAnimationFrame(tick)
+        }
+        frame = requestAnimationFrame(tick)
+        return () => cancelAnimationFrame(frame)
+    }, [count, place, reduced])
+    return (
+        <span className="relative inline-block h-[1.5em] w-[1ch] overflow-hidden align-middle">
+            <span
+                ref={strip}
+                className="absolute inset-x-0 top-0 flex flex-col leading-[1.5em]"
+                style={{ transform: "translateY(-33.333333%)" }}
+            >
+                <span>{digitAt(count - 1)}</span>
+                <span>{digitAt(count)}</span>
+                <span>{digitAt(count + 1)}</span>
+            </span>
+        </span>
+    )
+}

package/src/components/stepper/stepper.tsx

@@ -0,0 +1,101 @@
+import { useId } from "react"
+import { Button } from "../button/button"
+import { cn } from "../../lib/class-names"
+import { clampRange, stepRange } from "../../lib/range-value"
+import { RollingDigit } from "./rolling-digit"
+
+export interface StepperProps {
+    value: number
+    onChange: (value: number) => void
+    label: string
+    /** Localized accessible names for each action. */
+    labels: { decrement: string; increment: string }
+    min?: number
+    max?: number
+    step?: number
+    disabled?: boolean
+    className?: string
+    /** Formats the displayed value. */
+    formatValue?: (value: number) => string
+}
+
+/** Discrete increments with disabled boundary actions and a spoken value. */
+export function Stepper({
+    value,
+    onChange,
+    label,
+    labels,
+    min = 0,
+    max = 100,
+    step = 1,
+    disabled = false,
+    className,
+    formatValue,
+}: StepperProps) {
+    const id = useId()
+    const upper = Math.max(min, max)
+    const current = clampRange(value, min, upper)
+    const decrement = stepRange(current, -1, min, upper, step > 0 ? step : 1)
+    const increment = stepRange(current, 1, min, upper, step > 0 ? step : 1)
+    const displayed = formatValue?.(current) ?? String(current)
+    const digits = displayed.replace(/[^0-9]/g, "")
+    let digitIndex = 0
+
+    return (
+        <div className={cn("flex min-w-0 items-center justify-between gap-3", className)}>
+            <span id={id} className="min-w-0 text-subheadline text-label">
+                {label}
+            </span>
+            <div className="flex shrink-0 items-center gap-3">
+                <output
+                    aria-live="polite"
+                    aria-labelledby={id}
+                    className="text-subheadline tabular-nums text-label"
+                >
+                    <span aria-hidden="true" className="inline-flex items-center">
+                        {Array.from(displayed).map((character, index) => {
+                            if (!/[0-9]/.test(character))
+                                return <span key={`separator-${index}`}>{character}</span>
+                            const prefix = digits.slice(0, ++digitIndex)
+                            const place = digits.length - digitIndex
+                            return (
+                                <RollingDigit
+                                    key={`place-${place}`}
+                                    count={Number(prefix)}
+                                    place={place}
+                                />
+                            )
+                        })}
+                    </span>
+                    <span className="sr-only">{displayed}</span>
+                </output>
+                <div className="flex items-center divide-x divide-separator overflow-hidden rounded-lg bg-fill">
+                    <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        aria-label={labels.decrement}
+                        aria-describedby={id}
+                        disabled={disabled || decrement === current}
+                        onClick={() => onChange(decrement)}
+                        className="size-8 rounded-none text-title3 text-accent-text [@media(pointer:coarse)]:size-11"
+                    >
+                        −
+                    </Button>
+                    <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        aria-label={labels.increment}
+                        aria-describedby={id}
+                        disabled={disabled || increment === current}
+                        onClick={() => onChange(increment)}
+                        className="size-8 rounded-none text-title3 text-accent-text [@media(pointer:coarse)]:size-11"
+                    >
+                        +
+                    </Button>
+                </div>
+            </div>
+        </div>
+    )
+}

package/src/components/swatch-picker/swatch-picker.tsx

@@ -5,24 +5,30 @@ import { cn } from "../../lib/class-names"
 import { haptic } from "../../lib/haptics"
 import { spring } from "../../motion/transitions"
 
+export interface SwatchPickerOption<T extends string> {
+    value: T
+    label: string
+    /** Swatch background color. */
+    color: string
+    /** Color of the selected checkmark. */
+    ink: string
+}
+
+export interface SwatchPickerProps<T extends string> {
+    value: T
+    options: ReadonlyArray<SwatchPickerOption<T>>
+    onChange: (value: T) => void
+    /** Accessible name for the group. */
+    label: string
+}
+
 /** Colour swatches with a check on the chosen one. */
 export function SwatchPicker<T extends string>({
     value,
     options,
     onChange,
     label,
-}: {
-    value: T
-    /** `ink` colours the check drawn on the swatch. */
-    options: Array<{
-        value: T
-        label: string
-        color: string
-        ink: string
-    }>
-    onChange: (value: T) => void
-    label: string
-}) {
+}: SwatchPickerProps<T>) {
     const name = useId()
     return (
         <fieldset className="flex flex-wrap gap-3">
@@ -81,9 +87,7 @@ export function SwatchPicker<T extends string>({
                         <span
                             className={cn(
                                 "text-caption2",
-                                selected
-                                    ? "font-semibold text-label"
-                                    : "text-label-tertiary"
+                                selected ? "font-semibold text-label" : "text-label-tertiary"
                             )}
                         >
                             {option.label}