@passui/react 0.1.16 → 0.1.19

package/src/components/section/section.tsx

@@ -1,27 +1,30 @@
-import type { ReactNode } from "react"
+import { useId, type HTMLAttributes, type ReactNode } from "react"
+import { cn } from "../../lib/class-names"
+
+export interface SectionProps extends HTMLAttributes<HTMLElement> {
+    /** Optional group heading and accessible name. */
+    title?: string
+    /** Supporting text below the grouped rows. */
+    footer?: ReactNode
+    /** Rows, typically LabeledContent. */
+    children?: ReactNode
+}
 
 /**
  * A titled, inset group of rows with an optional footer, as in iOS Settings
  * and SwiftUI's grouped `List` with `Section(header:footer:)`. Rows are
  * usually `LabeledContent`; dividers between them come for free.
  */
-export function Section({
-    title,
-    footer,
-    children,
-}: {
-    /** iOS groups can stand without a header. */
-    title?: string
-    footer?: ReactNode
-    children?: ReactNode
-}) {
+export function Section({ title, footer, children, className, ...props }: SectionProps) {
+    const headingId = useId()
     return (
         <section
-            aria-label={title}
-            className="flex flex-col gap-2"
+            aria-labelledby={title ? headingId : undefined}
+            className={cn("flex flex-col gap-2", className)}
+            {...props}
         >
             {title && (
-                <h2 className="px-4 text-footnote font-medium text-label-tertiary">
+                <h2 id={headingId} className="px-4 text-footnote font-medium text-label-tertiary">
                     {title}
                 </h2>
             )}
@@ -32,9 +35,7 @@ export function Section({
                 </div>
             ) : null}
             {footer && (
-                <p className="px-4 text-caption leading-snug text-label-tertiary">
-                    {footer}
-                </p>
+                <div className="px-4 text-caption leading-snug text-label-tertiary">{footer}</div>
             )}
         </section>
     )

package/src/components/secure-field/secure-field.tsx

@@ -1,10 +1,8 @@
-import {
-    TextField,
-    type TextFieldProps,
-} from "../text-field/text-field"
+import { TextField, type TextFieldProps } from "../text-field/text-field"
 
-export function SecureField(
-    props: Omit<TextFieldProps, "type">
-) {
+/** TextField's native input props, with the password type managed by SecureField. */
+export type SecureFieldProps = Omit<TextFieldProps, "type">
+
+export function SecureField(props: SecureFieldProps) {
     return <TextField {...props} type="password" />
 }

package/src/components/segmented-control/segmented-control.tsx

@@ -1,15 +1,21 @@
-import { motion } from "motion/react"
-import {
-    useId,
-    useLayoutEffect,
-    useRef,
-    useState,
-} from "react"
+import { motion, useReducedMotion } from "motion/react"
+import { useId, useLayoutEffect, useRef, useState } from "react"
 import { cn } from "../../lib/class-names"
 import { haptic } from "../../lib/haptics"
 import { spring } from "../../motion/transitions"
 import { Picker } from "../picker/picker"
 
+export interface SegmentedControlProps<T extends string> {
+    /** Value of the selected segment. */
+    value: T
+    /** The choices, in display order. */
+    options: ReadonlyArray<{ value: T; label: string }>
+    /** Called with the selected segment's value. */
+    onChange: (value: NoInfer<T>) => void
+    /** Accessible name for the group and its compact picker. */
+    label: string
+}
+
 /**
  * Mutually exclusive choices with a sliding selection, as on Apple
  * platforms. When the labels can't all fit the space it is given (a long
@@ -21,13 +27,9 @@ export function SegmentedControl<T extends string>({
     options,
     onChange,
     label,
-}: {
-    value: T
-    options: Array<{ value: T; label: string }>
-    onChange: (value: T) => void
-    label: string
-}) {
+}: SegmentedControlProps<T>) {
     const id = useId()
+    const reducedMotion = useReducedMotion()
     const frame = useRef<HTMLDivElement>(null)
     const measure = useRef<HTMLDivElement>(null)
     const [fits, setFits] = useState(true)
@@ -36,10 +38,7 @@ export function SegmentedControl<T extends string>({
         const box = frame.current
         const natural = measure.current
         if (!box || !natural) return
-        const check = () =>
-            setFits(
-                natural.offsetWidth <= box.clientWidth + 0.5
-            )
+        const check = () => setFits(natural.offsetWidth <= box.clientWidth + 0.5)
         check()
         const observer = new ResizeObserver(check)
         observer.observe(box)
@@ -56,22 +55,16 @@ export function SegmentedControl<T extends string>({
                 className="pointer-events-none invisible absolute top-0 flex w-max p-[3px] text-footnote font-semibold"
             >
                 {options.map((option) => (
-                    <span
-                        key={option.value}
-                        className="min-w-[64px] px-3 py-1 whitespace-nowrap"
-                    >
+                    <span key={option.value} className="min-w-[64px] px-3 py-1 whitespace-nowrap">
                         {option.label}
                     </span>
                 ))}
             </div>
             {fits ? (
                 <fieldset className="flex w-full rounded-lg bg-fill p-[3px] shadow-[inset_0_1px_2px_rgb(40_30_0/0.06)]">
-                    <legend className="sr-only">
-                        {label}
-                    </legend>
+                    <legend className="sr-only">{label}</legend>
                     {options.map((option) => {
-                        const selected =
-                            option.value === value
+                        const selected = option.value === value
                         return (
                             <label
                                 key={option.value}
@@ -97,9 +90,7 @@ export function SegmentedControl<T extends string>({
                                     <motion.span
                                         layoutId={`segment-${id}`}
                                         className="absolute inset-0 -z-10 rounded-md bg-elevated shadow-[0_0_0_0.5px_rgb(0_0_0/0.06),0_1px_2px_rgb(0_0_0/0.08),0_3px_8px_-2px_rgb(0_0_0/0.10)]"
-                                        transition={
-                                            spring.snappy
-                                        }
+                                        transition={reducedMotion ? { duration: 0 } : spring.snappy}
                                     />
                                 )}
                                 {option.label}

package/src/components/sheet/modal-environment.ts

@@ -1,7 +1,4 @@
-import {
-    FLOATING_LAYER,
-    ownsFloatingLayer,
-} from "../../lib/floating-layers"
+import { FLOATING_LAYER, ownsFloatingLayer } from "../../lib/floating-layers"
 
 const surfaces: HTMLElement[] = []
 const isolated = new Map<HTMLElement, boolean>()
@@ -9,8 +6,7 @@ let overflow = ""
 let overflowPriority = ""
 
 function restoreBackground() {
-    for (const [element, inert] of isolated)
-        element.inert = inert
+    for (const [element, inert] of isolated) element.inert = inert
     isolated.clear()
 }
 
@@ -19,11 +15,8 @@ function isolateBackground() {
     const surface = surfaces.at(-1)
     if (!surface) return
     const roots = [surface.parentElement ?? surface]
-    for (const layer of document.querySelectorAll<HTMLElement>(
-        `[${FLOATING_LAYER}]`
-    )) {
-        if (ownsFloatingLayer(surface, layer))
-            roots.push(layer)
+    for (const layer of document.querySelectorAll<HTMLElement>(`[${FLOATING_LAYER}]`)) {
+        if (ownsFloatingLayer(surface, layer)) roots.push(layer)
     }
     const visit = (parent: HTMLElement) => {
         for (const child of parent.children) {
@@ -31,9 +24,7 @@ function isolateBackground() {
             if (roots.includes(child)) continue
             if (roots.some((root) => child.contains(root))) {
                 visit(child)
-            } else if (
-                !child.matches("script, style, link")
-            ) {
+            } else if (!child.matches("script, style, link")) {
                 isolated.set(child, child.inert)
                 child.inert = true
             }
@@ -43,43 +34,26 @@ function isolateBackground() {
 }
 
 /** Keeps nested sheets and their portaled controls above an inactive background. */
-export function enterModalEnvironment(
-    surface: HTMLElement
-): () => void {
+export function enterModalEnvironment(surface: HTMLElement): () => void {
     if (!surfaces.length) {
-        overflow =
-            document.body.style.getPropertyValue("overflow")
-        overflowPriority =
-            document.body.style.getPropertyPriority(
-                "overflow"
-            )
+        overflow = document.body.style.getPropertyValue("overflow")
+        overflowPriority = document.body.style.getPropertyPriority("overflow")
         document.body.style.setProperty("overflow", "hidden")
     }
     surfaces.push(surface)
     isolateBackground()
-    const preventBackgroundScroll = (
-        event: WheelEvent | TouchEvent
-    ) => {
+    const preventBackgroundScroll = (event: WheelEvent | TouchEvent) => {
         if (surfaces.at(-1) !== surface) return
         const target = event.target
         if (
             target instanceof Element &&
-            (surface.contains(target) ||
-                ownsFloatingLayer(surface, target))
+            (surface.contains(target) || ownsFloatingLayer(surface, target))
         )
             return
         event.preventDefault()
     }
-    document.addEventListener(
-        "wheel",
-        preventBackgroundScroll,
-        { passive: false }
-    )
-    document.addEventListener(
-        "touchmove",
-        preventBackgroundScroll,
-        { passive: false }
-    )
+    document.addEventListener("wheel", preventBackgroundScroll, { passive: false })
+    document.addEventListener("touchmove", preventBackgroundScroll, { passive: false })
     const observer = new MutationObserver(() => {
         if (surfaces.at(-1) === surface) isolateBackground()
     })
@@ -89,25 +63,13 @@ export function enterModalEnvironment(
     })
     return () => {
         observer.disconnect()
-        document.removeEventListener(
-            "wheel",
-            preventBackgroundScroll
-        )
-        document.removeEventListener(
-            "touchmove",
-            preventBackgroundScroll
-        )
+        document.removeEventListener("wheel", preventBackgroundScroll)
+        document.removeEventListener("touchmove", preventBackgroundScroll)
         surfaces.splice(surfaces.indexOf(surface), 1)
         isolateBackground()
         if (!surfaces.length) {
-            if (overflow)
-                document.body.style.setProperty(
-                    "overflow",
-                    overflow,
-                    overflowPriority
-                )
-            else
-                document.body.style.removeProperty("overflow")
+            if (overflow) document.body.style.setProperty("overflow", overflow, overflowPriority)
+            else document.body.style.removeProperty("overflow")
         }
     }
 }

package/src/components/sheet/sheet-portal.tsx

@@ -1,21 +1,10 @@
-import {
-    type ReactNode,
-    useLayoutEffect,
-    useRef,
-    useState,
-} from "react"
+import { type ReactNode, useLayoutEffect, useRef, useState } from "react"
 import { createPortal } from "react-dom"
 
 /** Escape transformed page layers while retaining the source's scoped appearance. */
-export function SheetPortal({
-    children,
-}: {
-    children: ReactNode
-}) {
+export function SheetPortal({ children }: { children: ReactNode }) {
     const source = useRef<HTMLSpanElement>(null)
-    const [host, setHost] = useState<HTMLDivElement | null>(
-        null
-    )
+    const [host, setHost] = useState<HTMLDivElement | null>(null)
     useLayoutEffect(() => {
         const marker = source.current
         if (!marker) return
@@ -23,20 +12,12 @@ export function SheetPortal({
         const layer = document.createElement("div")
         layer.dataset.passuiOverlay = ""
         layer.style.display = "contents"
-        const attributes = [
-            "data-theme",
-            "data-accent",
-            "data-os",
-            "dir",
-        ]
+        const attributes = ["data-theme", "data-accent", "data-os", "dir"]
         let properties = new Set<string>()
         const inherit = () => {
             for (const name of attributes) {
-                const value = marker
-                    .closest(`[${name}]`)
-                    ?.getAttribute(name)
-                if (value === null || value === undefined)
-                    layer.removeAttribute(name)
+                const value = marker.closest(`[${name}]`)?.getAttribute(name)
+                if (value === null || value === undefined) layer.removeAttribute(name)
                 else layer.setAttribute(name, value)
             }
             const computed = getComputedStyle(marker)
@@ -44,14 +25,9 @@ export function SheetPortal({
             for (const name of computed) {
                 if (!name.startsWith("--")) continue
                 next.add(name)
-                layer.style.setProperty(
-                    name,
-                    computed.getPropertyValue(name)
-                )
+                layer.style.setProperty(name, computed.getPropertyValue(name))
             }
-            for (const name of properties)
-                if (!next.has(name))
-                    layer.style.removeProperty(name)
+            for (const name of properties) if (!next.has(name)) layer.style.removeProperty(name)
             properties = next
             layer.style.colorScheme = computed.colorScheme
             layer.style.fontFamily = computed.fontFamily
@@ -61,18 +37,10 @@ export function SheetPortal({
         document.body.appendChild(layer)
         setHost(layer)
         const observer = new MutationObserver(inherit)
-        for (
-            let ancestor = marker.parentElement;
-            ancestor;
-            ancestor = ancestor.parentElement
-        ) {
+        for (let ancestor = marker.parentElement; ancestor; ancestor = ancestor.parentElement) {
             observer.observe(ancestor, {
                 attributes: true,
-                attributeFilter: [
-                    ...attributes,
-                    "style",
-                    "class",
-                ],
+                attributeFilter: [...attributes, "style", "class"],
             })
         }
         return () => {

package/src/components/sheet/sheet.tsx

@@ -1,8 +1,4 @@
-import {
-    AnimatePresence,
-    motion,
-    useReducedMotion,
-} from "motion/react"
+import { AnimatePresence, motion, useReducedMotion } from "motion/react"
 import { type ReactNode, useRef } from "react"
 import { useVisualViewport } from "../../hooks/use-visual-viewport"
 import { cn } from "../../lib/class-names"
@@ -10,12 +6,19 @@ import { spring } from "../../motion/transitions"
 import { SheetPortal } from "./sheet-portal"
 import { useSheetFocus } from "./use-sheet-focus"
 
-interface SheetProps {
+export type SheetPlacement = "adaptive" | "center"
+
+export interface SheetProps {
+    /** Controls whether the sheet is presented. */
     open: boolean
+    /** Called on Escape or an outside press. */
     onClose: () => void
     /** Read out by screen readers as the sheet's name. */
     label: string
+    /** ID of a visible heading to use instead of label for the accessible name. */
     labelledBy?: string
+    /** `adaptive` rises from the bottom on phones; `center` always floats. @default "adaptive" */
+    placement?: SheetPlacement
     className?: string
     children: ReactNode
 }
@@ -40,6 +43,7 @@ function OpenSheet({
     onClose,
     label,
     labelledBy,
+    placement = "adaptive",
     className,
     children,
 }: Omit<SheetProps, "open">) {
@@ -51,8 +55,8 @@ function OpenSheet({
     return (
         <div
             className={cn(
-                "fixed inset-0 z-[65] flex items-end justify-center",
-                "sm:items-center sm:p-6"
+                "fixed inset-0 z-[65] flex justify-center",
+                placement === "center" ? "items-center p-6" : "items-end sm:items-center sm:p-6"
             )}
             style={
                 viewport
@@ -85,25 +89,13 @@ function OpenSheet({
                 className={cn(
                     "glass-menu relative flex w-full flex-col overflow-hidden",
                     "max-h-[92%] max-w-[560px]",
-                    "rounded-t-sheet sm:rounded-sheet",
+                    placement === "center" ? "rounded-sheet" : "rounded-t-sheet sm:rounded-sheet",
                     className
                 )}
-                initial={
-                    reducedMotion
-                        ? { opacity: 0 }
-                        : { y: 40, opacity: 0, scale: 0.98 }
-                }
-                animate={{ y: 0, opacity: 1, scale: 1 }}
-                exit={
-                    reducedMotion
-                        ? { opacity: 0 }
-                        : { y: 30, opacity: 0 }
-                }
-                transition={
-                    reducedMotion
-                        ? { duration: 0 }
-                        : spring.smooth
-                }
+                initial={reducedMotion ? { opacity: 0 } : { y: 40, opacity: 0 }}
+                animate={{ y: 0, opacity: 1 }}
+                exit={reducedMotion ? { opacity: 0 } : { y: 30, opacity: 0 }}
+                transition={reducedMotion ? { duration: 0 } : spring.smooth}
             >
                 {children}
             </motion.div>

package/src/components/sheet/use-sheet-focus.ts

@@ -1,10 +1,4 @@
-import {
-    type RefObject,
-    useEffect,
-    useLayoutEffect,
-    useRef,
-    useState,
-} from "react"
+import { type RefObject, useEffect, useLayoutEffect, useRef, useState } from "react"
 import { ownsFloatingLayer } from "../../lib/floating-layers"
 import { enterModalEnvironment } from "./modal-environment"
 
@@ -19,12 +13,8 @@ const focusableSelector = [
     "[contenteditable=true]",
 ].join(",")
 
-function focusableElements(
-    panel: HTMLElement
-): HTMLElement[] {
-    return Array.from(
-        panel.querySelectorAll<HTMLElement>(focusableSelector)
-    ).filter(
+function focusableElements(panel: HTMLElement): HTMLElement[] {
+    return Array.from(panel.querySelectorAll<HTMLElement>(focusableSelector)).filter(
         (element) =>
             element.tabIndex >= 0 &&
             !element.matches(":disabled") &&
@@ -35,15 +25,10 @@ function focusableElements(
 }
 
 /** Keeps keyboard focus in the foremost sheet, including its floating pickers. */
-export function useSheetFocus(
-    panel: RefObject<HTMLDivElement | null>,
-    onClose: () => void
-) {
+export function useSheetFocus(panel: RefObject<HTMLDivElement | null>, onClose: () => void) {
     // Capture before children mount, since a child may use autoFocus.
     const [opener] = useState(() =>
-        typeof document === "undefined"
-            ? null
-            : document.activeElement
+        typeof document === "undefined" ? null : document.activeElement
     )
     const close = useRef(onClose)
     useEffect(() => {
@@ -55,34 +40,22 @@ export function useSheetFocus(
         if (!surface) return
         sheets.push(surface)
         const foremost = () => sheets.at(-1) === surface
-        const focusFirst = () =>
-            (focusableElements(surface)[0] ?? surface).focus()
-        const inFloatingLayer = (element: Element | null) =>
-            ownsFloatingLayer(surface, element)
+        const focusFirst = () => (focusableElements(surface)[0] ?? surface).focus()
+        const inFloatingLayer = (element: Element | null) => ownsFloatingLayer(surface, element)
         const belongsToSheet = (element: Element | null) =>
-            surface.contains(element) ||
-            inFloatingLayer(element)
+            surface.contains(element) || inFloatingLayer(element)
 
-        if (!surface.contains(document.activeElement))
-            surface.focus({ preventScroll: true })
-        const leaveModalEnvironment =
-            enterModalEnvironment(surface)
+        if (!surface.contains(document.activeElement)) surface.focus({ preventScroll: true })
+        const leaveModalEnvironment = enterModalEnvironment(surface)
 
         const onFocus = (event: FocusEvent) => {
-            if (
-                foremost() &&
-                !belongsToSheet(
-                    event.target as Element | null
-                )
-            )
-                focusFirst()
+            if (foremost() && !belongsToSheet(event.target as Element | null)) focusFirst()
         }
         const onKey = (event: KeyboardEvent) => {
             if (!foremost() || event.defaultPrevented) return
             if (event.key === "Escape") {
                 // Floating controls handle their own Escape before the sheet.
-                if (inFloatingLayer(document.activeElement))
-                    return
+                if (inFloatingLayer(document.activeElement)) return
                 event.preventDefault()
                 event.stopPropagation()
                 close.current()
@@ -94,17 +67,13 @@ export function useSheetFocus(
             const active = document.activeElement
             if (
                 event.shiftKey &&
-                (active === surface ||
-                    active === first ||
-                    !surface.contains(active))
+                (active === surface || active === first || !surface.contains(active))
             ) {
                 event.preventDefault()
                 last.focus()
             } else if (
                 !event.shiftKey &&
-                (active === last ||
-                    !surface.contains(active) ||
-                    active === surface)
+                (active === last || !surface.contains(active) || active === surface)
             ) {
                 event.preventDefault()
                 first.focus()
@@ -119,12 +88,7 @@ export function useSheetFocus(
             document.removeEventListener("focusin", onFocus)
             window.removeEventListener("keydown", onKey)
             leaveModalEnvironment()
-            if (
-                wasForemost &&
-                opener instanceof HTMLElement &&
-                opener.isConnected
-            )
-                opener.focus()
+            if (wasForemost && opener instanceof HTMLElement && opener.isConnected) opener.focus()
         }
     }, [panel, opener])
 }

package/src/components/sidebar/sidebar.tsx

@@ -1,20 +1,33 @@
-import type { ReactNode } from "react"
+import { useId, type ReactNode } from "react"
 import { cn } from "../../lib/class-names"
 
-export function SidebarSection({
-    title,
-    children,
-}: {
+export interface SidebarSectionProps {
+    /** Visible heading for this group of navigation rows. */
     title: string
     children: ReactNode
-}) {
+}
+
+export interface SidebarItemContentProps {
+    icon: ReactNode
+    /** Optional trailing count. */
+    count?: number
+    /** Matches the router link's active state. */
+    active?: boolean
+    children: ReactNode
+}
+
+export function SidebarSection({ title, children }: SidebarSectionProps) {
+    const headingId = useId()
     return (
-        <div className="flex flex-col gap-0.5">
-            <span className="px-2.5 pb-1.5 text-caption font-semibold text-label-tertiary">
+        <section aria-labelledby={headingId} className="flex flex-col gap-0.5">
+            <h2
+                id={headingId}
+                className="px-2.5 pb-1.5 text-caption font-semibold text-label-tertiary"
+            >
                 {title}
-            </span>
+            </h2>
             {children}
-        </div>
+        </section>
     )
 }
 
@@ -22,31 +35,17 @@ export function SidebarSection({
 export function sidebarItemClass(active?: boolean): string {
     return cn(
         "group flex items-center gap-2.5 rounded-2xl px-2.5 py-[7px] text-subheadline text-label no-underline transition-colors duration-fast",
-        active
-            ? "bg-accent-soft font-medium text-label"
-            : "hover:bg-fill/70"
+        active ? "bg-accent-soft font-medium text-label" : "hover:bg-fill/70"
     )
 }
 
-export function SidebarItemContent({
-    icon,
-    count,
-    active,
-    children,
-}: {
-    icon: ReactNode
-    count?: number
-    active?: boolean
-    children: ReactNode
-}) {
+export function SidebarItemContent({ icon, count, active, children }: SidebarItemContentProps) {
     return (
         <>
             <span
                 className={cn(
                     "flex transition-colors",
-                    active
-                        ? "text-accent-text"
-                        : "text-label-secondary"
+                    active ? "text-accent-text" : "text-label-secondary"
                 )}
             >
                 {icon}
@@ -56,9 +55,7 @@ export function SidebarItemContent({
                 <span
                     className={cn(
                         "text-footnote tabular-nums",
-                        active
-                            ? "text-accent-text"
-                            : "text-label-tertiary"
+                        active ? "text-accent-text" : "text-label-tertiary"
                     )}
                 >
                     {count}