first commit

docs/ui/react/react-ui/src/theme/theme-context.md

@@ -0,0 +1,93 @@
+# `theme-context` — React context plumbing for the active theme
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+  - [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_  - [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
+- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
+- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
+- [use-resolved-theme-tokens](./use-resolved-theme-tokens/use-resolved-theme-tokens.md) — `useResolvedThemeTokens()` is the read-side counterpart to `useThemeMutator()`. It returns the live merged token state…
+  - [use-resolved-theme-tokens](./use-resolved-theme-tokens/use-resolved-theme-tokens.md) — `useResolvedThemeTokens()` is the read-side counterpart to `useThemeMutator()`. It returns the live merged token state…
+- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-mutator](./use-theme-mutator/use-theme-mutator.md) — `useThemeMutator()` is the public surface a consumer reaches for when it wants to push CSS custom properties onto the a…
+  - [use-theme-mutator](./use-theme-mutator/use-theme-mutator.md) — `useThemeMutator()` is the public surface a consumer reaches for when it wants to push CSS custom properties onto the a…
+- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- theme-provider — <!-- begin:auto-docs --> _(no submo…
+- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
+- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
+- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
+- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
+- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
+- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
+- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- theme-provider — <!-- begin:…
+- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
+- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
+- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
+- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_- theme-provider — <!-- begin:auto-docs --> _(no subm…
+- [theme-provider](./theme-provider/theme-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_  - [theme-switcher](./theme-switcher/theme-switcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [dark](./themes/dark.md) — The dark counterpart of `lightTheme`. Same variant surface, same token names, lightness anchors inverted so foreground…
+- [high-contrast](./themes/high-contrast.md) — Accessibility-first theme that meets WCAG AAA contrast for normal and large text alike. Pure-white foreground (`#FFFFFF…
+- [light](./themes/light.md) — The default `ThemePlugin` instance shipped with `@suaveplan/react-ui`. `lightTheme` matches the shadcn `nova` token pre…
+- [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme](./use-theme/use-theme.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-theme-tokens](./use-theme-tokens/use-theme-tokens.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-themed-variants](./use-themed-variants/use-themed-variants.md) — <!-- begin:auto-docs --> _(no submodules)_- [theme-context](./theme-context.md) — <!-- begin:auto-docs --> _(no submodules)_
+## Purpose
+
+Owns the React `Context` `<ThemeProvider>` writes into and every theme
+hook (`useTheme`, `useThemeTokens`, `useThemedVariants`,
+`<ThemeSwitcher>`) reads from. The context is intentionally typed as
+`ThemeContextValue | null` — `null` carries "no Provider mounted" so
+hooks can throw a structured `ReactUiError(REACT_UI.NO_PROVIDER)` in
+dev mode rather than silently rendering a broken UI.
+
+## Features
+
+- Single source-of-truth context for the chassis theme system
+- `null` discriminator drives provider-missing detection in every
+  consumer hook
+- `displayName` set so React DevTools shows `ReactUiThemeContext`
+  rather than the unhelpful `Context.Provider` default
+- Exposes `reducedMotionActive` so motion-aware components can read
+  the resolved `prefers-reduced-motion` policy without re-querying
+  `matchMedia` themselves
+
+## Usage: Basic example
+
+```ts
+import { useContext } from "react";
+import { ThemeContext } from "@suaveplan/react-ui/theme/theme-context";
+
+function CustomThemeAware() {
+    const ctx = useContext(ThemeContext);
+    if (!ctx) return null;
+    return <div data-theme={ctx.theme.name}>…</div>;
+}
+```
+
+## Usage: Advanced example
+
+```ts
+import { useContext } from "react";
+import { ThemeContext, type ThemeContextValue } from "@suaveplan/react-ui/theme/theme-context";
+
+function useThemeOrThrow(): ThemeContextValue {
+    const ctx = useContext(ThemeContext);
+    if (ctx === null) {
+        throw new Error("useThemeOrThrow requires <ThemeProvider>");
+    }
+    return ctx;
+}
+```
+
+## API Reference
+
+- `ThemeContext: React.Context<ThemeContextValue | null>` — initial
+  value `null` so unwrapped reads can be detected
+- `interface ThemeContextValue` — `{ theme, themes, setTheme, isPending,
+  reducedMotionActive }`
+
+## Implementation notes
+
+The `setTheme` callback is typed as `(name: string) => Promise<void>`
+so the Provider can wrap the underlying state update in
+`useTransition()` and consumers that `await setTheme('dark')` get the
+DOM in its post-commit state. The `reducedMotionActive` field is
+recomputed inside the Provider on `prefers-reduced-motion` media query
+changes; consumers that need finer control over the motion policy
+should read `theme.motionTokens.respectReducedMotion` directly via
+`useTheme()`.