@passui/react 0.0.0-stage → 0.1.15

package/src/lib/anchored-placement.ts

@@ -0,0 +1,92 @@
+import { screenEdges } from "./screen-edges"
+
+export interface AnchoredPlacement {
+    left: number
+    width: number
+    top?: number
+    bottom?: number
+    /** Opens upward, so motion should grow from the bottom edge. */
+    above: boolean
+    /**
+     * Set when the chosen side has less room than the panel needs: the
+     * panel scrolls inside this height instead of crossing the edge.
+     */
+    maxHeight?: number
+}
+
+/** The measurements placement decides on, so the math stays testable. */
+export interface PlacementFrame {
+    anchor: { top: number; bottom: number; left: number }
+    viewport: { width: number; height: number }
+    edges: {
+        top: number
+        right: number
+        bottom: number
+        left: number
+    }
+}
+
+/**
+ * Places a panel of `width` under its anchor, or above it when there's
+ * less than `needed` height below and more room above, kept inside the
+ * screen's safe edges.
+ */
+export function placeInViewport(
+    { anchor, viewport, edges }: PlacementFrame,
+    width: number,
+    needed: number,
+    gap = 6
+): AnchoredPlacement {
+    const fitted = Math.min(
+        width,
+        viewport.width - edges.left - edges.right
+    )
+    const left = Math.min(
+        Math.max(edges.left, anchor.left),
+        viewport.width - fitted - edges.right
+    )
+    const roomBelow =
+        viewport.height - anchor.bottom - gap - edges.bottom
+    const roomAbove = anchor.top - gap - edges.top
+    const above = roomBelow < needed && roomAbove > roomBelow
+    const room = above ? roomAbove : roomBelow
+    const placement: AnchoredPlacement = {
+        left,
+        width: fitted,
+        above,
+        ...(above
+            ? { bottom: viewport.height - anchor.top + gap }
+            : { top: anchor.bottom + gap }),
+    }
+    if (room < needed) placement.maxHeight = room
+    return placement
+}
+
+/** `placeInViewport` from live DOM measurements. */
+export function placeAnchored(
+    anchor: HTMLElement,
+    width: number,
+    needed: number,
+    gap = 6
+): AnchoredPlacement {
+    const rect = anchor.getBoundingClientRect()
+    const viewport = window.visualViewport
+    return placeInViewport(
+        {
+            anchor: {
+                top: rect.top,
+                bottom: rect.bottom,
+                left: rect.left,
+            },
+            viewport: {
+                width: viewport?.width ?? window.innerWidth,
+                height:
+                    viewport?.height ?? window.innerHeight,
+            },
+            edges: screenEdges(),
+        },
+        width,
+        needed,
+        gap
+    )
+}

package/src/lib/class-names.ts

@@ -0,0 +1,21 @@
+import { clsx } from "clsx"
+import type { ClassValue } from "clsx"
+import { extendTailwindMerge } from "tailwind-merge"
+import { textStyles } from "@passui/tokens/typography"
+
+const textStyleClasses = Object.keys(textStyles).map(
+    (name) =>
+        `text-${name.replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`)}`
+)
+
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: {
+            "font-size": textStyleClasses,
+        },
+    },
+})
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs))
+}

package/src/lib/date.ts

@@ -0,0 +1,96 @@
+// Dates through the platform's own Intl, no date library in the bundle.
+// en-US on purpose: the server renders first, so a viewer-specific locale
+// would make server and browser disagree on hydration.
+const LOCALE = "en-US"
+
+const PRESETS = {
+    /** Aug 30, 2026 */
+    PP: { dateStyle: "medium" },
+    /** August 30, 2026 */
+    PPP: { dateStyle: "long" },
+    /** Aug 30, 2026, 2:15 PM */
+    PPp: { dateStyle: "medium", timeStyle: "short" },
+    /** August 30, 2026 at 2:15 PM */
+    PPPp: { dateStyle: "long", timeStyle: "short" },
+    /** Aug 30 */
+    "MMM d": { month: "short", day: "numeric" },
+    /** Aug 30, 14:15 */
+    "MMM d, HH:mm": {
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+    },
+    /** Aug 30, 14:15:09 */
+    "MMM d, HH:mm:ss": {
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+    },
+} satisfies Record<string, Intl.DateTimeFormatOptions>
+
+export type DatePreset = keyof typeof PRESETS
+
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+function formatter(
+    key: string,
+    options: Intl.DateTimeFormatOptions
+) {
+    let cached = formatters.get(key)
+    if (!cached) {
+        cached = new Intl.DateTimeFormat(LOCALE, options)
+        formatters.set(key, cached)
+    }
+    return cached
+}
+
+/** A stored UTC timestamp shown as its UTC wall-clock time, whatever the viewer's timezone. */
+export function formatUtc(
+    date: Date | string | number,
+    preset: DatePreset
+) {
+    return formatter(`utc:${preset}`, {
+        ...PRESETS[preset],
+        timeZone: "UTC",
+    }).format(new Date(date))
+}
+
+/** The viewer's local time of day, like 2:15 PM. */
+export function formatTime(date: Date | string | number) {
+    return formatter("local:time", {
+        timeStyle: "short",
+    }).format(new Date(date))
+}
+
+const UNITS: [Intl.RelativeTimeFormatUnit, number][] = [
+    ["year", 31_536_000],
+    ["month", 2_592_000],
+    ["week", 604_800],
+    ["day", 86_400],
+    ["hour", 3_600],
+    ["minute", 60],
+]
+
+let relative: Intl.RelativeTimeFormat | undefined
+
+/** "5 minutes ago", "in 30 days": the largest whole unit that fits. */
+export function fromNow(date: Date | string | number) {
+    relative ??= new Intl.RelativeTimeFormat(LOCALE, {
+        numeric: "auto",
+    })
+    const seconds =
+        (new Date(date).getTime() - Date.now()) / 1000
+    for (const [unit, size] of UNITS) {
+        if (Math.abs(seconds) >= size)
+            return relative.format(
+                Math.round(seconds / size),
+                unit
+            )
+    }
+    return relative.format(0, "second")
+}

package/src/lib/floating-layers.ts

@@ -0,0 +1,28 @@
+export const FLOATING_LAYER = "data-floating-layer"
+
+const anchors = new WeakMap<Element, Element>()
+
+/** Portals retain the ownership of the control that opened them. */
+export function registerFloatingLayer(
+    layer: Element,
+    anchor: Element
+): () => void {
+    anchors.set(layer, anchor)
+    return () => anchors.delete(layer)
+}
+
+export function ownsFloatingLayer(
+    container: Element,
+    target: Element | null
+): boolean {
+    let layer = target?.closest(`[${FLOATING_LAYER}]`)
+    const visited = new Set<Element>()
+    while (layer && !visited.has(layer)) {
+        visited.add(layer)
+        const anchor = anchors.get(layer)
+        if (!anchor) return false
+        if (container.contains(anchor)) return true
+        layer = anchor.closest(`[${FLOATING_LAYER}]`)
+    }
+    return false
+}

package/src/lib/haptics.ts

@@ -0,0 +1,25 @@
+/** The feedback kinds the systems share, from a selection tick to an error. */
+export type HapticKind =
+    | "selection"
+    | "light"
+    | "medium"
+    | "heavy"
+    | "success"
+    | "warning"
+    | "error"
+
+let player: (kind: HapticKind) => void = () => {}
+
+/**
+ * Components only ask for feedback; the app decides how it plays on this
+ * device (system haptics, a vibration, or nothing) and whether it's on.
+ */
+export function setHapticPlayer(
+    next: (kind: HapticKind) => void
+): void {
+    player = next
+}
+
+export function haptic(kind: HapticKind): void {
+    player(kind)
+}

package/src/lib/language.ts

@@ -0,0 +1,21 @@
+/** A language's name in itself, capitalized: "Français", "中文". */
+export function getNativeLanguageName(tag: string) {
+    const name = new Intl.DisplayNames([tag], {
+        type: "language",
+    }).of(tag)
+    return name
+        ? name.charAt(0).toUpperCase() + name.slice(1)
+        : tag
+}
+
+/** A language's name as read in `displayLocale`: "French" in English. */
+export function getLocalizedLanguageName(
+    tag: string,
+    displayLocale: string
+) {
+    return (
+        new Intl.DisplayNames([displayLocale], {
+            type: "language",
+        }).of(tag) ?? tag
+    )
+}

package/src/lib/screen-edges.ts

@@ -0,0 +1,45 @@
+export interface ScreenEdges {
+    top: number
+    right: number
+    bottom: number
+    left: number
+}
+
+let probe: HTMLDivElement | undefined
+
+/**
+ * How far menus and popovers keep from each side of the screen: clear of
+ * the status bar, gesture bar and notch, and on touch screens a little
+ * further from the glass, as the systems' own menus are.
+ */
+export function screenEdges(): ScreenEdges {
+    const margin =
+        typeof window !== "undefined" &&
+        window.matchMedia("(pointer: coarse)").matches
+            ? 12
+            : 8
+    if (typeof document === "undefined") {
+        return {
+            top: margin,
+            right: margin,
+            bottom: margin,
+            left: margin,
+        }
+    }
+    if (!probe) {
+        probe = document.createElement("div")
+        probe.setAttribute("aria-hidden", "true")
+        probe.style.cssText =
+            "position:fixed;inset:0;visibility:hidden;pointer-events:none;" +
+            "padding:env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left)"
+    }
+    if (!probe.isConnected) document.body.appendChild(probe)
+    const style = getComputedStyle(probe)
+    return {
+        top: Number.parseFloat(style.paddingTop) + margin,
+        right: Number.parseFloat(style.paddingRight) + margin,
+        bottom:
+            Number.parseFloat(style.paddingBottom) + margin,
+        left: Number.parseFloat(style.paddingLeft) + margin,
+    }
+}

package/src/lib/shapes.ts

@@ -0,0 +1,70 @@
+/** Material 3 expressive outlines: a circle and the scalloped "cookie", "clover", and "sunny" shapes. */
+export const shapes = [
+    "circle",
+    "cookie4",
+    "cookie6",
+    "cookie9",
+    "clover",
+    "sunny",
+    /** Reserved for the Pherus mark itself, so it never matches a project's icon. */
+    "cookie12",
+] as const
+
+export type Shape = (typeof shapes)[number]
+
+/** Lobe count and wave depth (as a fraction of the radius) for each wavy shape. */
+const waves: Record<
+    Exclude<Shape, "circle">,
+    { lobes: number; depth: number }
+> = {
+    cookie4: { lobes: 4, depth: 0.08 },
+    cookie6: { lobes: 6, depth: 0.07 },
+    cookie9: { lobes: 9, depth: 0.055 },
+    clover: { lobes: 4, depth: 0.16 },
+    sunny: { lobes: 8, depth: 0.045 },
+    cookie12: { lobes: 12, depth: 0.04 },
+}
+
+const STEPS = 144
+
+/**
+ * An SVG path for a Material 3 expressive shape centred on (cx, cy): a circle
+ * whose radius rides a cosine wave, which gives the soft scalloped "cookie",
+ * "clover", and "sunny" outlines. The wave is normalised so every shape fills
+ * the same `r`, keeping icons optically the same size.
+ */
+export function shapePath(
+    shape: Shape,
+    cx: number,
+    cy: number,
+    r: number
+) {
+    if (shape === "circle") {
+        return `M ${cx - r} ${cy} a ${r} ${r} 0 1 0 ${r * 2} 0 a ${r} ${r} 0 1 0 ${-r * 2} 0 Z`
+    }
+
+    const { lobes, depth } = waves[shape]
+    const base = r / (1 + depth)
+    const points: string[] = []
+    for (let i = 0; i < STEPS; i++) {
+        const theta = (i / STEPS) * Math.PI * 2 - Math.PI / 2
+        const radius =
+            base *
+            (1 +
+                depth *
+                    Math.cos(lobes * (theta + Math.PI / 2)))
+        const x = cx + radius * Math.cos(theta)
+        const y = cy + radius * Math.sin(theta)
+        points.push(
+            `${i === 0 ? "M" : "L"} ${x.toFixed(2)} ${y.toFixed(2)}`
+        )
+    }
+    return `${points.join(" ")} Z`
+}
+
+/**
+ * The app wide `dualTone` rule dims every svg path for two tone icons; a
+ * drawn shape or illustration opts out with this so its colors stay true.
+ */
+export const plainSvg =
+    "cursor-[inherit] [&_path]:opacity-100 [&_path]:transform-none"

package/src/motion/transitions.ts

@@ -0,0 +1,30 @@
+import { springs } from "@passui/tokens/motion"
+import type { Transition } from "motion/react"
+
+/** Design-token springs as motion/react transitions. */
+export const spring = {
+    smooth: { type: "spring", ...springs.smooth },
+    snappy: { type: "spring", ...springs.snappy },
+    bouncy: { type: "spring", ...springs.bouncy },
+} as const satisfies Record<keyof typeof springs, Transition>
+
+/** Menus, popovers and floating toolbars: grow from their anchor. */
+export const popoverMotion = {
+    initial: { opacity: 0, scale: 0.94, y: -6 },
+    animate: { opacity: 1, scale: 1, y: 0 },
+    exit: {
+        opacity: 0,
+        scale: 0.97,
+        y: -4,
+        transition: { duration: 0.12 },
+    },
+    transition: spring.snappy,
+} as const
+
+/** Floating bars that rise from the bottom edge. */
+export const riseMotion = {
+    initial: { opacity: 0, y: 32 },
+    animate: { opacity: 1, y: 0 },
+    exit: { opacity: 0, y: 24 },
+    transition: spring.smooth,
+} as const

package/src/styles/base.css

@@ -0,0 +1 @@
+@import "@passui/tokens/base.css";

package/src/styles/styles.css

@@ -0,0 +1,3 @@
+@import "@passui/tokens/styles.css";
+
+@source "../";

package/src/styles/theme.css

@@ -0,0 +1 @@
+@import "@passui/tokens/theme.css";

package/src/styles/typeset.css

@@ -0,0 +1 @@
+@import "@passui/tokens/typeset.css";

package/src/styles/utilities.css

@@ -0,0 +1 @@
+@import "@passui/tokens/utilities.css";

package/src/tokens.ts

@@ -0,0 +1 @@
+export * from "@passui/tokens"