@djangocfg/ui-core 2.1.530 → 2.1.532

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.530",
+  "version": "2.1.532",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -128,7 +128,7 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.530",
+    "@djangocfg/i18n": "^2.1.532",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -206,8 +206,8 @@
     "@chenglou/pretext": "^0.0.8"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.530",
-    "@djangocfg/typescript-config": "^2.1.530",
+    "@djangocfg/i18n": "^2.1.532",
+    "@djangocfg/typescript-config": "^2.1.532",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/components/overlay/dialog/index.tsx

@@ -80,7 +80,11 @@ const DialogContent = React.forwardRef<
           ? "left-0 top-0 grid grid-rows-[minmax(0,1fr)] h-[100dvh] w-screen max-w-none gap-0 border-0 p-0 shadow-none data-[state=closed]:zoom-out-[0.98] data-[state=open]:zoom-in-[0.98]"
           // Rounded on ALL sizes — the radius used to be `sm:`-gated, which left
           // phone dialogs with hard square corners. Centered, soft-cornered card.
-          : "left-1/2 top-1/2 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 rounded-[var(--radius-dialog)] border p-6 shadow-lg data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+          // Width by MEASUREMENT, not breakpoint: `min()` keeps the card off
+          // both edges at any viewport. A `sm:` gate reads the window, so a
+          // narrow desktop pane lost its margins and rendered as a sheet with
+          // its rounding cropped.
+          : "left-1/2 top-1/2 grid w-[min(32rem,calc(100vw-2rem))] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-[var(--radius-dialog)] border p-6 shadow-lg data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
         className
       )}
       {...props}
@@ -105,7 +109,9 @@ const DialogHeader = ({
 }: React.HTMLAttributes<HTMLDivElement>) => (
   <div
     className={cn(
-      "flex flex-col space-y-1.5 text-center sm:text-left",
+      // Start-aligned at every width: the `sm:` gate centred the title in a
+      // narrow pane only, so one dialog read as two different components.
+      "flex flex-col space-y-1.5 text-start",
       className
     )}
     {...props}
@@ -119,7 +125,10 @@ const DialogFooter = ({
 }: React.HTMLAttributes<HTMLDivElement>) => (
   <div
     className={cn(
-      "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
+      // One row, buttons sized to their labels. The `sm:`-gated stack read the
+      // window, so a narrow pane got two full-bleed buttons — Cancel as loud as
+      // Confirm. `flex-wrap` handles a long label by measurement instead.
+      "flex flex-wrap items-center justify-end gap-2",
       className
     )}
     {...props}

package/src/styles/README.md

@@ -1,217 +1,156 @@
 # ui-core styles
 
-`@djangocfg/ui-core` owns the semantic CSS token contract used by every
-frontend. CSS is the single source of truth for colors, typography, radius,
-status surfaces, charts, and sidebar tokens.
+CSS is the single source of truth for colors, typography, radius, status
+surfaces, charts, and sidebar tokens. There are no TypeScript color maps and no
+runtime token generator — do not add either.
 
 ## Layout
 
 ```text
 styles/
-├── css/                     # complete CSS layer
-│   ├── full.css             # Tailwind v4 + tokens + base + utilities
-│   ├── index.css            # unlayered compatibility entry
-│   ├── globals.css          # backwards-compatible global entry
-│   ├── base.css             # resets and document defaults
-│   ├── sources.css          # Tailwind @source directives
-│   ├── theme.css            # token/animation aggregator
-│   ├── theme/               # tokens, light, dark, animations
-│   ├── utilities.css        # ui-core utility aggregator
-│   ├── utilities/            # focused utility modules
-│   └── presets/              # authoritative static preset token sheets
-│       ├── default.css
-│       ├── django-cfg.css
-│       ├── ios.css
-│       ├── macos.css
-│       ├── windows.css
-│       ├── soft.css
-│       ├── dense.css
-│       └── high-contrast.css
-├── palette/                 # runtime readers of computed CSS variables
-└── presets/                  # TypeScript names/order only
-    ├── index.ts
-    ├── presets.ts
-    └── types.ts
+├── css/
+│   ├── full.css        # THE entry: Tailwind + tokens + base + utilities
+│   ├── base.css        # resets
+│   ├── sources.css     # Tailwind @source directives
+│   ├── theme/          # tokens.css (the @theme map), light.css, dark.css
+│   ├── utilities/      # focused utility modules
+│   └── presets/        # the authoritative token values, one file per preset
+├── palette/            # runtime readers of computed CSS variables
+└── presets/            # TypeScript names and ordering only — never values
 ```
 
-There are deliberately no TypeScript color maps and no runtime CSS generator.
-Do not add a second palette in React or TypeScript.
+`index.css` and `globals.css` are compatibility entries. New consumers import
+`full.css`.
 
-`styles/presets/` contains only the TypeScript preset names and ordering used by
-the public API. The actual values always live in `styles/css/presets/*.css`.
-
-## Consumer contract
-
-Import the golden path first, then exactly one product preset:
+## Consumer setup
 
 ```css
 @import "@djangocfg/ui-core/styles/full";
+@plugin "tailwindcss-animate";
 @import "@djangocfg/ui-core/styles/presets/macos";
+@import "@djangocfg/ui-tools/styles";
 ```
 
-The preset export resolves to `src/styles/css/presets/macos.css`; consumers do
-not depend on the physical path. The preset defines both `:root` (light) and
-`.dark` (dark) values. `ThemeProvider` only controls the `html.dark` class.
-
-For a product-specific adjustment, add a small override after the preset:
+Order is load-bearing: the preset must come after `full.css` so its `:root` and
+`.dark` values win. Application overrides come last.
 
-```css
-:root,
-.dark {
-  --font-size-base: 0.9375rem;
-  --font-size-sm: 0.875rem;
-}
-```
-
-Do not create a `theme-preset.ts`, append a `<style>` tag, or call a token
-builder during application startup.
+`full.css` already imports Tailwind, tokens, base and utilities — a second
+`@import "tailwindcss"` or `base.css` in the consumer is a duplicate. The
+`tailwindcss-animate` plugin is registered by the consumer, not the package.
 
-### Import order
+A preset defines both `:root` (light) and `.dark`. `ThemeProvider` only toggles
+the `html.dark` class.
 
-Keep the application entrypoint minimal and deterministic:
+For a product adjustment, override after the preset:
 
 ```css
-@import "@djangocfg/ui-core/styles/full";
-@plugin "tailwindcss-animate";
-@import "@djangocfg/ui-core/styles/presets/macos";
-@import "@djangocfg/layouts/styles";
-@import "@djangocfg/ui-tools/styles";
+:root, .dark { --font-size-base: 0.9375rem; }
 ```
 
-`full.css` already imports Tailwind, the theme tokens, base styles, and
-ui-core utilities. Do not add a second `@import "tailwindcss"`, `base.css`,
-or `utilities.css` in the consumer. Load the preset after `full.css`, so its
-`:root` and `.dark` variables win over defaults. Keep application overrides
-after the preset.
-
-The `tailwindcss-animate` plugin is registered once by the consumer. It
-provides classes such as `animate-in`, `fade-in-0`, and `zoom-in-95`; the
-package's component source uses those classes but does not register the
-plugin itself.
+Do not build tokens at startup, append a `<style>` tag, or copy values into a
+`theme-preset.ts`.
 
 ### Tailwind source scanning
 
-`css/sources.css` is part of the `full` entry and must scan the package source
-root from its own location:
+`css/sources.css` must scan the package root from its own location:
 
 ```css
 @source "../../**/*.{ts,tsx}";
 ```
 
-This is important. Scanning only `../` scans `src/styles` and silently drops
-utilities used by components, including `bg-overlay` and state/animation
-utilities. A consumer may add extra `@source` directives for local packages,
-but should not replace the ui-core source directive.
+Scanning `../` instead reaches only `src/styles` and silently drops every
+utility used by components, `bg-overlay` among them. Consumers may add their own
+`@source` lines but must not replace this one.
 
-### Overlays and glass surfaces
+## Token format
 
-Dialog, alert-dialog, sheet, and drawer backdrops use the semantic
-`bg-overlay` class. The class gets its color from `--overlay` and its frosting
-from `--overlay-blur` (the default is `5px`):
+Color variables are complete CSS colors, never bare HSL triplets. Use
+`var(--background)` or `bg-background`; never `hsl(var(--background))`.
 
 ```css
-.bg-overlay {
-  background: var(--overlay);
-  backdrop-filter: blur(var(--overlay-blur));
-}
+:root { --background: hsl(240 17% 97%); }
+.dark { --background: hsl(240 5% 8%); }
 ```
 
-Glass surfaces must have a translucent background; an opaque `bg-card` or
-`bg-popover` makes the blur invisible. A dropdown rendered inside an ancestor
-that already has `backdrop-filter` is also unable to blur the page behind that
-ancestor because it becomes a backdrop root. PublicLayout desktop dropdowns
-are therefore rendered through a body portal and positioned from the trigger.
-Use the same pattern for new floating surfaces that must blur content outside
-their parent stacking context.
+Typography variables are ordinary CSS values (`--font-size-base: 0.8125rem`).
 
-For custom glass utilities, prefer a Tailwind utility such as
-`backdrop-blur-[5px]` when the consuming build must emit the standard
-`backdrop-filter` declaration. Keep the visual token (`--overlay-blur`) in
-CSS rather than duplicating a pixel value in React.
+### Raised and recessed surfaces
 
-## Token format
+| Token | Reads as | Use for |
+|---|---|---|
+| `--surface-hover` | a step toward the reader | pointer feedback on a resting surface |
+| `--surface-recessed` | sunk below the page | chrome framing content: a tab strip, a rail, a footer band |
 
-Color variables are complete CSS colors, never bare HSL triplets:
+`--surface-recessed` is a translucent black, not a mix with `--background`. A
+percentage mix takes its step from what is already there, and a dark page has
+almost nothing to take: 6% black into `hsl(240 5% 8%)` moved it two bytes out of
+255, which no eye resolves. A fixed overlay steps by the same amount whatever
+the page — and the alpha differs per theme, because the same overlay costs far
+more contrast on a near-white ground.
 
-```css
-:root {
-  --background: hsl(240 17% 97%);
-}
-.dark {
-  --background: hsl(240 5% 8%);
-}
-```
+**Never recess with `--muted` or `--card`.** Their direction is not guaranteed:
+`theme/dark.css` keeps `--muted` below `--background`, while the macOS preset
+raises every resting surface (background 8%, muted 11%, card 12%). A tab strip
+painted `bg-muted` floated toward the reader on that preset and looked correct
+in the base theme.
 
-Tailwind maps semantic utilities to these variables through `@theme inline`.
-Use `var(--background)` or `bg-background`; do not write
-`hsl(var(--background))`.
+### Overlays and glass
 
-Typography variables are ordinary CSS values:
+`bg-overlay` takes its color from `--overlay` and its frosting from
+`--overlay-blur` (default `5px`). A glass surface needs a translucent
+background — an opaque `bg-card` makes the blur invisible.
 
-```css
-:root,
-.dark {
-  --font-size-base: 0.8125rem;
-  --font-size-sm: 0.75rem;
-}
-```
+An element inside an ancestor that already has `backdrop-filter` cannot blur the
+page behind that ancestor: the ancestor becomes a backdrop root. Render such
+surfaces through a body portal, positioned from their trigger.
 
 ## Preset rules
 
-- Presets are authored directly in `styles/css/presets/`.
-- Every preset must define valid `hsl(...)`, `color-mix(...)`, or other complete
-  CSS color values.
-- Keep light and dark pairs together in the same file.
-- A preset may omit tokens that intentionally inherit from `theme.css`.
-- In light mode, `--muted` must be at least 2 HSL lightness points darker
-  than `--background`. This keeps translucent muted fills visible on the
-  canvas and is enforced by `check:contrast`.
-- An interactive surface must sit at least 4 HSL lightness points away from the
-  surface it lands on, **in both modes**: `--accent` vs `--background`, and
-  `--sidebar-accent` vs `--sidebar-background`. Direction is deliberately not
-  asserted (light darkens its hover, dark lightens it) — only the size of the
-  step, so both modes do comparable work for the same interaction. Enforced by
-  `check:contrast`.
-
-  This rule exists because the one above it was not enough. A sidebar hover
-  lands on `--sidebar-background`, which nothing checked, so presets shipped
-  one-point steps in light against eleven in dark — and one stepped the wrong
-  way, its hover lighter than the rail it highlighted. Every one passed the
-  `--muted`/`--background` gate. **Check the surface the user actually sees,
-  not a neighbouring one that happens to be nearby.**
-- Changes to a preset require checking both light and dark modes.
-- Product density overrides belong in the consuming app's CSS, not in a copied
-  TypeScript map.
+- Values live in `styles/css/presets/*.css`. `styles/presets/*.ts` holds names
+  and ordering only.
+- Every value must be a complete CSS color. Keep a preset's light and dark pairs
+  in one file. A preset may omit tokens that inherit from `theme.css`.
+- **Light mode:** `--muted` at least 2 lightness points darker than
+  `--background`, so translucent muted fills stay visible.
+- **Both modes:** an interactive surface sits at least 4 lightness points from
+  the surface it lands on — `--accent` vs `--background`, `--sidebar-accent` vs
+  `--sidebar-background`.
+
+  Direction is not asserted, only the step size. The second pair exists because
+  the first was not enough: a sidebar hover lands on `--sidebar-background`,
+  which nothing checked, so presets shipped one-point steps in light against
+  eleven in dark, and one hover came out lighter than the rail it highlighted —
+  all while passing the `--muted` gate. **Check the surface the user sees, not a
+  neighbour that happens to be nearby.**
+
+  Because direction is free, product code must not infer it from a token's
+  value. That is what `--surface-recessed` and `--surface-hover` are for.
+- Density overrides belong in the consuming app's CSS.
 
 ## Verification
 
 ```bash
-pnpm check:contrast
-pnpm check
+pnpm check:contrast   # preset gates + the macOS AA compact-text audit
+pnpm check            # tsc --noEmit
 ```
 
-`check:contrast` merges every static preset over the base theme and validates
-the light-mode background/muted surface hierarchy. It also keeps the complete
-macOS compact-text audit: semantic pairs must reach WCAG AA 4.5:1 in both
-modes, including primary, destructive, sidebar, status-surface, on-fill, and
-muted text against every common surface. When tuning a token, change the
-semantic pair together rather than overriding text in a consumer component.
+`check:contrast` merges each static preset over the base theme, enforces the
+rules above, and requires WCAG AA 4.5:1 for semantic pairs in both modes. When
+tuning a token, move the semantic pair together rather than overriding text in a
+consumer component.
 
-At the consumer, build the app that imports the preset and verify both modes.
-The important invariant is that changing a preset requires editing one CSS
-file, and no React runtime code is involved in applying it.
+Then build a consumer and look at both modes.
 
-For a local cross-repository change, use the consumer's sync command and
-restart its dev server afterward:
+## Cross-repository changes
 
 ```bash
 pnpm sync:cfg:one ui-core
-pnpm sync:cfg:one layouts
-pnpm sync:cfg:one i18n       # required peer when ui-core is synced locally
-rm -rf apps/web/.next
+pnpm sync:cfg:one i18n     # required peer when ui-core is synced locally
 ```
 
-Do not delete `pnpm-lock.yaml` to force a package update. Update the package
-range with pnpm, then let the lockfile record the resolved version. A clean
-install restores published packages and therefore requires publishing a new
-package version for source changes to survive.
+Restart the consumer's dev server afterward.
+
+A sync is local and temporary: a clean install restores the published package,
+so a source change survives only once a new version is published. Update the
+dependency range with pnpm and let the lockfile record the resolution — never
+delete `pnpm-lock.yaml` to force an update.

package/src/styles/css/theme/dark.css

@@ -37,6 +37,18 @@
   --muted-foreground: hsl(48 5% 59%);
   /* Neutral interaction surface: a quiet lift above the current dark page. */
   --surface-hover: color-mix(in oklab, var(--card) 96%, var(--foreground));
+  /* The counterpart to --surface-hover: a surface that reads as sunk BELOW the
+   * page — a tab strip under a document, a rail beside it. Every other surface
+   * token raises, so a chrome band painted with one of them floats toward the
+   * viewer instead of receding, and a preset whose --muted sits above
+   * --background has no recessed fill at all.
+   *
+   * A translucent BLACK, not a mix with --background. A percentage mix takes its
+   * step from what is already there, and a dark page has almost nothing to take:
+   * mixing 6% black into hsl(240 5% 8%) moved it two bytes out of 255, which no
+   * eye resolves. A fixed overlay steps by the same amount whatever the page,
+   * and composites over whatever surface the band happens to sit on. */
+  --surface-recessed: rgb(0 0 0 / 0.35);
   /* Hover/active surface (rails, menus, tabs) — a quiet warm lift above the page. */
   --accent: hsl(48 3% 24%);
   --accent-foreground: hsl(48 33% 97%);

package/src/styles/css/theme/light.css

@@ -34,6 +34,11 @@
    * It deliberately keys off --background, not white --card, so hover remains
    * visible on translucent menus and on plain pages alike. */
   --surface-hover: color-mix(in oklab, var(--background) 96%, var(--foreground));
+  /* The counterpart to --surface-hover: a surface that reads as sunk BELOW the
+   * page. A translucent black for the same reason as the dark theme's, but much
+   * weaker: the same overlay costs far more contrast on a near-white ground,
+   * where it goes muddy rather than quiet. */
+  --surface-recessed: rgb(0 0 0 / 0.045);
   /* Neutral hover/active surface — quiet warm-gray lift (Claude bg-200), a
    * clear step (≥4L) below the 97% canvas. */
   --accent: hsl(60 11% 92%);

package/src/styles/css/theme/tokens.css

@@ -39,6 +39,7 @@
   --color-muted: var(--muted);
   --color-muted-foreground: var(--muted-foreground);
   --color-surface-hover: var(--surface-hover);
+  --color-surface-recessed: var(--surface-recessed);
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
   --color-destructive: var(--destructive);