@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/styles/word-reveal.css

@@ -0,0 +1,204 @@
+/* ==========================================================================
+   @digithings-ai/ui — WordReveal structural CSS (components/typography/WordReveal).
+   Import AFTER the token bridge, in the app's globals.css:
+     @import "tailwindcss";
+     @import "@digithings-ai/design/tokens.css";
+     @import "@digithings-ai/ui/styles/web-theme.css";
+     @import "@digithings-ai/ui/styles/word-reveal.css";
+     @source "<path-to>/packages/ui/src/components/typography";
+   The @source line is load-bearing (path relative to the app's globals.css):
+   the component carries token-backed kicker/title utilities, and Tailwind does
+   not scan package sources on its own.
+
+   Utilities in <WordReveal/> carry the kicker/title type + the scroll→opacity/
+   blur mapping (inline MotionValues). This file holds only what must stay CSS:
+   the taller-than-viewport pinned track, the sticky pin, the display-line type,
+   and the reduced-motion + no-JS static fallbacks — the reveal must never gate
+   the claim; it reads fully with no JS.
+
+   Reference note: the muted/outline sibling variants (reference-only) reuse the
+   .wr-track / .wr-sticky / .word-line shell defined here and add their own
+   per-word color treatments in reference/app/typography/typography.css.
+   ========================================================================== */
+
+/* ── pinned track ──────────────────────────────────────────────────────────
+   .wr-track is taller than the viewport and .wr-sticky pins the line at
+   mid-viewport. The reveal itself rides the line's ENTRY (scroll offset
+   ["start end","start start"] in WordReveal.tsx): words fill as the line
+   rises and finish by the time the pin engages, so the pinned remainder
+   (height − 100vh) is only a short hold before the page flows on — the text
+   can never leave the viewport half-revealed. Keep the track short: the tail
+   after the pin is dead scroll. */
+.wr-track {
+  /* component tokens — pinned track + display line */
+  --wr-track-h: 150vh;
+  --wr-static-pad: 2.5rem;
+  --wr-line-font: clamp(1.55rem, 4.2vw, 2.6rem);
+  --wr-measure: 24ch;
+  --wr-word-gap: 0.35em;
+  --tw-caret-w: 0.55em;
+  --tw-caret-h: 1.05em;
+  --tw-caret-lead: 0.08em;
+  --tw-caret-trail: -0.63em;
+
+  position: relative;
+  height: var(--wr-track-h);
+}
+
+.wr-sticky {
+  position: sticky;
+  top: 0;
+  min-height: 100vh;
+  min-height: 100svh;
+  display: flex;
+  align-items: center;
+}
+
+/* static branch (the useReducedMotion hook adds .is-static) */
+.wr-track.is-static {
+  height: auto;
+}
+
+.wr-track.is-static .wr-sticky {
+  position: static;
+  min-height: 0;
+  padding: var(--wr-static-pad, 2.5rem) 0;
+}
+
+/* ── display line ──────────────────────────────────────────────────────────── */
+.word-line {
+  margin: 0;
+  font-family: var(--font-display);
+  font-size: var(--wr-line-font, clamp(1.55rem, 4.2vw, 2.6rem));
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  max-width: var(--wr-measure, 24ch);
+}
+
+.word {
+  display: inline-block;
+  margin-inline-end: var(--wr-word-gap, 0.35em);
+  will-change: transform, opacity, filter;
+}
+
+/* ── reduced motion: final state, no pinned scroll gap ──────────────────────
+   The hook renders the static branch; this covers pre-hydration paint and
+   forces the finished state regardless of the inline MotionValues. */
+@media (prefers-reduced-motion: reduce) {
+  .wr-track {
+    height: auto;
+  }
+
+  .wr-sticky {
+    position: static;
+    min-height: 0;
+    padding: var(--wr-static-pad, 2.5rem) 0;
+  }
+
+  .word {
+    opacity: 1 !important;
+    transform: none !important;
+    filter: none !important;
+    transition: none !important;
+  }
+}
+
+/* ── no JS: content-first (law 06) ──────────────────────────────────────────
+   With scripts off the reveal never runs AND the reduced-motion query may not
+   fire, so SSR's baked-in low opacity/blur would hide the claim. html.no-js
+   (set on <html>, stripped pre-paint when JS runs) neutralizes it: final text,
+   no 240vh empty scroll gap. Mirrors the hero's html.no-js fallback rules. */
+html.no-js .wr-track {
+  height: auto;
+}
+
+html.no-js .wr-sticky {
+  position: static;
+  min-height: 0;
+  padding: var(--wr-static-pad, 2.5rem) 0;
+}
+
+html.no-js .word {
+  opacity: 1 !important;
+  transform: none !important;
+  filter: none !important;
+}
+
+/* ── TypewriterReveal ───────────────────────────────────────────────────────
+   The unpinned third sibling: characters appear in order with a caret as the
+   line travels. No track and no pin, so it adds no height to the band.
+
+   The ghost is the whole point. Revealing characters one at a time reflows the
+   paragraph on every tick, so the full text is laid out once in a `visibility:
+   hidden` copy and the typed copy is drawn on top of it — the box is the size of
+   the finished quote from the first frame, and nothing below it moves.
+   `visibility: hidden` rather than `display: none` or `opacity: 0`, because only
+   `visibility` keeps the text's layout contribution while taking it out of the
+   accessibility tree's way (the component also marks it aria-hidden, and the
+   visible layers with it, exposing the full line once in `.tw-sr`). */
+.tw {
+  position: relative;
+  display: block;
+}
+
+.tw-ghost {
+  visibility: hidden;
+}
+
+/* Overlaid on the ghost, so the two wrap at exactly the same width. */
+.tw-live {
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline: 0;
+}
+
+/* The caret rides at the type edge. Net-zero width, like the chat caret, so
+   appearing and retiring never rewraps the line it is attached to. */
+.tw-caret {
+  display: inline-block;
+  width: var(--tw-caret-w, 0.55em);
+  height: var(--tw-caret-h, 1.05em);
+  margin-inline-start: var(--tw-caret-lead, 0.08em);
+  margin-inline-end: var(--tw-caret-trail, -0.63em);
+  vertical-align: text-bottom;
+  background: var(--accent);
+  animation: tw-caret-blink 1.06s steps(1) infinite;
+}
+
+@keyframes tw-caret-blink {
+  0%,
+  49% {
+    opacity: 1;
+  }
+  50%,
+  100% {
+    opacity: 0;
+  }
+}
+
+/* The one readable copy. The visual layers are aria-hidden, so assistive tech
+   gets the finished quote exactly once rather than a partial, still-typing one. */
+.tw-sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Reduced motion never types (the component renders the whole line), so the
+   caret has nothing to point at — and a blinking cursor under a motion
+   preference is exactly the thing the preference is asking not to see. Both
+   declarations: `display: none` takes it out of the line, and `animation: none`
+   is what the reduced-motion contract test requires of any infinite animation
+   in this sheet, whether or not the element is painted. */
+@media (prefers-reduced-motion: reduce) {
+  .tw-caret {
+    display: none;
+    animation: none;
+  }
+}

package/src/theme/apply-theme.ts

@@ -0,0 +1,214 @@
+/**
+ * Platform theme: mode (`dt-theme`) and palette (`dt-palette`).
+ *
+ * `dt-theme` stores only `light` or `dark`. Auto removes the key so the OS
+ * preference applies and live-updates. The dashboard writes the same key with
+ * the resolved light/dark value and never touches `dt-palette`.
+ */
+import { PALETTE_IDS, PALETTES, type PaletteId } from "./palette-registry";
+
+export const THEME_STORAGE_KEY = "dt-theme";
+/** Fired on the document's window after every applyDocumentTheme, so a provider can re-read it. */
+export const THEME_CHANGE_EVENT = "dt-theme-change";
+export const PALETTE_STORAGE_KEY = "dt-palette";
+
+export type ThemePreference = "light" | "dark" | "auto";
+export type ResolvedTheme = "light" | "dark";
+export type PaletteName = PaletteId | "default";
+
+/** Default canvas, matching tokens.css `--bg`. Read by `<meta name="theme-color">`. */
+export const DEFAULT_THEME_COLOR: Record<ResolvedTheme, string> = {
+  light: "#FBFBF9", // canon-allow: default --bg for the browser theme-color meta
+  dark: "#0A0E0C", // canon-allow: default --bg for the browser theme-color meta
+};
+
+export function isPaletteId(value: string): value is PaletteId {
+  return (PALETTE_IDS as readonly string[]).includes(value);
+}
+
+export function isThemePreference(value: string): value is ThemePreference {
+  return value === "light" || value === "dark" || value === "auto";
+}
+
+export function normalizePalette(value: string | null | undefined): PaletteName {
+  if (!value) return "default";
+  const id = value.trim().toLowerCase();
+  if (id === "default") return "default";
+  return isPaletteId(id) ? id : "default";
+}
+
+type GetItem = { getItem(key: string): string | null };
+
+function safeStorage(): GetItem | null {
+  try {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function readPreference(storage: GetItem | null): ThemePreference {
+  if (!storage) return "auto";
+  try {
+    const raw = storage.getItem(THEME_STORAGE_KEY);
+    if (raw === "light" || raw === "dark") return raw;
+  } catch {
+    /* private mode */
+  }
+  return "auto";
+}
+
+export function readPalette(storage: GetItem | null): PaletteName {
+  if (!storage) return "default";
+  try {
+    return normalizePalette(storage.getItem(PALETTE_STORAGE_KEY));
+  } catch {
+    return "default";
+  }
+}
+
+export function resolveTheme(preference: ThemePreference, prefersLight: boolean): ResolvedTheme {
+  if (preference === "light" || preference === "dark") return preference;
+  return prefersLight ? "light" : "dark";
+}
+
+export function themeColorFor(palette: string, resolved: ResolvedTheme): string {
+  const id = normalizePalette(palette);
+  if (id === "default") return DEFAULT_THEME_COLOR[resolved];
+  return PALETTES[id][resolved].bg;
+}
+
+export type ThemeState = {
+  preference: ThemePreference;
+  palette: PaletteName;
+  resolved: ResolvedTheme;
+};
+
+function prefersLightNow(): boolean {
+  if (typeof matchMedia !== "function") return false;
+  try {
+    return matchMedia("(prefers-color-scheme: light)").matches;
+  } catch {
+    return false;
+  }
+}
+
+/** What the document is painting right now (the pre-paint script or a pin set it). */
+export function readPaintedTheme(
+  doc: Document | null = typeof document === "undefined" ? null : document,
+): { resolved: ResolvedTheme; palette: PaletteName } {
+  const root = doc?.documentElement;
+  return {
+    resolved: root?.getAttribute("data-theme") === "light" ? "light" : "dark",
+    palette: normalizePalette(root?.getAttribute("data-palette")),
+  };
+}
+
+export function readThemeState(storage?: GetItem | null, prefersLight?: boolean): ThemeState {
+  const store = storage === undefined ? safeStorage() : storage;
+  const preference = readPreference(store);
+  const palette = readPalette(store);
+  const resolved = resolveTheme(preference, prefersLight ?? prefersLightNow());
+  return { preference, palette, resolved };
+}
+
+function writeKey(storage: Storage, key: string, value: string | null): void {
+  try {
+    if (value === null) storage.removeItem(key);
+    else storage.setItem(key, value);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Paint `data-theme` / `data-palette` and, for a user's choice, persist it.
+ * Auto clears `dt-theme`; the default palette clears `dt-palette`. Pass
+ * `{ persist: false }` to repaint without writing (an OS light/dark change).
+ */
+export function applyDocumentTheme(
+  preference: ThemePreference,
+  palette: string,
+  doc: Document | null = typeof document === "undefined" ? null : document,
+  options: { persist?: boolean } = {},
+): ResolvedTheme {
+  const pal = normalizePalette(palette);
+  const resolved = resolveTheme(preference, prefersLightNow());
+  if (doc) {
+    const root = doc.documentElement;
+    root.setAttribute("data-theme", resolved);
+    if (pal === "default") root.removeAttribute("data-palette");
+    else root.setAttribute("data-palette", pal);
+    try {
+      let meta = doc.querySelector('meta[name="theme-color"]');
+      if (!meta) {
+        meta = doc.createElement("meta");
+        meta.setAttribute("name", "theme-color");
+        doc.head.appendChild(meta);
+      }
+      meta.setAttribute("content", themeColorFor(pal, resolved));
+    } catch {
+      /* ignore */
+    }
+  }
+  const store = options.persist === false ? null : safeStorage();
+  if (store && "setItem" in store) {
+    const writable = store as Storage;
+    writeKey(writable, THEME_STORAGE_KEY, preference === "auto" ? null : preference);
+    writeKey(writable, PALETTE_STORAGE_KEY, pal === "default" ? null : pal);
+  }
+  if (doc) {
+    try {
+      doc.defaultView?.dispatchEvent(new Event(THEME_CHANGE_EVENT));
+    } catch {
+      /* ignore */
+    }
+  }
+  return resolved;
+}
+
+/** One stop on the shared cycle: default dark, default light, then each palette in dark and light. */
+export type ThemeStep = {
+  id: string;
+  label: string;
+  mode: "dark" | "light";
+  palette: PaletteName;
+};
+
+export function themeCycle(): readonly ThemeStep[] {
+  const steps: ThemeStep[] = [
+    { id: "default:dark", label: "default · dark", mode: "dark", palette: "default" },
+    { id: "default:light", label: "default · light", mode: "light", palette: "default" },
+  ];
+  for (const id of PALETTE_IDS) {
+    steps.push({ id: `${id}:dark`, label: `${id} · dark`, mode: "dark", palette: id });
+    steps.push({ id: `${id}:light`, label: `${id} · light`, mode: "light", palette: id });
+  }
+  return steps;
+}
+
+/** The cycle stop that matches the painted mode and palette. Auto uses the resolved mode. */
+export function matchThemeStep(
+  preference: ThemePreference,
+  palette: PaletteName,
+  resolved: ResolvedTheme,
+): ThemeStep {
+  const mode = preference === "auto" ? resolved : preference;
+  const steps = themeCycle();
+  return steps.find((step) => step.mode === mode && step.palette === palette) ?? steps[0];
+}
+
+/** The next stop after the painted one. Wraps to default dark. */
+export function nextThemeStep(
+  preference: ThemePreference,
+  palette: PaletteName,
+  resolved: ResolvedTheme,
+): ThemeStep {
+  const steps = themeCycle();
+  const current = matchThemeStep(preference, palette, resolved);
+  const index = steps.findIndex((step) => step.id === current.id);
+  return steps[(index + 1) % steps.length];
+}
+
+export { PALETTE_IDS, PALETTES, type PaletteId };

package/src/theme/index.ts

@@ -0,0 +1,27 @@
+export {
+  applyDocumentTheme,
+  DEFAULT_THEME_COLOR,
+  isPaletteId,
+  isThemePreference,
+  matchThemeStep,
+  nextThemeStep,
+  normalizePalette,
+  PALETTE_IDS,
+  PALETTES,
+  PALETTE_STORAGE_KEY,
+  readPaintedTheme,
+  readPalette,
+  readPreference,
+  readThemeState,
+  resolveTheme,
+  THEME_CHANGE_EVENT,
+  THEME_STORAGE_KEY,
+  themeColorFor,
+  themeCycle,
+  type PaletteId,
+  type PaletteName,
+  type ResolvedTheme,
+  type ThemePreference,
+  type ThemeState,
+  type ThemeStep,
+} from "./apply-theme";