@djangocfg/ui-core 2.1.462 → 2.1.464

package/package.json

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

package/src/components/navigation/menu/render-items.tsx

@@ -123,6 +123,11 @@ export function renderItems(
                   key={option.id}
                   value={option.value}
                   disabled={option.disabled}
+                  onSelect={(event) => {
+                    // closeOnSelect=false → keep the menu open so the selection
+                    // can reveal more of the same menu (e.g. an engine preview).
+                    if (item.closeOnSelect === false) event.preventDefault();
+                  }}
                 >
                   <MenuIndicatorRow
                     icon={option.icon}

package/src/components/navigation/menu/types.ts

@@ -66,6 +66,11 @@ export interface MenuRadioGroup {
   value: string;
   onValueChange: (value: string) => void;
   options: MenuRadioOption[];
+  /** Keep the menu OPEN after a selection (default: false = close, Radix's
+   *  default). Use for a radio group whose pick reveals more of the SAME menu
+   *  (e.g. an engine row that previews that engine's models below it) rather
+   *  than being a terminal choice. */
+  closeOnSelect?: boolean;
 }
 
 /** Visual divider. */

package/src/styles/README.md

@@ -37,6 +37,9 @@ styles/
 There are deliberately no TypeScript color maps and no runtime CSS generator.
 Do not add a second palette in React or TypeScript.
 
+`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:
@@ -62,6 +65,69 @@ For a product-specific adjustment, add a small override after the preset:
 Do not create a `theme-preset.ts`, append a `<style>` tag, or call a token
 builder during application startup.
 
+### Import order
+
+Keep the application entrypoint minimal and deterministic:
+
+```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";
+```
+
+`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.
+
+### Tailwind source scanning
+
+`css/sources.css` is part of the `full` entry and must scan the package source
+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.
+
+### Overlays and glass surfaces
+
+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`):
+
+```css
+.bg-overlay {
+  background: var(--overlay);
+  backdrop-filter: blur(var(--overlay-blur));
+}
+```
+
+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.
+
+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.
+
 ## Token format
 
 Color variables are complete CSS colors, never bare HSL triplets:
@@ -86,7 +152,7 @@ Typography variables are ordinary CSS values:
 
 ## Preset rules
 
-- Presets are authored directly in `presets/css/`.
+- 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.
@@ -104,3 +170,18 @@ pnpm check
 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.
+
+For a local cross-repository change, use the consumer's sync command and
+restart its dev server afterward:
+
+```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
+```
+
+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.

package/src/styles/css/base.css

@@ -23,7 +23,7 @@
    * / sheet) blurs the page behind it. Theme-agnostic (same both modes);
    * a preset can override for a heavier/lighter frost, or set `0px` to disable
    * the blur while keeping the `--overlay` dimming scrim. 2px = a subtle frost. */
-  --overlay-blur: 2px;
+  --overlay-blur: 5px;
 
   /* Typography tokens — overridable per preset */
   --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;

package/src/styles/css/sources.css

@@ -6,4 +6,5 @@
  *
  * Scans all TypeScript files recursively from package root.
  */
-@source "../**/*.{ts,tsx}";
+/* This file lives in src/styles/css; ../../ reaches the package src root. */
+@source "../../**/*.{ts,tsx}";

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

@@ -34,6 +34,8 @@
   /* Recessed surface — below the page (Claude bg-200), for input rest / chips. */
   --muted: hsl(30 3.3% 11.8%);
   --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));
   /* 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

@@ -24,6 +24,10 @@
   --secondary-foreground: hsl(0 0% 98%);
   --muted: hsl(0 0% 96%);
   --muted-foreground: hsl(0 0% 45%);
+  /* Neutral interaction surface: a quiet step below the current light canvas.
+   * 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));
   /* Neutral hover/active surface — quiet gray lift, no hue tint
    * (Claude/macOS settings convention). */
   --accent: hsl(0 0% 94%);

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

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

package/src/styles/css/utilities/controls.css

@@ -10,3 +10,8 @@
 .rounded-control {
   border-radius: var(--radius-control);
 }
+
+/* Static package utility: do not depend on a consumer Tailwind source scan. */
+.surface-hover:hover {
+  background-color: var(--surface-hover);
+}

package/src/styles/css/utilities/glass.css

@@ -55,3 +55,19 @@
   -webkit-backdrop-filter: blur(8px) saturate(160%);
   background-color: color-mix(in oklab, var(--background) 80%, transparent);
 }
+
+/**
+ * PublicLayout desktop navigation dropdown.
+ * Keep this as a package utility instead of relying on a consumer's Tailwind
+ * source scan: the layout is distributed code, while the dropdown must still
+ * frost whatever page is underneath it.
+ */
+.nav-dropdown-glass {
+  backdrop-filter: blur(var(--overlay-blur, 5px)) saturate(150%);
+  -webkit-backdrop-filter: blur(var(--overlay-blur, 5px)) saturate(150%);
+  background-color: color-mix(in oklab, var(--background) 55%, transparent);
+}
+
+.dark .nav-dropdown-glass {
+  background-color: color-mix(in oklab, var(--card) 55%, transparent);
+}