@brdgapp/ui 0.1.2 → 1.0.0

package/hooks/use-theme.js

@@ -0,0 +1,34 @@
+"use client";
+import { useCallback, useSyncExternalStore } from "react";
+import { applyTheme, DARK_QUERY, readPreference, resolveTheme, writePreference } from "@brdgapp/ui/lib/theme";
+// One small store for the theme, shared by every useTheme() on the page. No provider to wrap the app in.
+// It follows the device while the choice is System, and picks up a choice made in another Bridge app when
+// people come back to this tab.
+const CHANGE = "bridge-theme-change";
+let listening = false;
+function sync() {
+    applyTheme(resolveTheme(readPreference()));
+    window.dispatchEvent(new Event(CHANGE));
+}
+function subscribe(onChange) {
+    if (!listening) {
+        listening = true;
+        window.matchMedia(DARK_QUERY).addEventListener("change", sync);
+        window.addEventListener("focus", sync);
+        document.addEventListener("visibilitychange", () => document.visibilityState === "visible" && sync());
+    }
+    window.addEventListener(CHANGE, onChange);
+    return () => window.removeEventListener(CHANGE, onChange);
+}
+const snapshot = () => `${readPreference()}:${resolveTheme(readPreference())}`;
+// Before the page has loaded there's no saved choice to read: report System, drawn light.
+const serverSnapshot = () => "system:light";
+/** The theme choice, what's drawn, and a way to change it. Needs `themeScript` in the root layout's <head>. */
+export function useTheme() {
+    const [theme, resolvedTheme] = useSyncExternalStore(subscribe, snapshot, serverSnapshot).split(":");
+    const setTheme = useCallback((next) => {
+        writePreference(next);
+        sync();
+    }, []);
+    return { theme, resolvedTheme, setTheme };
+}

package/lib/demo-controls.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from "react";
+/**
+ * Global settings for handbook demos: how slow fake data is, whether it fails, and a "replay" counter
+ * that makes every demo load again. Read by `useMockQuery`. Demo-only — product code never uses it.
+ */
+type DemoControls = {
+    /** Fake network delay in milliseconds. */
+    latency: number;
+    /** When true, every mock query fails, so error states can be seen. */
+    fail: boolean;
+    /** Bumped by `replay()`; every mock query reloads when it changes. */
+    replayKey: number;
+    setLatency: (ms: number) => void;
+    setFail: (fail: boolean) => void;
+    replay: () => void;
+};
+declare const DEFAULT_LATENCY = 900;
+declare function DemoControlsProvider({ children }: {
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<DemoControls | null>>;
+/** Outside a provider, demos still work with the defaults (no failure, default delay). */
+declare function useDemoControls(): DemoControls;
+export { DemoControlsProvider, useDemoControls, DEFAULT_LATENCY };
+export type { DemoControls };

package/lib/demo-controls.js

@@ -0,0 +1,24 @@
+"use client";
+import { createContext, createElement, useCallback, useContext, useMemo, useState } from "react";
+const DEFAULT_LATENCY = 900;
+const DemoControlsContext = createContext(null);
+function DemoControlsProvider({ children }) {
+    const [latency, setLatency] = useState(DEFAULT_LATENCY);
+    const [fail, setFail] = useState(false);
+    const [replayKey, setReplayKey] = useState(0);
+    const replay = useCallback(() => setReplayKey((k) => k + 1), []);
+    const value = useMemo(() => ({ latency, fail, replayKey, setLatency, setFail, replay }), [latency, fail, replayKey, replay]);
+    return createElement(DemoControlsContext.Provider, { value }, children);
+}
+/** Outside a provider, demos still work with the defaults (no failure, default delay). */
+function useDemoControls() {
+    return (useContext(DemoControlsContext) ?? {
+        latency: DEFAULT_LATENCY,
+        fail: false,
+        replayKey: 0,
+        setLatency: () => { },
+        setFail: () => { },
+        replay: () => { },
+    });
+}
+export { DemoControlsProvider, useDemoControls, DEFAULT_LATENCY };

package/lib/format.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A count. In full with a comma under 10,000 (1,284); compact from 10,000 with a capital K or M and at
+ * most one decimal, never ".0" (12K, 12.5K, 1.3M).
+ */
+export declare function formatCount(n: number): string;
+/** Money in whole dollars, the same steps as counts: $950, $9,500, $270K, $1.2M; a minus before the symbol. */
+export declare function formatMoney(n: number): string;
+/** A share: no space, at most one decimal, never ".0" (92.4%, 2%). */
+export declare function formatPercent(n: number): string;
+/**
+ * A date as Bridge writes it: relative under 7 days (Today, Yesterday, 4 days ago), then the date
+ * (Jul 20), with the year when it isn't this year (Jul 20, 2025). Future dates are always absolute.
+ * `now` is for tests and fixed examples; it defaults to the current time.
+ */
+export declare function formatDate(date: Date | string, now?: Date): string;
+/** A time of day: 12-hour with minutes, a space, then AM or PM (9:40 AM). */
+export declare function formatTime(date: Date | string): string;

package/lib/format.js

@@ -0,0 +1,55 @@
+// Bridge's writing rules for numbers, money, dates and times, as functions, so every app formats them the
+// same way (handbook → Brand → Writing). American English (decision 2026-11-03).
+const COMPACT_FROM = 10_000;
+/** Strips a trailing ".0" so 12.0 reads 12. */
+const oneDecimal = (n) => {
+    const s = n.toFixed(1);
+    return s.endsWith(".0") ? s.slice(0, -2) : s;
+};
+/**
+ * A count. In full with a comma under 10,000 (1,284); compact from 10,000 with a capital K or M and at
+ * most one decimal, never ".0" (12K, 12.5K, 1.3M).
+ */
+export function formatCount(n) {
+    const sign = n < 0 ? "-" : "";
+    const a = Math.abs(n);
+    // From 999,950 the K form would round to "1000K", so it becomes 1M.
+    if (a >= 999_950)
+        return `${sign}${oneDecimal(a / 1_000_000)}M`;
+    if (a >= COMPACT_FROM)
+        return `${sign}${oneDecimal(a / 1_000)}K`;
+    return `${sign}${Math.round(a).toLocaleString("en-US")}`;
+}
+/** Money in whole dollars, the same steps as counts: $950, $9,500, $270K, $1.2M; a minus before the symbol. */
+export function formatMoney(n) {
+    const body = formatCount(Math.abs(n));
+    return `${n < 0 ? "-" : ""}$${body}`;
+}
+/** A share: no space, at most one decimal, never ".0" (92.4%, 2%). */
+export function formatPercent(n) {
+    return `${oneDecimal(n)}%`;
+}
+const DAY = 86_400_000;
+const startOfDay = (d) => Date.UTC(d.getFullYear(), d.getMonth(), d.getDate());
+/**
+ * A date as Bridge writes it: relative under 7 days (Today, Yesterday, 4 days ago), then the date
+ * (Jul 20), with the year when it isn't this year (Jul 20, 2025). Future dates are always absolute.
+ * `now` is for tests and fixed examples; it defaults to the current time.
+ */
+export function formatDate(date, now = new Date()) {
+    const d = typeof date === "string" ? new Date(date) : date;
+    const days = Math.round((startOfDay(now) - startOfDay(d)) / DAY);
+    if (days === 0)
+        return "Today";
+    if (days === 1)
+        return "Yesterday";
+    if (days > 1 && days < 7)
+        return `${days} days ago`;
+    const sameYear = d.getFullYear() === now.getFullYear();
+    return d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: sameYear ? undefined : "numeric" });
+}
+/** A time of day: 12-hour with minutes, a space, then AM or PM (9:40 AM). */
+export function formatTime(date) {
+    const d = typeof date === "string" ? new Date(date) : date;
+    return d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" });
+}

package/lib/layout.d.ts

@@ -0,0 +1,19 @@
+/** How wide a page's content gets. Pick by the page's job. */
+export declare const PAGE_WIDTH: {
+    /** Tables and record pages with a side rail: 1600px. */
+    readonly wide: "max-w-[1600px]";
+    /** Card dashboards, grids and feeds: 1280px. */
+    readonly standard: "max-w-7xl";
+    /** A single column of reading: 800px. */
+    readonly read: "max-w-[800px]";
+    /** Forms and settings: 720px. */
+    readonly form: "max-w-[720px]";
+    /** A centred card outside the app, like sign-in: 448px. */
+    readonly narrow: "max-w-md";
+};
+/** The page's side edges: 16px on phones, 24px from 640px, 32px from 1024px. */
+export declare const PAGE_EDGES = "px-4 sm:px-6 lg:px-8";
+/** A page's frame: centred, its width, its edges, 24px from the top bar on phones and 32px from 640px. */
+export declare function pageFrame(width: keyof typeof PAGE_WIDTH): string;
+/** The side rail beside a record page's main column, from 1024px: 340px. */
+export declare const RAIL = "lg:grid-cols-[minmax(0,1fr)_340px]";

package/lib/layout.js

@@ -0,0 +1,24 @@
+// Page widths and edges, shared by every app (decisions 2026-11-03, from a survey of all 12 app repos).
+// Values from Bridge OS src/lib/layout/widths.ts, plus a narrow width for sign-in cards (apps used six
+// values between 360 and 560px). Classes, not numbers, so Tailwind generates them from the package.
+/** How wide a page's content gets. Pick by the page's job. */
+export const PAGE_WIDTH = {
+    /** Tables and record pages with a side rail: 1600px. */
+    wide: "max-w-[1600px]",
+    /** Card dashboards, grids and feeds: 1280px. */
+    standard: "max-w-7xl",
+    /** A single column of reading: 800px. */
+    read: "max-w-[800px]",
+    /** Forms and settings: 720px. */
+    form: "max-w-[720px]",
+    /** A centred card outside the app, like sign-in: 448px. */
+    narrow: "max-w-md",
+};
+/** The page's side edges: 16px on phones, 24px from 640px, 32px from 1024px. */
+export const PAGE_EDGES = "px-4 sm:px-6 lg:px-8";
+/** A page's frame: centred, its width, its edges, 24px from the top bar on phones and 32px from 640px. */
+export function pageFrame(width) {
+    return `mx-auto w-full ${PAGE_WIDTH[width]} ${PAGE_EDGES} pt-6 pb-12 sm:pt-8`;
+}
+/** The side rail beside a record page's main column, from 1024px: 340px. */
+export const RAIL = "lg:grid-cols-[minmax(0,1fr)_340px]";

package/lib/motion.d.ts

@@ -0,0 +1,16 @@
+/** Seconds, for Framer Motion's `duration`. */
+export declare const DURATION: {
+    /** 150ms: hover, color, press. */
+    readonly quick: 0.15;
+    /** 200ms: menus, sections, toasts: small things opening. */
+    readonly base: 0.2;
+    /** 300ms: drawers, sheets, dialogs: big things arriving. */
+    readonly slow: 0.3;
+};
+/** The one curve: fast out of the gate, gentle landing. Same as the package's `ease-out`. */
+export declare const EASE: readonly [0.23, 1, 0.32, 1];
+/** A ready-made transition for Framer Motion: `transition={transition("base")}`. */
+export declare function transition(speed?: keyof typeof DURATION): {
+    duration: 0.15 | 0.2 | 0.3;
+    ease: readonly [0.23, 1, 0.32, 1];
+};

package/lib/motion.js

@@ -0,0 +1,18 @@
+// Bridge's motion, for JavaScript animations (Framer Motion and the like). CSS uses the same values:
+// `duration-150` / `duration-200` / `duration-300` and `ease-out`, which the package sets to this curve.
+// Decision 2026-11-03: three speeds and one curve; the package itself stays CSS-only.
+/** Seconds, for Framer Motion's `duration`. */
+export const DURATION = {
+    /** 150ms: hover, color, press. */
+    quick: 0.15,
+    /** 200ms: menus, sections, toasts: small things opening. */
+    base: 0.2,
+    /** 300ms: drawers, sheets, dialogs: big things arriving. */
+    slow: 0.3,
+};
+/** The one curve: fast out of the gate, gentle landing. Same as the package's `ease-out`. */
+export const EASE = [0.23, 1, 0.32, 1];
+/** A ready-made transition for Framer Motion: `transition={transition("base")}`. */
+export function transition(speed = "base") {
+    return { duration: DURATION[speed], ease: EASE };
+}

package/lib/theme.d.ts

@@ -0,0 +1,21 @@
+export type ThemePreference = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+export declare const THEME_COOKIE = "bridge-theme";
+declare const DARK_QUERY = "(prefers-color-scheme: dark)";
+/** The saved choice: the shared cookie, then Bridge OS's old per-app key, then System. */
+export declare function readPreference(): ThemePreference;
+/** Saves the choice for every Bridge app: on brdg.app it's shared by all subdomains; elsewhere (localhost, previews) by this site. */
+export declare function writePreference(preference: ThemePreference): void;
+export declare function systemTheme(): ResolvedTheme;
+export declare function resolveTheme(preference: ThemePreference): ResolvedTheme;
+/**
+ * Puts the theme on <html>. Transitions are switched off for one frame while it changes, so every
+ * `transition-colors` on the page doesn't fade at once.
+ */
+export declare function applyTheme(theme: ResolvedTheme): void;
+/**
+ * Runs in <head> before the page paints, so someone in dark never sees a white flash. The same steps as
+ * readPreference and resolveTheme, written out because it can't import anything.
+ */
+export declare const themeScript = "(function(){try{var m=document.cookie.match(/(?:^|; )bridge-theme=(light|dark|system)/),p=m?m[1]:null;if(!p){try{p=localStorage.getItem(\"bridge-theme\")}catch(e){}}if(p!==\"light\"&&p!==\"dark\")p=\"system\";var t=p===\"dark\"||(p===\"system\"&&matchMedia(\"(prefers-color-scheme: dark)\").matches)?\"dark\":\"light\",r=document.documentElement;r.dataset.theme=t;r.style.colorScheme=t}catch(e){}})()";
+export { DARK_QUERY };

package/lib/theme.js

@@ -0,0 +1,63 @@
+// Light, dark or system, the same in every Bridge app. Decided 2026-11-03 (Aman): every web app offers dark
+// mode; the choice is Light, Dark or System (the default, following the device); one choice applies across
+// all Bridge apps, so it's kept in a cookie for the whole brdg.app domain. Built on Bridge OS's version
+// (src/lib/hooks/use-theme.tsx and the init script in its root layout), which kept it per app in
+// localStorage under "bridge-theme" and offered Light and Dark only; that key is still read, so people who
+// chose dark in Bridge OS keep it.
+export const THEME_COOKIE = "bridge-theme";
+const ONE_YEAR = 60 * 60 * 24 * 365;
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+function isPreference(v) {
+    return v === "light" || v === "dark" || v === "system";
+}
+/** The saved choice: the shared cookie, then Bridge OS's old per-app key, then System. */
+export function readPreference() {
+    if (typeof document === "undefined")
+        return "system";
+    const match = document.cookie.match(new RegExp(`(?:^|; )${THEME_COOKIE}=(light|dark|system)`));
+    if (match && isPreference(match[1]))
+        return match[1];
+    try {
+        const old = localStorage.getItem(THEME_COOKIE);
+        if (isPreference(old))
+            return old;
+    }
+    catch {
+        // Storage blocked: fall through to System.
+    }
+    return "system";
+}
+/** Saves the choice for every Bridge app: on brdg.app it's shared by all subdomains; elsewhere (localhost, previews) by this site. */
+export function writePreference(preference) {
+    const shared = /(^|\.)brdg\.app$/.test(location.hostname) ? "; Domain=.brdg.app" : "";
+    const secure = location.protocol === "https:" ? "; Secure" : "";
+    document.cookie = `${THEME_COOKIE}=${preference}; Path=/; Max-Age=${ONE_YEAR}; SameSite=Lax${shared}${secure}`;
+}
+export function systemTheme() {
+    return typeof window !== "undefined" && window.matchMedia(DARK_QUERY).matches ? "dark" : "light";
+}
+export function resolveTheme(preference) {
+    return preference === "system" ? systemTheme() : preference;
+}
+/**
+ * Puts the theme on <html>. Transitions are switched off for one frame while it changes, so every
+ * `transition-colors` on the page doesn't fade at once.
+ */
+export function applyTheme(theme) {
+    const root = document.documentElement;
+    if (root.dataset.theme === theme)
+        return;
+    const pause = document.createElement("style");
+    pause.textContent = "*,*::before,*::after{transition:none!important;animation:none!important}";
+    document.head.appendChild(pause);
+    root.dataset.theme = theme;
+    root.style.colorScheme = theme;
+    void window.getComputedStyle(document.body).opacity;
+    requestAnimationFrame(() => pause.remove());
+}
+/**
+ * Runs in <head> before the page paints, so someone in dark never sees a white flash. The same steps as
+ * readPreference and resolveTheme, written out because it can't import anything.
+ */
+export const themeScript = `(function(){try{var m=document.cookie.match(/(?:^|; )${THEME_COOKIE}=(light|dark|system)/),p=m?m[1]:null;if(!p){try{p=localStorage.getItem("${THEME_COOKIE}")}catch(e){}}if(p!=="light"&&p!=="dark")p="system";var t=p==="dark"||(p==="system"&&matchMedia("${DARK_QUERY}").matches)?"dark":"light",r=document.documentElement;r.dataset.theme=t;r.style.colorScheme=t}catch(e){}})()`;
+export { DARK_QUERY };

package/lib/utils.d.ts

@@ -0,0 +1,22 @@
+import type * as React from "react";
+import { type ClassValue } from "clsx";
+/**
+ * Bridge's class merger. Joins class names and lets a later class override an earlier one that sets
+ * the same thing, so `cn(base, className)` lets the caller win.
+ *
+ * Always import this one, never `clsx` or a local copy: when Bridge adds custom utilities (for example
+ * named text sizes), they get registered here with `extendTailwindMerge` so overrides keep working.
+ */
+/** Bridge's named type sizes (globals.css → @theme). Registered so `text-13` counts as a size, not a color. */
+declare const TYPE_SIZES: readonly ["11", "12", "13", "14", "16", "18", "22", "28", "36", "48"];
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Extra attributes a component passes straight to its main element (the button you click, the field you
+ * type in): `id`, `aria-*`, `data-*` and event handlers the component doesn't own itself. The component's
+ * own props win where they overlap.
+ */
+type ElementProps<E extends HTMLElement = HTMLElement> = Omit<React.HTMLAttributes<E>, "children" | "className" | "color" | "title" | "onClick" | "onChange" | "placeholder" | "defaultValue"> & {
+    [key: `data-${string}`]: string | undefined;
+};
+export { cn, TYPE_SIZES };
+export type { ElementProps };

package/lib/utils.js

@@ -0,0 +1,27 @@
+import { clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+/**
+ * Bridge's class merger. Joins class names and lets a later class override an earlier one that sets
+ * the same thing, so `cn(base, className)` lets the caller win.
+ *
+ * Always import this one, never `clsx` or a local copy: when Bridge adds custom utilities (for example
+ * named text sizes), they get registered here with `extendTailwindMerge` so overrides keep working.
+ */
+/** Bridge's named type sizes (globals.css → @theme). Registered so `text-13` counts as a size, not a color. */
+const TYPE_SIZES = ["11", "12", "13", "14", "16", "18", "22", "28", "36", "48"];
+// Bridge's page textures (globals.css): a pattern image and two overlays, not background colors. Registered so
+// `cn("bg-[var(--info-bg)] bg-dot-grid")` keeps both instead of dropping the color, and the three can stack.
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: {
+            "font-size": [{ text: [...TYPE_SIZES] }],
+            "bg-image": [{ bg: ["dot-grid"] }],
+            "bridge-noise": ["bg-noise"],
+            "bridge-glow": ["bg-glow-patches"],
+        },
+    },
+});
+function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}
+export { cn, TYPE_SIZES };

package/package.json

@@ -1,28 +1,44 @@
 {
   "name": "@brdgapp/ui",
-  "version": "0.1.2",
-  "description": "Shared Bridge UI components for Bridge apps.",
+  "version": "1.0.0",
+  "description": "Bridge's shared components, tokens and styles. Documented at handbook.brdg.app.",
   "license": "UNLICENSED",
+  "homepage": "https://handbook.brdg.app",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/intropath/apps/bridge-design-system.git",
+    "directory": "packages/ui"
+  },
   "type": "module",
   "sideEffects": [
     "**/*.css"
   ],
-  "files": [
-    "src"
-  ],
   "exports": {
-    ".": "./src/index.ts",
-    "./styles.css": "./src/styles.css"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+ssh://git@gitlab.com/intropath/packages/ui.git"
+    "./components/*": {
+      "types": "./components/*.d.ts",
+      "default": "./components/*.js"
+    },
+    "./hooks/*": {
+      "types": "./hooks/*.d.ts",
+      "default": "./hooks/*.js"
+    },
+    "./lib/*": {
+      "types": "./lib/*.d.ts",
+      "default": "./lib/*.js"
+    },
+    "./globals.css": "./styles/globals.css",
+    "./package.json": "./package.json"
   },
-  "publishConfig": {
-    "access": "public"
+  "dependencies": {
+    "@base-ui/react": "^1.9.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.6.0",
+    "tailwind-merge": "^3.7.0"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "react-dom": ">=18"
+    "react": ">=19",
+    "react-dom": ">=19",
+    "tailwindcss": ">=4"
   }
-}
+}