@passui/react 0.0.0-stage → 0.1.14

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

@@ -0,0 +1,81 @@
+import type { PropsWithChildren, ReactNode } from "react"
+import { cn } from "../../lib/class-names"
+
+type ViewControllerProps = PropsWithChildren<{
+    heading: ReactNode
+    className?: string
+}>
+
+type HeadingProps = {
+    title: ReactNode
+    description?: ReactNode
+    action?: ReactNode
+    size?: keyof typeof titleSizes
+}
+
+const titleSizes = {
+    default: "text-3xl md:text-4xl",
+    // sign in style screens: centered, tighter, like a system sheet
+    compact: "text-[1.75rem] font-semibold tracking-tight",
+} as const
+
+export function ViewController({
+    heading,
+    className,
+    children,
+}: ViewControllerProps) {
+    return (
+        <article
+            className={cn(
+                "container mx-auto flex flex-col",
+                "w-full gap-5 py-20 md:max-w-3xl",
+                className
+            )}
+        >
+            <section>{heading}</section>
+            {children}
+        </article>
+    )
+}
+
+function Heading({
+    title,
+    description,
+    action,
+    size = "default",
+}: HeadingProps) {
+    const centered = size === "compact"
+    return (
+        <>
+            <div
+                className={cn(
+                    "flex flex-wrap items-center gap-3",
+                    centered && "justify-center text-center"
+                )}
+            >
+                <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]"
+                    )}
+                >
+                    {description}
+                </p>
+            )}
+        </>
+    )
+}
+
+ViewController.Heading = Heading

package/src/docs/index.ts

@@ -0,0 +1,3 @@
+export * from "./registry"
+export * from "./types"
+export * from "./snippet"

package/src/docs/registry.ts

@@ -0,0 +1,113 @@
+import { buttonDocs } from "../components/button/button.docs"
+import { iconButtonDocs } from "../components/button/icon-button.docs"
+import { chipDocs } from "../components/chip/chip.docs"
+import { labeledContentDocs } from "../components/labeled-content/labeled-content.docs"
+import { pickerDocs } from "../components/picker/picker.docs"
+import { searchFieldDocs } from "../components/search-field/search-field.docs"
+import { secureFieldDocs } from "../components/secure-field/secure-field.docs"
+import { sectionDocs } from "../components/section/section.docs"
+import { segmentedControlDocs } from "../components/segmented-control/segmented-control.docs"
+import { statTileDocs } from "../components/stat-tile/stat-tile.docs"
+import { statusIndicatorDocs } from "../components/status-indicator/status-indicator.docs"
+import { swatchPickerDocs } from "../components/swatch-picker/swatch-picker.docs"
+import { textFieldDocs } from "../components/text-field/text-field.docs"
+import { toggleDocs } from "../components/toggle/toggle.docs"
+import { compactDatePickerDocs } from "../components/compact-date-picker/compact-date-picker.docs"
+import { compactTimePickerDocs } from "../components/compact-time-picker/compact-time-picker.docs"
+import { datePickerDocs } from "../components/date-picker/date-picker.docs"
+import { textEditorDocs } from "../components/text-editor/text-editor.docs"
+import { searchListDocs } from "../components/search-list/search-list.docs"
+import { profileImageDocs } from "../components/profile-image/profile-image.docs"
+import { tabViewDocs } from "../components/tab-view/tab-view.docs"
+import { tabBarDocs } from "../components/tab-bar/tab-bar.docs"
+import { sidebarDocs } from "../components/sidebar/sidebar.docs"
+import { viewControllerDocs } from "../components/view-controller/view-controller.docs"
+import { tableDocs } from "../components/table/table.docs"
+import { contentViewDocs } from "../components/content-view/content-view.docs"
+import { conversationDocs } from "../components/conversation/conversation.docs"
+import { ambientDocs } from "../components/ambient/ambient.docs"
+import { dialogDocs } from "../components/dialog/dialog.docs"
+import { sheetDocs } from "../components/sheet/sheet.docs"
+import { popoverDocs } from "../components/popover/popover.docs"
+import { toastDocs } from "../components/toast/toast.docs"
+import { contextMenuDocs } from "../components/context-menu/context-menu.docs"
+import { tooltipDocs } from "../components/tooltip/tooltip.docs"
+import { localeSwitcherDocs } from "../components/locale-switcher/locale-switcher.docs"
+import type { RegisteredDocs } from "./types"
+
+/** Every documented component. Add one line per docs file. */
+export const registry: readonly RegisteredDocs[] = [
+    buttonDocs,
+    iconButtonDocs,
+    chipDocs,
+    textFieldDocs,
+    secureFieldDocs,
+    searchFieldDocs,
+    toggleDocs,
+    segmentedControlDocs,
+    pickerDocs,
+    swatchPickerDocs,
+    sectionDocs,
+    labeledContentDocs,
+    statusIndicatorDocs,
+    statTileDocs,
+    datePickerDocs,
+    compactDatePickerDocs,
+    compactTimePickerDocs,
+    textEditorDocs,
+    searchListDocs,
+    profileImageDocs,
+    tabViewDocs,
+    tabBarDocs,
+    sidebarDocs,
+    viewControllerDocs,
+    tableDocs,
+    contentViewDocs,
+    conversationDocs,
+    ambientDocs,
+    dialogDocs,
+    sheetDocs,
+    popoverDocs,
+    toastDocs,
+    contextMenuDocs,
+    tooltipDocs,
+    localeSwitcherDocs,
+]
+
+export {
+    dialogDocs,
+    sheetDocs,
+    popoverDocs,
+    toastDocs,
+    contextMenuDocs,
+    tooltipDocs,
+    localeSwitcherDocs,
+    tableDocs,
+    contentViewDocs,
+    conversationDocs,
+    ambientDocs,
+    tabViewDocs,
+    tabBarDocs,
+    sidebarDocs,
+    viewControllerDocs,
+    datePickerDocs,
+    compactDatePickerDocs,
+    compactTimePickerDocs,
+    textEditorDocs,
+    searchListDocs,
+    profileImageDocs,
+    buttonDocs,
+    chipDocs,
+    iconButtonDocs,
+    labeledContentDocs,
+    pickerDocs,
+    searchFieldDocs,
+    secureFieldDocs,
+    sectionDocs,
+    segmentedControlDocs,
+    statTileDocs,
+    statusIndicatorDocs,
+    swatchPickerDocs,
+    textFieldDocs,
+    toggleDocs,
+}

package/src/docs/snippet.ts

@@ -0,0 +1,17 @@
+/**
+ * A JSX attribute for a string, quoted so the code always parses: a
+ * plain `name="value"`, or `name={"value"}` when the value holds a quote,
+ * a brace, a backslash or a line break.
+ */
+export function jsxAttribute(name: string, value: string) {
+    return /["\\{}\n]/.test(value)
+        ? `${name}={${JSON.stringify(value)}}`
+        : `${name}="${value}"`
+}
+
+/** Text as JSX children, wrapped in braces when JSX would misread it. */
+export function jsxText(text: string) {
+    return /[{}<>]/.test(text)
+        ? `{${JSON.stringify(text)}}`
+        : text
+}

package/src/docs/types.ts

@@ -0,0 +1,180 @@
+import type { ComponentType, ReactNode } from "react"
+
+/**
+ * A choice among fixed options. The options are object keys, so the
+ * record must name every member of the prop's union: adding a variant to
+ * a component fails the typecheck here until its docs list it too.
+ */
+export type SelectControl<T extends string> = {
+    kind: "select"
+    options: Record<T, true>
+    default: T
+}
+
+export type BooleanControl = {
+    kind: "boolean"
+    default: boolean
+}
+
+export type TextControl = {
+    kind: "text"
+    default: string
+    /**
+     * The prop is required, so the snippet always writes it, even at its
+     * default value, and the copied code compiles.
+     */
+    required?: true
+}
+
+export type AnyControl =
+    | SelectControl<string>
+    | BooleanControl
+    | TextControl
+
+/** The control that fits a prop's type. */
+export type ControlFor<V> = [NonNullable<V>] extends [boolean]
+    ? BooleanControl
+    : [NonNullable<V>] extends [string]
+      ? string extends NonNullable<V>
+          ? TextControl
+          : SelectControl<NonNullable<V> & string>
+      : never
+
+/** Controls for any of a component's props, plus its text children. */
+export type Controls<P> = {
+    [K in Exclude<keyof P, "children">]?: ControlFor<P[K]>
+} & { children?: TextControl }
+
+/** The current value of every control. */
+export type ControlValues<C> = {
+    [K in keyof C]-?: NonNullable<C[K]> extends {
+        kind: "select"
+        options: infer O
+    }
+        ? keyof O & string
+        : NonNullable<C[K]> extends BooleanControl
+          ? boolean
+          : string
+}
+
+/**
+ * An example is a real React function in the component's `examples/`
+ * folder, named `<slug>-<id>.tsx`; the site shows that file's source as
+ * its code, so the code is always what runs. `playground` values let the
+ * site open the example in the playground.
+ */
+export type Example<C> = {
+    id: string
+    component: ComponentType
+    playground?: Partial<ControlValues<C>>
+}
+
+/** What the code snippet shows for children, when plain text is not enough. */
+export type SnippetChildren = {
+    imports: string[]
+    children: string
+    /** Literal string props, written as name="value". */
+    extraProps?: Record<string, string>
+    /** Code expressions, written as name={expression}: state and handlers. */
+    expressionProps?: Record<string, string>
+    /** Objects spread onto the element, written as {...name}. */
+    spreadProps?: string[]
+    /** Lines placed before the element, such as a useState call. */
+    setup?: string[]
+    /**
+     * Demo-only controls the snippet writes itself, left out of the
+     * generated props: a `critical` switch written as `tone="critical"`.
+     */
+    omit?: string[]
+    /**
+     * The element to write when it is a part rather than the export
+     * itself: `Conversation.Messages` for `Conversation`.
+     */
+    element?: string
+}
+
+export type ComponentDocs<
+    C,
+    E extends readonly Example<C>[],
+> = {
+    /** Kebab case, unique across the registry, used in URLs. */
+    slug: string
+    /** The component's export name, as written in code. */
+    name: string
+    /** Where it is imported from, for example `@passui/react/button`. */
+    importPath: string
+    controls: C
+    render: (values: ControlValues<C>) => ReactNode
+    childrenSnippet?: (
+        values: ControlValues<C>
+    ) => SnippetChildren
+    /** The smallest real use, shown under Usage (`<slug>-usage.tsx`). */
+    usage: ComponentType
+    /** A small, realistic interface built with it (`<slug>-showcase.tsx`). */
+    showcase: ComponentType
+    examples: E
+    /**
+     * The playground frame's least height in pixels, for components that
+     * open something over the page (a sheet, a popover, a menu) that the
+     * frame must have room to show.
+     */
+    previewHeight?: number
+}
+
+/**
+ * Rejects select options that are not members of the prop's union, so
+ * docs cannot offer a value the component does not accept.
+ */
+type ExactOptions<C, P> = {
+    [K in keyof C]: K extends keyof P
+        ? C[K] extends { kind: "select"; options: infer O }
+            ? {
+                  options: {
+                      [Option in keyof O]: Option extends NonNullable<
+                          P[K]
+                      >
+                          ? true
+                          : never
+                  }
+              }
+            : unknown
+        : unknown
+}
+
+/**
+ * Docs typed against a component's props. Curried so the props type is
+ * given once and control keys and example ids stay exact:
+ * `defineDocs<ButtonProps>()({ ... })`.
+ */
+export function defineDocs<P>() {
+    return <
+        const C extends Controls<P>,
+        const E extends readonly Example<C>[],
+    >(
+        docs: ComponentDocs<C, E> & {
+            controls: ExactOptions<C, P>
+        }
+    ) => docs
+}
+
+/** Any component's docs, as the registry holds them. */
+export type RegisteredDocs = {
+    slug: string
+    name: string
+    importPath: string
+    controls: Record<string, AnyControl | undefined>
+    examples: readonly {
+        id: string
+        component: ComponentType
+        playground?: Record<string, string | boolean>
+    }[]
+    usage: ComponentType
+    showcase: ComponentType
+    previewHeight?: number
+    render(
+        values: Record<string, string | boolean>
+    ): ReactNode
+    childrenSnippet?(
+        values: Record<string, string | boolean>
+    ): SnippetChildren
+}

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

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

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

@@ -0,0 +1,43 @@
+import { useLayoutEffect, useState } from "react"
+import {
+    type AnchoredPlacement,
+    placeAnchored,
+} from "../lib/anchored-placement"
+
+/**
+ * Places a panel of `width` and `needed` height under its anchor and
+ * keeps it there: re-places while the viewport resizes or anything
+ * scrolls, so it never hangs off the screen.
+ */
+export function useAnchoredPlacement(
+    anchor: HTMLElement,
+    width: number,
+    needed: number
+): AnchoredPlacement {
+    const [placement, setPlacement] = useState(() =>
+        placeAnchored(anchor, width, needed)
+    )
+
+    useLayoutEffect(() => {
+        const replace = () =>
+            setPlacement(placeAnchored(anchor, width, needed))
+        replace()
+        const viewport = window.visualViewport
+        viewport?.addEventListener("resize", replace)
+        viewport?.addEventListener("scroll", replace)
+        window.addEventListener("resize", replace)
+        window.addEventListener("scroll", replace, true)
+        return () => {
+            viewport?.removeEventListener("resize", replace)
+            viewport?.removeEventListener("scroll", replace)
+            window.removeEventListener("resize", replace)
+            window.removeEventListener(
+                "scroll",
+                replace,
+                true
+            )
+        }
+    }, [anchor, width, needed])
+
+    return placement
+}

package/src/hooks/use-dismiss.ts

@@ -0,0 +1,58 @@
+import { type RefObject, useEffect } from "react"
+import { 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"
+
+/**
+ * Calls `onDismiss` when the user presses Escape or clicks outside `ref`
+ * while `active`, for menus, popovers and sheets. Clicks in a floating
+ * layer opened from inside, such as a pop-up button's list, don't count.
+ */
+export function useDismiss(
+    ref: RefObject<HTMLElement | null>,
+    active: boolean,
+    onDismiss: () => void
+): void {
+    useEffect(() => {
+        if (!active) return
+        const onPointerDown = (event: PointerEvent) => {
+            const target = event.target as Element
+            const surface = ref.current
+            if (
+                surface &&
+                (surface.contains(target) ||
+                    ownsFloatingLayer(surface, target))
+            )
+                return
+            onDismiss()
+        }
+        const onKeyDown = (event: KeyboardEvent) => {
+            if (event.defaultPrevented) return
+            if (
+                ref.current &&
+                ownsFloatingLayer(
+                    ref.current,
+                    document.activeElement
+                )
+            )
+                return
+            if (event.key === "Escape") {
+                event.preventDefault()
+                onDismiss()
+            }
+        }
+        document.addEventListener(
+            "pointerdown",
+            onPointerDown
+        )
+        window.addEventListener("keydown", onKeyDown)
+        return () => {
+            document.removeEventListener(
+                "pointerdown",
+                onPointerDown
+            )
+            window.removeEventListener("keydown", onKeyDown)
+        }
+    }, [ref, active, onDismiss])
+}

package/src/hooks/use-media-query.ts

@@ -0,0 +1,106 @@
+import { useCallback, useSyncExternalStore } from "react"
+
+const BREAKPOINTS = {
+    "2xl": 1536,
+    "3xl": 1600,
+    "4xl": 2000,
+    lg: 1024,
+    md: 800,
+    sm: 640,
+    xl: 1280,
+} as const
+
+export type Breakpoint = keyof typeof BREAKPOINTS
+export type BreakpointQuery =
+    | Breakpoint
+    | `max-${Breakpoint}`
+    | `${Breakpoint}:max-${Breakpoint}`
+function resolveMin(value: Breakpoint | number): string {
+    const px =
+        typeof value === "number" ? value : BREAKPOINTS[value]
+    return `(min-width: ${px}px)`
+}
+
+function resolveMax(value: Breakpoint | number): string {
+    const px =
+        typeof value === "number" ? value : BREAKPOINTS[value]
+    return `(max-width: ${px - 1}px)`
+}
+
+function parseQuery(
+    query: BreakpointQuery | MediaQueryInput | (string & {})
+): string {
+    if (typeof query !== "string") {
+        const parts: string[] = []
+        if (query.min != null)
+            parts.push(resolveMin(query.min))
+        if (query.max != null)
+            parts.push(resolveMax(query.max))
+        if (query.pointer === "coarse")
+            parts.push("(pointer: coarse)")
+        if (query.pointer === "fine")
+            parts.push("(pointer: fine)")
+        if (parts.length === 0) return "(min-width: 0px)"
+        return parts.join(" and ")
+    }
+
+    if (query.startsWith("(")) return query
+
+    const parts: string[] = []
+    for (const segment of query.split(":")) {
+        if (segment.startsWith("max-")) {
+            const bp = segment.slice(4)
+            if (bp in BREAKPOINTS)
+                parts.push(resolveMax(bp as Breakpoint))
+        } else if (segment in BREAKPOINTS) {
+            parts.push(resolveMin(segment as Breakpoint))
+        }
+    }
+
+    return parts.length > 0 ? parts.join(" and ") : query
+}
+
+function getServerSnapshot(): boolean {
+    return false
+}
+
+export type MediaQueryInput = {
+    min?: Breakpoint | number
+    max?: Breakpoint | number
+    /** Touch-like input (finger). Use "fine" for mouse/trackpad. */
+    pointer?: PointerPrecision
+}
+
+export type PointerPrecision = "coarse" | "fine"
+
+export function useMediaQuery(
+    query: BreakpointQuery | MediaQueryInput | (string & {})
+): boolean {
+    const mediaQuery = parseQuery(query)
+
+    const subscribe = useCallback(
+        (callback: () => void) => {
+            if (typeof window === "undefined") return () => {}
+            const mql = window.matchMedia(mediaQuery)
+            mql.addEventListener("change", callback)
+            return () =>
+                mql.removeEventListener("change", callback)
+        },
+        [mediaQuery]
+    )
+
+    const getSnapshot = useCallback(() => {
+        if (typeof window === "undefined") return false
+        return window.matchMedia(mediaQuery).matches
+    }, [mediaQuery])
+
+    return useSyncExternalStore(
+        subscribe,
+        getSnapshot,
+        getServerSnapshot
+    )
+}
+
+export function useIsMobile(): boolean {
+    return useMediaQuery("(max-width: 768px)")
+}