@passui/react 0.0.0-stage → 0.1.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pherus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# Passui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Passui is Pherus's design system: native React controls, design tokens and
+themes, with names drawn from SwiftUI. What Liquid Glass is to Apple and
+Material 3 is to Google, built for any React app.
+
+**Docs, live playgrounds and examples: [passui.pherus.org](https://passui.pherus.org)**
+
+## What's inside
+
+- **Controls**: buttons, fields, pickers, toggles, sheets, dialogs,
+  popovers, toasts, menus, tables and more, written as plain React you
+  can read.
+- **Design tokens**: color roles for light and dark, seven accents, text
+  styles named as SwiftUI names them, corners and springs.
+- **Appearance**: theme and platform providers, so every control follows
+  the system it runs on, with `ios:`, `android:`, `macos:`, `windows:`
+  and `linux:` variants.
+- **Typeset**: calm styles for long-form writing.
+
+## Using it
+
+Install the public npm package in a React 19 app with Tailwind CSS 4:
+
+```bash
+bun add @passui/react
+```
+
+Import the styles once and each control from its own entry point:
+
+```css
+@import "@passui/react/styles.css";
+```
+
+```tsx
+import { Button } from "@passui/react/button"
+
+export function SaveButton() {
+    return <Button variant="accent">Save</Button>
+}
+```
+
+See [Installation](https://passui.pherus.org/docs/installation) for the
+root setup, and [Skills](https://passui.pherus.org/docs/skills) to give AI
+agents Passui's rules.
+
+Passui works independently of TanStack. If your app uses TanStack Form,
+Table or Router, the optional `@passui/tanstack` package connects them to
+Passui's controls.
+
+## Development and publishing
+
+```bash
+bun install
+bun run typecheck
+bun run test
+bun run publish:check
+```
+
+The package exports TypeScript and TSX source. Your app's bundler must
+process those files and its stylesheet through Tailwind CSS 4.
+
+The GitHub Actions `publish.yml` workflow publishes from `main` using
+npm's trusted publisher connection and the `npm-publish` environment.
+It installs and validates with Bun, packs with Bun, then publishes the
+archive with npm's OIDC support. It needs no stored npm token.
+
+For a manual release, login to npm with an account that can publish
+under `@passui`, then run `bun publish`. The package configuration
+selects the public npm registry and public access. Keep credentials in
+your user npm configuration.
+
+## Principles
+
+- Ask what Apple would do, then add our own touch.
+- Name things as SwiftUI does: `Toggle`, `Picker`, `Sheet`, `footnote`.
+- Use named tokens, never one-off colors, sizes or shadows.
+- Every string comes from the app, so every app can translate.
+- Respect the system: light and dark, text size, Reduce Motion and each
+  platform's look.
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -1,6 +1,97 @@
 {
-  "name": "@passui/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@passui/react",
+    "version": "0.1.14",
+    "description": "Passui: native React controls, design tokens, presentation and appearance.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/phe-rus/passui.git",
+        "directory": "packages/ui"
+    },
+    "homepage": "https://passui.pherus.org",
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org",
+        "access": "public"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "type": "module",
+    "exports": {
+        "./table": "./src/components/table/table.tsx",
+        "./search-list": "./src/components/search-list/search-list.tsx",
+        "./profile-image": "./src/components/profile-image/profile-image.tsx",
+        "./popover": "./src/components/popover/popover.tsx",
+        "./sheet": "./src/components/sheet/sheet.tsx",
+        "./use-dismiss": "./src/hooks/use-dismiss.ts",
+        "./toast": "./src/components/toast/toast-store.ts",
+        "./toaster": "./src/components/toast/toaster.tsx",
+        "./tab-view": "./src/components/tab-view/tab-view.tsx",
+        "./sidebar": "./src/components/sidebar/sidebar.tsx",
+        "./icon-button": "./src/components/button/icon-button.tsx",
+        "./secure-field": "./src/components/secure-field/secure-field.tsx",
+        "./text-field": "./src/components/text-field/text-field.tsx",
+        "./text-editor": "./src/components/text-editor/text-editor.tsx",
+        "./button": "./src/components/button/button.tsx",
+        "./toggle": "./src/components/toggle/toggle.tsx",
+        "./cn": "./src/lib/class-names.ts",
+        ".": "./src/index.ts",
+        "./base.css": "./src/styles/base.css",
+        "./utilities.css": "./src/styles/utilities.css",
+        "./theme.css": "./src/styles/theme.css",
+        "./tokens": "./src/tokens.ts",
+        "./date-picker": "./src/components/date-picker/date-picker.tsx",
+        "./compact-date-picker": "./src/components/compact-date-picker/compact-date-picker.tsx",
+        "./compact-time-picker": "./src/components/compact-time-picker/compact-time-picker.tsx",
+        "./view-controller": "./src/components/view-controller/index.ts",
+        "./content-view": "./src/components/content-view/index.ts",
+        "./ambient": "./src/components/ambient/index.ts",
+        "./stat-tile": "./src/components/stat-tile/index.ts",
+        "./conversation": "./src/components/conversation/index.ts",
+        "./locale-switcher": "./src/components/locale-switcher/index.ts",
+        "./date": "./src/lib/date.ts",
+        "./language": "./src/lib/language.ts",
+        "./shapes": "./src/lib/shapes.ts",
+        "./appearance": "./src/appearance/index.ts",
+        "./use-media-query": "./src/hooks/use-media-query.ts",
+        "./typeset.css": "./src/styles/typeset.css",
+        "./styles.css": "./src/styles/styles.css",
+        "./dialog": "./src/components/dialog/index.ts",
+        "./docs": "./src/docs/index.ts"
+    },
+    "scripts": {
+        "generate": "bun run --cwd ../tokens generate",
+        "test": "vitest run",
+        "typecheck": "tsc -p tsconfig.json",
+        "publish:check": "bun pm pack --dry-run",
+        "build": "bun run generate"
+    },
+    "packageManager": "bun@1.4.2",
+    "peerDependencies": {
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0",
+        "tailwindcss": "^4.3.3"
+    },
+    "devDependencies": {
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0",
+        "typescript": "^7.0.2",
+        "tailwindcss": "^4.3.3",
+        "@types/node": "^26.6.3",
+        "vitest": "5.0.5",
+        "vite": "8.3.5"
+    },
+    "dependencies": {
+        "@hugeicons/core-free-icons": "4.3.5",
+        "@hugeicons/react": "1.1.10",
+        "motion": "13.5.0",
+        "clsx": "^2.1.1",
+        "tailwind-merge": "^3.7.0",
+        "tw-animate-css": "^1.4.0",
+        "@passui/tokens": "^0.1.0"
+    }
+}

package/src/appearance/index.ts

@@ -0,0 +1,2 @@
+export * from "./platform"
+export * from "./theme"

package/src/appearance/platform.tsx

@@ -0,0 +1,123 @@
+import {
+    createContext,
+    useContext,
+    useEffect,
+    useState,
+    type PropsWithChildren,
+} from "react"
+
+export type PlatformOS =
+    | "ios"
+    | "android"
+    | "macos"
+    | "windows"
+    | "linux"
+    | "unknown"
+
+const PlatformContext = createContext<PlatformOS>("unknown")
+
+export function detectPlatform(
+    userAgent: string,
+    platform: string,
+    maxTouchPoints: number
+): PlatformOS {
+    return resolvePlatform(
+        null,
+        userAgent,
+        platform,
+        maxTouchPoints
+    )
+}
+
+export function resolvePlatform(
+    override: string | null,
+    userAgent: string,
+    platform: string,
+    maxTouchPoints: number
+): PlatformOS {
+    if (
+        override === "ios" ||
+        override === "android" ||
+        override === "macos" ||
+        override === "windows" ||
+        override === "linux" ||
+        override === "unknown"
+    ) {
+        return override
+    }
+
+    if (/android/i.test(userAgent)) return "android"
+    if (/iPhone|iPad|iPod/i.test(userAgent)) return "ios"
+    if (platform === "MacIntel" && maxTouchPoints > 1)
+        return "ios"
+    if (/Mac/i.test(platform)) return "macos"
+    if (/Win/i.test(platform)) return "windows"
+    if (/Linux/i.test(platform)) return "linux"
+    return "unknown"
+}
+
+function initializePlatform(
+    resolve: typeof resolvePlatform,
+    root: HTMLElement,
+    userAgent: string,
+    platform: string,
+    maxTouchPoints: number
+) {
+    root.setAttribute(
+        "data-os",
+        resolve(
+            root.getAttribute("data-os"),
+            userAgent,
+            platform,
+            maxTouchPoints
+        )
+    )
+}
+
+export function PlatformScript({
+    nonce,
+}: {
+    nonce?: string
+}) {
+    return (
+        <script
+            // Run the library's platform bootstrap before first paint.
+            dangerouslySetInnerHTML={{
+                __html: `(${initializePlatform.toString()})(${resolvePlatform.toString()}, document.documentElement, navigator.userAgent, navigator.platform, navigator.maxTouchPoints)`,
+            }}
+            nonce={nonce}
+            suppressHydrationWarning
+        />
+    )
+}
+
+export function PlatformProvider({
+    children,
+}: PropsWithChildren) {
+    const [platform, setPlatform] =
+        useState<PlatformOS>("unknown")
+
+    useEffect(() => {
+        const resolved = resolvePlatform(
+            document.documentElement.getAttribute("data-os"),
+            navigator.userAgent,
+            navigator.platform,
+            navigator.maxTouchPoints
+        )
+        document.documentElement.setAttribute(
+            "data-os",
+            resolved
+        )
+        setPlatform(resolved)
+    }, [])
+
+    return (
+        <PlatformContext.Provider value={platform}>
+            {children}
+        </PlatformContext.Provider>
+    )
+}
+
+export function usePlatform() {
+    return useContext(PlatformContext)
+}