@djangocfg/ui-core 2.1.432 → 2.1.433

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.432",
+  "version": "2.1.433",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -106,7 +106,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.432",
+    "@djangocfg/i18n": "^2.1.433",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -180,8 +180,8 @@
     "@chenglou/pretext": "*"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.432",
-    "@djangocfg/typescript-config": "^2.1.432",
+    "@djangocfg/i18n": "^2.1.433",
+    "@djangocfg/typescript-config": "^2.1.433",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/styles/README.md

@@ -42,6 +42,16 @@ This makes opacity modifiers (`bg-card/40`, `border-foreground/20`) resolve thro
 
 > **Do NOT wrap tokens in `hsl(var(--X))`.** Tokens are already full colors, so `hsl(hsl(...))` is invalid and falls back to the default. Use `var(--X)` or `color-mix(in oklab, var(--X) N%, transparent)` for manual opacity.
 
+> **Do NOT set a token to a bare HSL triplet.** The utilities read the token
+> **raw** (`.bg-muted { background-color: var(--muted) }`), so `--muted: 0 0% 10%`
+> resolves to the *string* `"0 0% 10%"` — not a color — and the declaration is
+> silently dropped: **transparent fills + white-fallback borders.** Always write
+> the full color: `--muted: hsl(0 0% 10%)`. This bites most often when a component
+> overrides tokens **inline** (e.g. an old `ForceTheme` wrapper). If part of a page
+> has vanished backgrounds / white borders, that's this — see
+> [`../theme/TROUBLESHOOTING.md`](../theme/TROUBLESHOOTING.md) and prefer
+> `ThemeOverride` over inline token maps.
+
 ## Semantic tokens — never use raw color scales
 
 **Rule:** never write `bg-amber-500`, `text-green-700`, `border-gray-200`. Use semantic tokens — they adapt to both themes and to whatever preset is active.

package/src/theme/ForceTheme.tsx

@@ -18,88 +18,59 @@ interface ForceThemeProps {
   className?: string;
 }
 
-// Dark theme CSS variables
+/**
+ * Token contract (ui-core Tailwind v4): base tokens are **full CSS colors**,
+ * never bare HSL triplets. The utilities consume them raw — `.bg-muted {
+ * background-color: var(--muted) }` — so `--muted: 0 0% 10%` (a triplet) is an
+ * invalid color and the declaration is dropped (transparent fills, white
+ * borders). Every value here is therefore wrapped in `hsl(...)`. The separate
+ * `--color-*` block is intentionally gone: ui-core's `@theme inline` already
+ * maps `--color-X: var(--X)`, so re-declaring it here is redundant and was the
+ * only reason this component half-worked before. See ui-core styles README
+ * §"Token format".
+ */
 const darkThemeVars = {
-  // Base HSL values
-  '--background': '0 0% 4%',
-  '--foreground': '0 0% 98%',
-  '--card': '0 0% 8%',
-  '--card-foreground': '0 0% 98%',
-  '--popover': '0 0% 12%',
-  '--popover-foreground': '0 0% 98%',
-  '--primary': '217 91% 60%',
-  '--primary-foreground': '0 0% 100%',
-  '--secondary': '0 0% 98%',
-  '--secondary-foreground': '0 0% 9%',
-  '--muted': '0 0% 10%',
-  '--muted-foreground': '0 0% 60%',
-  '--accent': '0 0% 15%',
-  '--accent-foreground': '0 0% 98%',
-  '--destructive': '0 84% 60%',
-  '--destructive-foreground': '0 0% 98%',
-  '--border': '0 0% 15%',
-  '--input': '0 0% 15%',
-  '--ring': '217 91% 60%',
-  // Tailwind color tokens (used by bg-*, text-*, etc)
-  '--color-background': 'hsl(0 0% 4%)',
-  '--color-foreground': 'hsl(0 0% 98%)',
-  '--color-card': 'hsl(0 0% 8%)',
-  '--color-card-foreground': 'hsl(0 0% 98%)',
-  '--color-primary': 'hsl(217 91% 60%)',
-  '--color-primary-foreground': 'hsl(0 0% 100%)',
-  '--color-secondary': 'hsl(0 0% 98%)',
-  '--color-secondary-foreground': 'hsl(0 0% 9%)',
-  '--color-muted': 'hsl(0 0% 10%)',
-  '--color-muted-foreground': 'hsl(0 0% 60%)',
-  '--color-accent': 'hsl(0 0% 15%)',
-  '--color-accent-foreground': 'hsl(0 0% 98%)',
-  '--color-destructive': 'hsl(0 84% 60%)',
-  '--color-destructive-foreground': 'hsl(0 0% 98%)',
-  '--color-border': 'hsl(0 0% 15%)',
-  '--color-input': 'hsl(0 0% 15%)',
-  '--color-ring': 'hsl(217 91% 60%)',
+  '--background': 'hsl(0 0% 4%)',
+  '--foreground': 'hsl(0 0% 98%)',
+  '--card': 'hsl(0 0% 8%)',
+  '--card-foreground': 'hsl(0 0% 98%)',
+  '--popover': 'hsl(0 0% 12%)',
+  '--popover-foreground': 'hsl(0 0% 98%)',
+  '--primary': 'hsl(217 91% 60%)',
+  '--primary-foreground': 'hsl(0 0% 100%)',
+  '--secondary': 'hsl(0 0% 98%)',
+  '--secondary-foreground': 'hsl(0 0% 9%)',
+  '--muted': 'hsl(0 0% 10%)',
+  '--muted-foreground': 'hsl(0 0% 60%)',
+  '--accent': 'hsl(0 0% 15%)',
+  '--accent-foreground': 'hsl(0 0% 98%)',
+  '--destructive': 'hsl(0 84% 60%)',
+  '--destructive-foreground': 'hsl(0 0% 98%)',
+  '--border': 'hsl(0 0% 15%)',
+  '--input': 'hsl(0 0% 15%)',
+  '--ring': 'hsl(217 91% 60%)',
 } as React.CSSProperties;
 
-// Light theme CSS variables
 const lightThemeVars = {
-  // Base HSL values
-  '--background': '0 0% 96%',
-  '--foreground': '0 0% 9%',
-  '--card': '0 0% 100%',
-  '--card-foreground': '0 0% 9%',
-  '--popover': '0 0% 100%',
-  '--popover-foreground': '0 0% 9%',
-  '--primary': '217 91% 60%',
-  '--primary-foreground': '0 0% 100%',
-  '--secondary': '0 0% 9%',
-  '--secondary-foreground': '0 0% 98%',
-  '--muted': '0 0% 96%',
-  '--muted-foreground': '0 0% 40%',
-  '--accent': '0 0% 92%',
-  '--accent-foreground': '0 0% 9%',
-  '--destructive': '0 84% 60%',
-  '--destructive-foreground': '0 0% 98%',
-  '--border': '0 0% 90%',
-  '--input': '0 0% 90%',
-  '--ring': '217 91% 60%',
-  // Tailwind color tokens (used by bg-*, text-*, etc)
-  '--color-background': 'hsl(0 0% 96%)',
-  '--color-foreground': 'hsl(0 0% 9%)',
-  '--color-card': 'hsl(0 0% 100%)',
-  '--color-card-foreground': 'hsl(0 0% 9%)',
-  '--color-primary': 'hsl(217 91% 60%)',
-  '--color-primary-foreground': 'hsl(0 0% 100%)',
-  '--color-secondary': 'hsl(0 0% 9%)',
-  '--color-secondary-foreground': 'hsl(0 0% 98%)',
-  '--color-muted': 'hsl(0 0% 96%)',
-  '--color-muted-foreground': 'hsl(0 0% 40%)',
-  '--color-accent': 'hsl(0 0% 92%)',
-  '--color-accent-foreground': 'hsl(0 0% 9%)',
-  '--color-destructive': 'hsl(0 84% 60%)',
-  '--color-destructive-foreground': 'hsl(0 0% 98%)',
-  '--color-border': 'hsl(0 0% 90%)',
-  '--color-input': 'hsl(0 0% 90%)',
-  '--color-ring': 'hsl(217 91% 60%)',
+  '--background': 'hsl(0 0% 96%)',
+  '--foreground': 'hsl(0 0% 9%)',
+  '--card': 'hsl(0 0% 100%)',
+  '--card-foreground': 'hsl(0 0% 9%)',
+  '--popover': 'hsl(0 0% 100%)',
+  '--popover-foreground': 'hsl(0 0% 9%)',
+  '--primary': 'hsl(217 91% 60%)',
+  '--primary-foreground': 'hsl(0 0% 100%)',
+  '--secondary': 'hsl(0 0% 9%)',
+  '--secondary-foreground': 'hsl(0 0% 98%)',
+  '--muted': 'hsl(0 0% 96%)',
+  '--muted-foreground': 'hsl(0 0% 40%)',
+  '--accent': 'hsl(0 0% 92%)',
+  '--accent-foreground': 'hsl(0 0% 9%)',
+  '--destructive': 'hsl(0 84% 60%)',
+  '--destructive-foreground': 'hsl(0 0% 98%)',
+  '--border': 'hsl(0 0% 90%)',
+  '--input': 'hsl(0 0% 90%)',
+  '--ring': 'hsl(217 91% 60%)',
 } as React.CSSProperties;
 
 export function ForceTheme({ theme, children, className }: ForceThemeProps) {

package/src/theme/README.md

@@ -0,0 +1,85 @@
+# Theme — providers, switches, and forced themes
+
+The runtime side of the design system. `styles/` ships the **tokens** (CSS
+variables) and the Tailwind utilities that read them; `theme/` is the **React**
+layer that decides *which* token set is live (light / dark / a preset) and lets
+you switch or pin it.
+
+> Read [`../styles/README.md`](../styles/README.md) first for the **token
+> contract** — it is load-bearing for everything here. The one rule that bites:
+> **base tokens are full CSS colors (`hsl(...)`), never bare triplets.**
+
+## Exports
+
+| Export | What it does |
+|---|---|
+| `ThemeProvider` / `useThemeContext` | Wraps `next-themes`. Owns the `html.dark` class + the user's light/dark/system choice. Mount once at the app root (via `BaseApp` in `@djangocfg/layouts`, which mounts it for you). |
+| `ThemeToggle` | A light/dark toggle button. |
+| `ThemeSegmented` | A segmented light/dark/system control. |
+| `ThemeOverride` | **Pathname-aware forced theme.** Mutates the real `next-themes` value while the route matches a rule, restores the user's pick when it leaves. Globs (`*`, `**`) supported. This is the **correct** way to force a route's theme. |
+| `resolveForcedTheme` | Pure helper — first matching rule → forced theme (or `null`). Pair with `ForcedThemeProvider`. |
+| `ForcedThemeProvider` / `useForcedTheme` | Lets descendants read the currently-forced theme. |
+| `ForceTheme` | **Scoped, inline-var theme for a subtree.** A `<div class={theme}>` that re-declares the token vars inline. Use sparingly — see the trap below. |
+
+## Choosing: `ThemeOverride` vs `ForceTheme`
+
+They look similar; they are not interchangeable.
+
+| | `ThemeOverride` (preferred) | `ForceTheme` (last resort) |
+|---|---|---|
+| How | mutates the real `next-themes` value → toggles `html.dark` | wraps children in `<div class={theme} style={inline vars}>` |
+| Scope | the **whole app** while the route matches | just that **subtree** |
+| Tokens | the real preset/`theme.css` tokens cascade — **always valid** | re-declares a hardcoded token map inline |
+| Active preset | **respected** (macos/ios/django-cfg/…) | **ignored** — ships its own generic palette |
+| Risk | none | bare-triplet trap (below); also overrides your brand accent |
+
+**Default to `ThemeOverride`** for "this route is always dark" (the common case —
+a marketing landing, a docs section). It's how the cmdop site forces its homepage
+dark:
+
+```tsx
+// in the app shell (RootAppLayout)
+<BaseApp theme={{ defaultTheme: 'dark' }}>
+  <ThemeOverride pathname={pathnameWithoutLocale} rules={[{ path: '/', theme: 'dark' }]} />
+  {children}
+</BaseApp>
+```
+
+Reach for `ForceTheme` **only** when you need a single subtree in the opposite
+theme of the rest of the page (e.g. a dark preview card on a light page) and you
+cannot drive it through the router.
+
+## ⚠️ The `ForceTheme` bare-triplet trap
+
+`ForceTheme` re-declares tokens inline. Under the **Tailwind v4 token contract**,
+base tokens are **full colors** and the utilities read them raw:
+
+```css
+.bg-muted    { background-color: var(--muted); }
+.border-border { border-color: var(--border); }
+```
+
+So a token set to a **bare HSL triplet** is a broken color:
+
+```css
+--muted: 0 0% 10%;     /* ❌ var(--muted) → "0 0% 10%" → not a color → declaration dropped */
+--muted: hsl(0 0% 10%);/* ✅ valid color */
+```
+
+The failure is **silent and confusing**: inside the `ForceTheme` subtree
+`bg-muted` renders **transparent** and `border-border` renders the inherited
+fallback (≈ white), while `border-divider` (a token `ForceTheme` doesn't
+re-declare) still works — so it looks like "random borders are white and some
+fills vanished." It is NOT a Tailwind content-scan problem; the utilities exist,
+their *input* is invalid. Full write-up + how to diagnose:
+[`TROUBLESHOOTING.md`](TROUBLESHOOTING.md).
+
+`ForceTheme`'s token map is wrapped in `hsl(...)` as of this version, so the trap
+is closed for the values it ships. But the lesson stands for **any** inline token
+override you write: wrap in `hsl(...)`, or prefer `ThemeOverride` so the real
+(already-valid) preset tokens cascade and you never hand-maintain a palette.
+
+## Maintenance rule
+
+After changing a component or the token map here, update this README and bump the
+package patch version (consumers pin npm versions; this file is the changelog).

package/src/theme/TROUBLESHOOTING.md

@@ -0,0 +1,89 @@
+# Theme & token troubleshooting
+
+Symptom-first. Each entry: what you see → why → the fix.
+
+---
+
+## "Random white borders + transparent fills on part of the page"
+
+### What you see
+- Some surfaces render with **no background** (`bg-muted` / `bg-card` / a custom
+  `bg-bubble-*` come out transparent).
+- Some borders render **bright white / light grey** instead of the hairline token
+  — `border-border` looks white, but `border-divider` next to it looks correct.
+- It only happens in **one region** of the page (often a marketing landing or a
+  card), not the whole app. A sibling app/route with the same components is fine.
+
+### Why (the actual mechanism)
+A subtree is wrapped in **`<ForceTheme>`** (or any hand-written element that sets
+token CSS vars inline) where a token is declared as a **bare HSL triplet**:
+
+```css
+--muted: 0 0% 10%;     /* ❌ */
+--border: 0 0% 15%;    /* ❌ */
+```
+
+ui-core's utilities consume tokens **raw** (`@theme inline` maps
+`--color-muted: var(--muted)`, and `.bg-muted { background-color: var(--muted) }`).
+So `var(--muted)` resolves to the **string** `"0 0% 10%"`, which is not a valid
+color → the browser **drops the declaration**:
+
+- `background-color` drop → falls back to `transparent`.
+- `border-color` drop → falls back to the inherited `currentColor` (≈ the light
+  text color on a dark UI → "white border").
+
+`border-divider` keeps working because that subtree doesn't *re-declare*
+`--divider`, so it still inherits the valid preset value.
+
+**This is NOT a Tailwind content-scan / `@source` problem.** The `.bg-muted`
+rule exists in the built CSS; its *input variable* is the broken thing.
+
+### How to confirm (60 seconds in the browser console)
+```js
+// 1) is the utility rule transparent on a real element?
+getComputedStyle($0).backgroundColor          // rgba(0,0,0,0) on a bg-muted node = bug
+
+// 2) is there a ForceTheme div with bare-triplet vars above it?
+[...document.querySelectorAll('div[style*="--muted"]')]
+  .map(d => d.style.getPropertyValue('--muted'))   // "0 0% 10%" (no hsl) = the culprit
+
+// 3) sanity: a probe OUTSIDE the subtree works
+const p = document.createElement('div'); p.className='bg-muted';
+document.body.appendChild(p);
+getComputedStyle(p).backgroundColor               // rgb(57,57,60) → proves the utility is fine
+p.remove();
+```
+If (1) is transparent but (3) is a real color, the input var is broken, not the
+utility — look up the tree for an inline token override.
+
+### Fix (in order of preference)
+1. **Stop forcing the theme with `ForceTheme`.** If the goal was just "this route
+   is dark", drive it through the router with **`ThemeOverride`** in the app shell
+   (`rules={[{ path: '/', theme: 'dark' }]}`) and delete the wrapper. The real
+   preset tokens (already valid `hsl(...)`) cascade and the bug is gone. This is
+   the right fix 90% of the time.
+2. **If you genuinely need `ForceTheme`** (a subtree in the opposite theme), make
+   sure every inline token value is a **full color**: `--muted: hsl(0 0% 10%)`,
+   not `0 0% 10%`. ui-core's shipped `ForceTheme` already does this.
+3. **Never** "fix" it by adding plain `.bg-x { background: var(--x) }` overrides in
+   the app's `globals.css` — that masks the broken input and rots.
+
+---
+
+## "ALL utilities missing (only @theme vars load)" — a different bug
+
+If `bg-*` / `border-*` are missing **everywhere** (not just one subtree) while the
+`--token` variables are present, that IS a content-scan problem, not this one:
+Tailwind v4 didn't scan your app source. See
+[`../styles/README.md`](../styles/README.md) §"Why `@source` is required" — add
+`@source "../../app"` (path relative to the CSS file) or check the app dir isn't
+`.gitignore`d. Distinguish the two: **scan bug = global**, **token bug = one
+subtree under an inline override.**
+
+---
+
+## "`hsl(var(--x))` shows the default / no color"
+
+Tokens are already full colors. `hsl(hsl(0 0% 10%))` is invalid. Use
+`var(--x)` directly, or `color-mix(in oklab, var(--x) N%, transparent)` for
+opacity. See `styles/README.md` §"Token format".