@baseworks/ui 0.0.0-stage → 0.2.1

package/src/theme.ts

@@ -0,0 +1,98 @@
+/**
+ * Theme.
+ *
+ * There is one palette — see tokens.css — in a light and a dark form. The
+ * operating system decides which, until someone says otherwise: `data-theme` on
+ * <html> forces a form in both directions, and `ThemeToggle` is the control
+ * that sets it.
+ *
+ * The choice is remembered in the realm's theme cookie, `bw_theme` — the one
+ * the pages a service draws read and write too (the sign-in page, the
+ * organization pages, the account pages; `@baseworks/core/pages`). So a theme
+ * chosen on `/account` is the theme the product opens in, and the other way
+ * round. It has to be restored before the first paint: `themeInitScript()` in
+ * <head>, or the page renders the system's answer and then flips.
+ *
+ * Until 0.2.1 the choice lived in localStorage under `<prefix>.theme`, where a
+ * server-drawn page could never see it. That key is still read when there is
+ * no cookie, so nobody's choice is lost, and still written, so an older copy
+ * of this package on the same origin keeps agreeing.
+ */
+
+export type ThemeMode = 'system' | 'light' | 'dark'
+
+const themeKey = (prefix: string) => `${prefix}.theme`
+
+/** The realm's theme cookie. Its values are `light`, `dark` and `auto`. */
+export const THEME_COOKIE = 'bw_theme'
+
+/** What the cookie says, or undefined when it is absent or says something else. */
+function cookieTheme(): ThemeMode | undefined {
+  if (typeof document === 'undefined') return undefined
+  const m = new RegExp(`(?:^|;\\s*)${THEME_COOKIE}=([^;]*)`).exec(document.cookie)
+  const v = m?.[1]
+  return v === 'light' || v === 'dark' ? v : v === 'auto' ? 'system' : undefined
+}
+
+/** The remembered choice: the cookie, else what an earlier version stored, else the system. */
+export function storedTheme(prefix = 'bw'): ThemeMode {
+  const fromCookie = cookieTheme()
+  if (fromCookie) return fromCookie
+  try {
+    const legacy = localStorage.getItem(themeKey(prefix))
+    if (legacy === 'light' || legacy === 'dark') return legacy
+  } catch { /* no storage: nothing was stored */ }
+  return 'system'
+}
+
+/** What the document is showing now — not what is stored. */
+export function currentTheme(): ThemeMode {
+  if (typeof document === 'undefined') return 'system'
+  const t = document.documentElement.dataset['theme']
+  return t === 'dark' || t === 'light' ? t : 'system'
+}
+
+/**
+ * What the viewer is actually seeing: the forced form if there is one, else the
+ * system's. This is the honest answer to "which theme is on" — `currentTheme()`
+ * says `system`, which is a setting, not a colour.
+ */
+export function resolvedTheme(): 'light' | 'dark' {
+  const forced = currentTheme()
+  if (forced !== 'system') return forced
+  if (typeof window === 'undefined') return 'light'
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+/**
+ * Force a form, or hand the decision back to the system. Remembered in the
+ * realm's cookie, so the pages a service draws agree; `prefix` only names the
+ * older localStorage key.
+ */
+export function applyTheme(mode: ThemeMode, prefix = 'bw'): void {
+  if (mode === 'system') delete document.documentElement.dataset['theme']
+  else document.documentElement.dataset['theme'] = mode
+  try {
+    const secure = location.protocol === 'https:' ? '; Secure' : ''
+    document.cookie = `${THEME_COOKIE}=${mode === 'system' ? 'auto' : mode}; Path=/; Max-Age=31536000; SameSite=Lax${secure}`
+  } catch { /* cookies refused: the choice just does not persist */ }
+  try { localStorage.setItem(themeKey(prefix), mode) } catch { /* private mode: the same */ }
+}
+
+/**
+ * The snippet for <head>, for a product that uses `applyTheme`. It is
+ * deliberately tiny and wrapped in try/catch: a browser that refuses cookies
+ * or localStorage must still render the page.
+ *
+ * It reads the realm's cookie first and the older localStorage key only when
+ * there is no cookie. `auto` in the cookie means "the system decides", which
+ * is what the page does with nothing set.
+ *
+ * A product with no toggle should still include this: its pages then open in
+ * the theme the person chose on the account page.
+ */
+export function themeInitScript(prefix = 'bw'): string {
+  return `try{var m=/(?:^|;\\s*)${THEME_COOKIE}=([^;]*)/.exec(document.cookie),t=m?m[1]:null;`
+    + `if(t===null)t=localStorage.getItem("${themeKey(prefix)}");`
+    + `if(t==="dark"||t==="light")document.documentElement.dataset.theme=t}catch(e){}`
+}

package/src/tokens.css

@@ -0,0 +1,143 @@
+/* @baseworks/ui — design tokens.
+
+   One palette: **warm paper, ultramarine ink**. Light and dark are the same
+   design at two luminances, not two designs — every token below exists in both
+   and means the same thing in both.
+
+   There is no brand switcher: a second palette is a second design to keep
+   correct in every state. There is a light/dark toggle, because that one is not
+   taste — it is the room the screen is in. The theme follows the operating
+   system until the viewer says otherwise, and `data-theme="light|dark"` on
+   <html> is how they say it (see `ThemeToggle`).
+
+   Why these colours:
+
+   - The neutrals are warm (a paper hue at very low saturation), not grey. A
+     console that is mostly tables and text is read for hours; a warm ground is
+     easier to sit in front of, and it is what distinguishes this from the
+     cool-grey default every admin panel ships with.
+
+   - The accent is ultramarine, at 231°. That is deliberate and functional: the
+     interface is full of status — ok, warn, crit — and those own green, amber
+     and red. An accent anywhere near them turns "this is a link" into "this is
+     a problem". Ultramarine is 76° from ok, 169° from warn and 132° from crit,
+     so an accented thing never reads as a state. The previous palette's
+     vermilion sat beside its own crit red, which is exactly the trap.
+
+   - Every pairing the interface actually makes was measured, not eyeballed:
+     body text ≥ 14:1, secondary text ≥ 5.7:1, an accent used as a link ≥ 7.4:1,
+     a button label on the accent ≥ 7.4:1, and each status pill against its own
+     tinted background ≥ 4.7:1. The faint tier (timestamps, placeholders) is
+     ≥ 3:1 and is never the only place something is said.
+
+   The one serif is the page title. Nothing else is set in it — it marks the
+   top of a document and then gets out of the way. */
+
+:root{
+  /* Ground and surfaces. bg is the page, surface is a card, surface2 is a
+     recessed area inside one (a toolbar, a code block, a table header). */
+  --bg:#FBFAF8; --surface:#FFFFFF; --surface2:#F2F0EB;
+
+  /* Text, in three tiers. ink says it, muted explains it, faint timestamps it. */
+  --ink:#1A1916; --muted:#67635B; --faint:#98938A;
+
+  /* line separates, line-strong encloses (an input, a control you can click). */
+  --line:#E8E4DC; --line-strong:#D6D0C5;
+
+  /* The accent: one colour, for the one thing on a screen that acts.
+     accent-soft is the same colour at 7%, for a pill or a selected row.
+     accent-ink is what is legible on top of it. */
+  --accent:#2B44CE; --accent-soft:#2B44CE12; --accent-ink:#FFFFFF;
+
+  /* State. Never the accent, never each other — see the note above. */
+  --ok:#16794F;   --ok-soft:#16794F16;
+  --warn:#8A6112; --warn-soft:#8A611218;
+  --crit:#B3362F; --crit-soft:#B3362F16;
+
+  --chat-bg:#F5F3EF;
+  --shadow:0 8px 28px rgba(26,25,22,.10);
+
+  --sans:'Instrument Sans',system-ui,-apple-system,'Segoe UI',sans-serif;
+  --mono:'IBM Plex Mono',ui-monospace,'SF Mono',Menlo,monospace;
+  --display:'Instrument Serif',Georgia,'Times New Roman',serif;
+}
+
+/* Dark is the same palette rotated down: the paper becomes a warm charcoal and
+   the ultramarine comes up to meet it. Not black — a dense table on pure black
+   vibrates, and the borders that hold it together disappear. */
+@media (prefers-color-scheme: dark){
+  :root:not([data-theme="light"]){
+    --bg:#1A1815; --surface:#221F1B; --surface2:#2B2823;
+    --ink:#EDE9E1; --muted:#A5A096; --faint:#7B766D;
+    --line:#322E28; --line-strong:#453F37;
+    --accent:#A9B5FF; --accent-soft:#A9B5FF20; --accent-ink:#151538;
+    --ok:#4FC28C;   --ok-soft:#4FC28C22;
+    --warn:#DFB255; --warn-soft:#DFB25520;
+    --crit:#F0736B; --crit-soft:#F0736B1F;
+    --chat-bg:#1D1B18;
+    --shadow:0 8px 28px rgba(0,0,0,.5);
+  }
+}
+
+/* The same values again, so an explicit choice wins in both directions: a
+   forced dark on a light system, and a forced light on a dark one. */
+:root[data-theme="dark"]{
+  --bg:#1A1815; --surface:#221F1B; --surface2:#2B2823;
+  --ink:#EDE9E1; --muted:#A5A096; --faint:#7B766D;
+  --line:#322E28; --line-strong:#453F37;
+  --accent:#A9B5FF; --accent-soft:#A9B5FF20; --accent-ink:#151538;
+  --ok:#4FC28C;   --ok-soft:#4FC28C22;
+  --warn:#DFB255; --warn-soft:#DFB25520;
+  --crit:#F0736B; --crit-soft:#F0736B1F;
+  --chat-bg:#1D1B18;
+  --shadow:0 8px 28px rgba(0,0,0,.5);
+}
+
+/* shadcn/ui names for the same colours, so a component copied in from there
+   inherits this palette instead of bringing its own. These are raw colour
+   values, which is the form shadcn uses with Tailwind v4 (`bg-background`);
+   the older `hsl(var(--background))` form expects bare HSL triplets and will
+   not read these. */
+:root{
+  --background:var(--bg);            --foreground:var(--ink);
+  --card:var(--surface);             --card-foreground:var(--ink);
+  --popover:var(--surface);          --popover-foreground:var(--ink);
+  --primary:var(--accent);           --primary-foreground:var(--accent-ink);
+  --secondary:var(--surface2);       --secondary-foreground:var(--ink);
+  --muted-foreground:var(--muted);
+  --destructive:var(--crit);         --destructive-foreground:var(--accent-ink);
+  --border:var(--line);              --input:var(--line-strong);
+  --ring:var(--accent);              --radius:10px;
+}
+
+/* Reset and text primitives. */
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{
+  background:var(--bg); color:var(--ink);
+  font-family:var(--sans); font-size:14px; line-height:1.5;
+  -webkit-font-smoothing:antialiased;
+}
+button{font:inherit;color:inherit;background:none;border:none;cursor:pointer;padding:0}
+a{color:inherit;text-decoration:none}
+button:focus-visible,a:focus-visible,input:focus-visible{outline:2px solid var(--accent);outline-offset:2px;border-radius:4px}
+.mono{font-family:var(--mono);font-size:.92em}
+.num{font-variant-numeric:tabular-nums}
+
+/* Controls carry the surface, not the browser's white. A bare <select> in a
+   table cell is a real case — the wrapper classes in primitives.css size and
+   stretch these, but an unwrapped control must already look right, in both
+   themes. */
+input,select,textarea{font:inherit;color:var(--ink)}
+select,textarea,
+input:not([type=checkbox]):not([type=radio]):not([type=range]):not([type=file]){
+  background:var(--surface);border:1px solid var(--line-strong);border-radius:8px;padding:6px 10px;
+}
+select{padding-right:6px}
+input::placeholder,textarea::placeholder{color:var(--faint)}
+input:disabled,select:disabled,textarea:disabled{opacity:.6;cursor:not-allowed}
+
+/* Someone who asked for less motion gets none. */
+@media (prefers-reduced-motion: reduce){
+  *{animation:none!important;transition:none!important}
+}

package/src/use-resource.ts

@@ -0,0 +1,70 @@
+'use client'
+
+/**
+ * A small fetch helper: loading and error state, optional periodic refresh.
+ * A cache/mutation library is worth adding only when a screen needs more.
+ *
+ * `enabled` exists for a question that should not be asked yet — a count for a
+ * service this realm may not have, a list that needs an organization first.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export type Resource<T> = {
+  data: T | undefined
+  error: string | undefined
+  loading: boolean
+  reload: () => void
+}
+
+export type ResourceOptions = {
+  refreshMs?: number
+  /** Re-runs when this changes — an id the fetcher closes over, usually. */
+  key?: string
+  enabled?: boolean
+  /** Shown when the failure carries no message of its own. */
+  fallbackError?: string
+}
+
+export function useResource<T>(fetcher: () => Promise<T>, options: ResourceOptions = {}): Resource<T> {
+  const [data, setData] = useState<T>()
+  const [error, setError] = useState<string>()
+  const [loading, setLoading] = useState(true)
+  const [nonce, setNonce] = useState(0)
+  // Held in a ref so a caller may write the fetcher inline without the effect
+  // re-running on every render.
+  const fetcherRef = useRef(fetcher)
+  fetcherRef.current = fetcher
+  const enabled = options.enabled ?? true
+  const fallback = options.fallbackError ?? 'That did not answer'
+
+  const reload = useCallback(() => setNonce((n) => n + 1), [])
+
+  useEffect(() => {
+    if (!enabled) return
+    let cancelled = false
+
+    const run = async () => {
+      try {
+        const result = await fetcherRef.current()
+        if (cancelled) return
+        setData(result)
+        setError(undefined)
+      } catch (err) {
+        if (cancelled) return
+        setError(err instanceof Error && err.message ? err.message : fallback)
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }
+
+    run()
+    const timer = options.refreshMs ? setInterval(run, options.refreshMs) : undefined
+    return () => {
+      cancelled = true
+      if (timer) clearInterval(timer)
+    }
+  }, [nonce, options.refreshMs, options.key, enabled, fallback])
+
+  return { data, error, loading, reload }
+}