@djangocfg/ui-core 2.1.531 → 2.1.533

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.531",
+  "version": "2.1.533",
   "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.531",
+    "@djangocfg/i18n": "^2.1.533",
     "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.531",
-    "@djangocfg/typescript-config": "^2.1.531",
+    "@djangocfg/i18n": "^2.1.533",
+    "@djangocfg/typescript-config": "^2.1.533",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/components/forms/slider/index.tsx

@@ -18,12 +18,32 @@ export interface SliderProps extends React.ComponentPropsWithoutRef<typeof Slide
   storageType?: StorageType
   /** TTL in ms */
   storageTtl?: number
+  /**
+   * Rendered inside the track, behind the filled range.
+   *
+   * For a second quantity that shares the track's scale — a media player's
+   * buffered extent is the case this exists for. Positioned by the caller and
+   * never interactive: the slider owns every pointer event on the track.
+   */
+  trackDecoration?: React.ReactNode
+  /**
+   * Extra classes for the track, the filled range and the thumb.
+   *
+   * These parts live inside this component, so a consumer cannot reach them:
+   * a descendant selector would have to name classes it does not own, and
+   * arbitrary Tailwind variants targeting them are not reliably generated.
+   * A media scrubber needs a hairline track and a thumb that only appears on
+   * hover, which is what these exist for.
+   */
+  trackClassName?: string
+  rangeClassName?: string
+  thumbClassName?: string
 }
 
 const Slider = React.forwardRef<
   React.ElementRef<typeof SliderPrimitive.Root>,
   SliderProps
->(({ className, orientation = 'horizontal', storageKey, storageType, storageTtl, onValueChange, ...props }, ref) => {
+>(({ className, orientation = 'horizontal', storageKey, storageType, storageTtl, trackDecoration, trackClassName, rangeClassName, thumbClassName, onValueChange, ...props }, ref) => {
   const isVertical = orientation === 'vertical';
 
   const storageOptions: UseStoredValueOptions | undefined =
@@ -55,6 +75,7 @@ const Slider = React.forwardRef<
   return (
     <SliderPrimitive.Root
       ref={ref}
+      data-slot="slider"
       orientation={orientation}
       className={cn(
         "relative flex touch-none select-none",
@@ -66,19 +87,39 @@ const Slider = React.forwardRef<
       {...sliderProps}
     >
       <SliderPrimitive.Track
+        data-slot="slider-track"
         className={cn(
           "relative overflow-hidden rounded-full bg-primary/20",
-          isVertical ? "w-1.5 h-full grow" : "h-1.5 w-full grow"
+          isVertical ? "w-1.5 h-full grow" : "h-1.5 w-full grow",
+          trackClassName
         )}
       >
+        {/* Renders BEHIND the range, inside the track, so a consumer that has a
+            secondary quantity to show (a media player's buffered extent) does not
+            have to fork this component or overlay a second element. */}
+        {trackDecoration}
         <SliderPrimitive.Range
+          data-slot="slider-range"
           className={cn(
             "absolute bg-primary",
-            isVertical ? "w-full bottom-0" : "h-full left-0"
+            isVertical ? "w-full bottom-0" : "h-full left-0",
+            rangeClassName
           )}
         />
       </SliderPrimitive.Track>
-      <SliderPrimitive.Thumb className="block h-4 w-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50" />
+      {/* The accessible name and value text belong on the THUMB: that is where
+          Radix puts `role="slider"`, so a label left on the Root names a
+          generic element and the control itself stays anonymous. */}
+      <SliderPrimitive.Thumb
+        data-slot="slider-thumb"
+        aria-label={props['aria-label']}
+        aria-labelledby={props['aria-labelledby']}
+        aria-valuetext={props['aria-valuetext']}
+        className={cn(
+          "block h-4 w-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+          thumbClassName
+        )}
+      />
     </SliderPrimitive.Root>
   );
 })

package/src/components/index.ts

@@ -99,7 +99,7 @@ export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './over
 // ─────────────────────────────────────────────────────────────────────────────
 export { navigationMenuTriggerStyle, NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuContent, NavigationMenuTrigger, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport } from './navigation/navigation-menu';
 export { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarPortal, MenubarSubContent, MenubarSubTrigger, MenubarGroup, MenubarSub, MenubarShortcut } from './navigation/menubar';
-export { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup } from './navigation/dropdown-menu';
+export { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup, revealOnRowInteraction } from './navigation/dropdown-menu';
 export { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuItem, ContextMenuLabel, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from './navigation/context-menu';
 export { PopoverRowButton } from './navigation/popover-row-button';
 export type { PopoverRowButtonProps } from './navigation/popover-row-button';

package/src/components/navigation/dropdown-menu/index.tsx

@@ -11,6 +11,24 @@ const DropdownMenu = DropdownMenuPrimitive.Root
 
 const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
 
+/**
+ * Classes for a trigger that stays hidden until the row is hovered or focused
+ * — the `…` on a list row, a tab, a tree item.
+ *
+ * The last clause is the one that is easy to miss and impossible to see in a
+ * screenshot of a closed menu: while the menu is OPEN, Radix has moved focus
+ * into the portalled panel and the pointer has left the row, so both reveal
+ * conditions are false and the trigger fades out under the menu it just
+ * opened. `data-state` is set by Radix on any trigger, so this composes with
+ * the primitive and with `MenuBuilder` alike.
+ *
+ * The row must be a `group`. Compose with `cn()` and the row's own sizing.
+ */
+const revealOnRowInteraction =
+  "opacity-0 transition-opacity group-hover:opacity-100 " +
+  "group-focus-within:opacity-100 focus-visible:opacity-100 " +
+  "data-[state=open]:opacity-100 motion-reduce:transition-none"
+
 const DropdownMenuGroup = DropdownMenuPrimitive.Group
 
 const DropdownMenuPortal = DropdownMenuPrimitive.Portal
@@ -232,6 +250,7 @@ DropdownMenuShortcut.displayName = "DropdownMenuShortcut"
 export {
   DropdownMenu,
   DropdownMenuTrigger,
+  revealOnRowInteraction,
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuCheckboxItem,

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);