@djangocfg/ui-core 2.1.443 → 2.1.445

package/README.md

@@ -91,12 +91,78 @@ Imports stay flat — group folders are organisational.
 
 ## Router adapters
 
-The router-aware components (`Sidebar`, `Link`, `SSRPagination`) read the active router via `RouterAdapterProvider`. Ship the adapter that matches your host:
+The router-aware primitives (`Sidebar`, `Link`, `SSRPagination`, and the
+`useRouter` / `useNavigate` / `useLocation` hooks) navigate through a **pluggable
+adapter**, so the same components work under any host. ui-core itself is
+router-agnostic and has **zero router dependency** — pick the adapter for your
+host and mount it once near the root.
 
-| Adapter | Source |
-|---|---|
-| Next.js App Router | `@djangocfg/ui-core/adapters/nextjs` |
-| Plain `<a>` fallback | default (no adapter) |
+### Which adapter for which host
+
+| Host | Mount this | Extra dependency you install |
+|---|---|---|
+| **Next.js** (App Router) | `NextRouterAdapter` from `@djangocfg/ui-core/adapters/nextjs` | `next` (you already have it) |
+| **Vite / React-Router SPA** | `ReactRouterProvider` from `@djangocfg/ui-core/adapters/react-router` | `react-router` **≥7** — add to your app's `dependencies` |
+| **Wails / Electron / plain React / Storybook** | **nothing** — the default History-API adapter is used automatically | none (zero deps) |
+
+`next` and `react-router` are **optional peers**: the base package never imports
+them. Only the matching sub-path entry does, so the dep is resolved *only* when
+you import that adapter. Never add both — import the one sub-path for your host.
+
+### Where to mount it
+
+Both provider adapters wrap a subtree; every ui-core router call inside it flows
+through your app's router. Mount **once**, near the root:
+
+```tsx
+// Next.js — inside the client provider stack (below your i18n provider)
+import { NextRouterAdapter } from '@djangocfg/ui-core/adapters/nextjs';
+<NextRouterAdapter><AppLayout>{children}</AppLayout></NextRouterAdapter>
+
+// Vite / React-Router — INSIDE the router context (an element RouterProvider
+// renders, e.g. a layout route wrapping <Outlet/>), NOT around <RouterProvider>.
+import { ReactRouterProvider } from '@djangocfg/ui-core/adapters/react-router';
+function Shell() {
+  return <ReactRouterProvider><Layout><Outlet /></Layout></ReactRouterProvider>;
+}
+```
+
+> **React-Router gotcha:** mounting `ReactRouterProvider` *around*
+> `<RouterProvider>` throws — that subtree has no router context, so
+> `useNavigate` fails. Always mount it *inside*.
+
+### What happens if you skip it
+
+Without an adapter, hooks fall back to the **default History-API adapter**
+(`window.history.pushState` + `window.location`). This is intentional and works
+everywhere with zero deps — but in a *framework* host it silently loses the
+framework's routing behavior:
+
+- **Next.js without `NextRouterAdapter`:** no RSC refetch on navigation, no route
+  loader, no prefetch. Links still change the URL, but the App Router doesn't
+  react. → always mount it in Next apps.
+- **React-Router without `ReactRouterProvider`:** programmatic `useNavigate` /
+  `<Link>` mutate `window.history` directly and bypass the `<Outlet/>` swap, so
+  navigation desyncs from the data router. → always mount it in RR SPAs.
+
+For a plain SPA (Wails/Electron/CRA) the History-API default *is* the right
+backend — mount nothing.
+
+### Link adapters (optional, Next.js)
+
+By default `<Link>` from `@djangocfg/ui-core/components` renders a plain `<a>`.
+To route Next's prefetch / RSC handling through it, also mount `NextLinkProvider`
+alongside `NextRouterAdapter`. For locale-prefixed hrefs with `next-intl`, pass
+`createNextIntlLinkAdapter(IntlLink)` as `AppLayout`'s `linkAdapter` — both live
+in `@djangocfg/ui-core/adapters/nextjs`.
+
+> **Deeper dive:** full adapter reference, the `useRouter` / `useNavigate` /
+> `useLocation` / `useQueryState` hook surface, and a ~20-line recipe for
+> **custom** routers (TanStack Router, wouter, Remix, custom transports) live in
+> [`src/hooks/router/README.md`](./src/hooks/router/README.md).
+
+> Using `@djangocfg/layouts`? `BaseApp` already mounts the Next adapters for you
+> — you don't wire them by hand.
 
 ## Theming (`/styles`)
 

package/package.json

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

package/src/components/layout/resizable/index.tsx

@@ -136,7 +136,9 @@ const ResizableHandle = ({
     return (
       <div
         className={cn(
-          "bg-border w-px",
+          // Separator between panels → `bg-divider` (soft hairline), not the
+          // opaque `bg-border` outline weight, so a resize seam stays quiet.
+          "bg-divider w-px",
           "data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full",
           className
         )}
@@ -147,7 +149,7 @@ const ResizableHandle = ({
   return (
     <ResizablePrimitive.PanelResizeHandle
       className={cn(
-        "relative flex items-center justify-center bg-border",
+        "relative flex items-center justify-center bg-divider",
         "w-px h-full",
         "hover:bg-primary/20 active:bg-primary/30",
         "transition-colors",

package/src/styles/README.md

@@ -68,8 +68,8 @@ This makes opacity modifiers (`bg-card/40`, `border-foreground/20`) resolve thro
 | `bg-primary` / `text-primary-foreground` | `--primary` | Brand CTA (filled buttons, links) — cyan |
 | `bg-secondary` / `text-secondary-foreground` | `--secondary` | Neutral filled controls |
 | `bg-destructive` / `text-destructive-foreground` | `--destructive` | Error / delete filled controls |
-| `border-border` | `--border` | Card outlines, control borders |
-| `border-divider` / `.divider-b` | `--divider` | **Hairline between rows** — deliberately *lighter than `--card`* so it stays visible on elevated surfaces (a `--border` line vanishes on a card) |
+| `border-border` | `--border` | **Outlines only** — card frames, control/input edges. *Not* for separators (see Presets § Border vs divider) |
+| `border-divider` / `.divider-b` / `bg-divider` | `--divider` | **All separators** — columns, header `border-b`, list rows, resize handles. A soft hairline (translucent on dark themes) so the chrome never reads as a heavy grid |
 | `bg-overlay` | `--overlay` | Modal scrim / backdrop behind dialogs, drawers, sheets — black scrim in both themes, the token owns the opacity |
 | `bg-input` | `--input` | Input **fill** — a notch off the panel so fields read as real controls (not flush holes). The input *border* uses `--border`, not `--input` |
 | `ring-ring` | `--ring` | Focus rings, selected outlines — **blue** (system-accent feel), independent of the cyan brand |
@@ -299,6 +299,35 @@ Two families, with different coverage by design:
 | `dense` | modifier | Smaller radius (0.25rem) — data-heavy admin UIs |
 | `high-contrast` | modifier | A11y boost — stronger borders, harder text, pure canvas |
 
+#### Border vs divider — outline weight vs translucent hairline
+
+`--border` and `--divider` are **two different roles**, not two shades of one:
+
+- **`--border`** — an OUTLINE: opaque, control-weight. Card frames, input
+  edges, panel outlines. Use `border-border` / `border border-border`.
+- **`--divider`** — a SEPARATOR: a soft hairline between things. Shell columns,
+  header `border-b` rules, list rows, resize handles. Use `border-divider` /
+  `.divider-b` / `bg-divider`, or `divide-*` on a `divide-y` stack.
+
+On the **dark** themes the separator token is now a **translucent** hairline —
+`hsl(H S 46-48% / 0.18)` — mirroring Apple's own `rgba(84,84,88,0.36)` approach:
+a light grey at low alpha that *dissolves into whatever sits behind it* instead
+of a fixed opaque line. This is deliberate. An opaque separator (even a dim one)
+read as a hard grid on a near-black canvas — every column edge and header rule
+looked heavy. A translucent hairline self-adapts: heavier where it crosses an
+elevated card, lighter on the page. Every dark preset carries it (`macos`,
+`ios`, `windows`, `dense`, `soft`, and the base `dark.css` behind
+`default`/`django-cfg`); **`high-contrast` keeps an opaque divider on purpose**
+(a11y wants the harder line). Light themes keep an opaque divider too — a
+translucent line on white gains nothing.
+
+The alpha was tuned by eye in a live cmdop-web session (0.18 is quiet-but-present;
+lower starts to vanish on the page).
+
+**If a dark surface looks too contrasty**, the culprit is almost always a
+column/row/header separator wrongly drawn with `--border` (the outline weight)
+instead of `--divider` — move it to `border-divider` / `var(--divider)`.
+
 ### Apply a preset
 
 ```tsx

package/src/styles/presets/themes/dense.ts

@@ -23,7 +23,7 @@ export const densePreset: ThemePreset = {
     radius: '0.25rem',
     border: 'hsl(0 0% 24%)',
     input: 'hsl(0 0% 24%)',
-    divider: 'hsl(0 0% 18%)',
+    divider: 'hsl(0 0% 46% / 0.18)',  // translucent hairline — dissolves into the page
     muted: 'hsl(0 0% 12%)',
     card: 'hsl(0 0% 10%)',
     accent: 'hsl(0 0% 14%)',

package/src/styles/presets/themes/ios.ts

@@ -18,11 +18,13 @@ export const iosPreset: ThemePreset = {
     'accent-foreground': 'hsl(220 9% 12%)',
     destructive: 'hsl(0 100% 58%)',
     'destructive-foreground': 'hsl(0 0% 100%)',
-    border: 'hsl(220 9% 88%)',
+    border: 'hsl(220 9% 85%)',   // nudged darker so outlines read on white cards
     input: 'hsl(220 9% 88%)',
     ring: 'hsl(211 100% 50%)',
-    divider: 'hsl(220 9% 84%)',  // hairline, a touch lighter than border
+    divider: 'hsl(220 9% 88%)',  // hairline, a touch lighter than border
     radius: '0.75rem',
+    // Modal scrim — light dim, iOS sheets keep the backdrop visible.
+    overlay: 'hsl(220 9% 10% / 0.32)',
     'sidebar-background': 'hsl(0 0% 99%)',
     'sidebar-foreground': 'hsl(220 9% 12%)',
     'sidebar-primary': 'hsl(211 100% 50%)',
@@ -55,25 +57,31 @@ export const iosPreset: ThemePreset = {
   dark: {
     background: 'hsl(240 6% 10%)',
     foreground: 'hsl(0 0% 96%)',
-    card: 'hsl(240 6% 14%)',
+    // Lifted 14→16 for a clearer float off the dark page (see macos rationale).
+    card: 'hsl(240 6% 16%)',
     'card-foreground': 'hsl(0 0% 96%)',
-    popover: 'hsl(240 6% 16%)',
+    // Kept a distinct step above card.
+    popover: 'hsl(240 6% 20%)',
     'popover-foreground': 'hsl(0 0% 96%)',
     primary: 'hsl(211 100% 55%)',
     'primary-foreground': 'hsl(0 0% 100%)',
     secondary: 'hsl(240 5% 26%)',
     'secondary-foreground': 'hsl(0 0% 96%)',
-    muted: 'hsl(240 5% 16%)',
+    // Recessed surface — below the page (bg 10%) and below card (16%), so
+    // bg-muted rails/chips read as sunk, not level with the panel.
+    muted: 'hsl(240 5% 13%)',
     'muted-foreground': 'hsl(240 5% 64%)',
     accent: 'hsl(240 5% 18%)',
     'accent-foreground': 'hsl(0 0% 96%)',
     destructive: 'hsl(0 100% 67%)',
     'destructive-foreground': 'hsl(0 0% 100%)',
-    border: 'hsl(240 5% 22%)',
+    border: 'hsl(240 5% 27%)',   // raised so outlines read on the dark page
     input: 'hsl(240 5% 22%)',
     ring: 'hsl(211 100% 55%)',
-    divider: 'hsl(240 5% 18%)',  // hairline, softer than border
+    divider: 'hsl(240 5% 48% / 0.18)',  // translucent hairline — dissolves into the page
     radius: '0.75rem',
+    // Modal scrim — lighter than base 0.7 so the dark page still reads behind.
+    overlay: 'hsl(0 0% 0% / 0.55)',
     'sidebar-background': 'hsl(240 6% 8%)',
     'sidebar-foreground': 'hsl(0 0% 96%)',
     'sidebar-primary': 'hsl(211 100% 55%)',

package/src/styles/presets/themes/macos.ts

@@ -52,14 +52,19 @@ export const macosPreset: ThemePreset = {
     // systemRed #FF3B30
     destructive: 'hsl(2 100% 59%)',
     'destructive-foreground': 'hsl(0 0% 100%)',
-    // Apple opaque separator: rgba(60,60,67,0.29) on white ≈ #C6C6C8 → HSL 240 3% 78%
-    // Kept intentionally light — Apple hairline, not a thick rule
+    // Apple opaque separator: rgba(60,60,67,0.29) on white ≈ #C6C6C8 → HSL 240 3% 78%.
+    // Kept at the Apple hairline value (78%). An earlier build nudged this darker
+    // (78→74) to force outlines onto white cards, but that over-contrasted every
+    // panel/header `border-b` on the grouped canvas — back to the HIG hairline.
     border: 'hsl(240 3% 78%)',
     input: 'hsl(240 8% 93%)',
     // Row hairline — a touch lighter than border so it reads on white cards
-    divider: 'hsl(240 4% 85%)',
+    divider: 'hsl(240 4% 83%)',
     ring: 'hsl(211 100% 50%)',
     radius: '0.625rem',
+    // Modal scrim — lighter than the base 0.6 so the light grouped canvas still
+    // reads behind the dialog (Apple sheets dim, they don't black out).
+    overlay: 'hsl(240 6% 10% / 0.32)',
     // Sidebar: slighly darker than page, matches macOS sidebar material
     'sidebar-background': 'hsl(240 12% 94%)',
     'sidebar-foreground': 'hsl(0 0% 7%)',
@@ -97,11 +102,13 @@ export const macosPreset: ThemePreset = {
     // Deeper than stock #1C1C1E — matches Sequoia dark finder/mail chrome (#141414)
     background: 'hsl(240 5% 8%)',
     foreground: 'hsl(0 0% 95%)',
-    // secondarySystemBackground #1E1E20 — cards slightly elevated
-    card: 'hsl(240 3% 12%)',
+    // secondarySystemBackground #1E1E20 — cards lifted above the #141414 page.
+    // Bumped 12→15 so panels (dialog body, settings cards) visibly float off the
+    // near-black canvas; on L≈8 a +4 lift is too subtle for the eye (Weber).
+    card: 'hsl(240 3% 15%)',
     'card-foreground': 'hsl(0 0% 95%)',
-    // #2C2C2E — popovers, menus, dropdowns
-    popover: 'hsl(240 3% 17%)',
+    // #2C2C2E — popovers, menus, dropdowns; kept a clear step above card.
+    popover: 'hsl(240 3% 20%)',
     'popover-foreground': 'hsl(0 0% 95%)',
     // systemBlue dark #0A84FF
     primary: 'hsl(211 100% 58%)',
@@ -109,8 +116,12 @@ export const macosPreset: ThemePreset = {
     // Elevated neutral surface — slightly lighter than card
     secondary: 'hsl(240 3% 20%)',
     'secondary-foreground': 'hsl(0 0% 88%)',
-    // tertiarySystemBackground #3A3A3C — chips, tags, muted fills
-    muted: 'hsl(240 3% 23%)',
+    // Recessed surface — a notch BELOW the page (bg 8%), like default's muted.
+    // `--muted` is the "sunk" surface (input rest, nav rails, chips): it must
+    // read as recessed vs `--card` (15%), not raised. Apple's #3A3A3C
+    // tertiary fill (23%) sat *above* card and inverted the depth — the
+    // SettingsDialog nav rail (bg-muted) then looked lighter than its panel.
+    muted: 'hsl(240 3% 11%)',
     'muted-foreground': 'hsl(240 4% 58%)',
     // Blue-tinted hover (Apple active state in dark)
     accent: 'hsl(211 25% 19%)',
@@ -118,13 +129,28 @@ export const macosPreset: ThemePreset = {
     // systemRed dark #FF453A
     destructive: 'hsl(3 100% 62%)',
     'destructive-foreground': 'hsl(0 0% 100%)',
-    // Separator dark: rgba(84,84,88,0.36) — ultra-thin, almost invisible
+    // Control/panel OUTLINE — input & card frames, not separators. Opaque 22%
+    // reads cleanly as a control edge on card (L15) surfaces. Structural
+    // separators (shell columns, headers, list rows) do NOT use this — they use
+    // `--divider`, which is a softer translucent hairline (see below), so the
+    // outline weight here never turns the chrome into a hard grid.
     border: 'hsl(240 3% 22%)',
-    input: 'hsl(240 3% 19%)',
-    // Row hairline — softer than border so dark rows don't read as a hard rule
-    divider: 'hsl(240 3% 18%)',
+    input: 'hsl(240 3% 22%)',
+    // Separator hairline — TRANSLUCENT, mirroring Apple's rgba(84,84,88,0.36):
+    // a light grey at low alpha that dissolves into whatever sits behind it
+    // instead of a fixed opaque line. This is the token for ALL structural
+    // separators — shell columns (rail↔list↔chat), header `border-b` rules, and
+    // list-row hairlines — deliberately softer than the opaque `--border`
+    // outline so the chrome never reads as a hard grid on the near-black canvas.
+    // 46% L @ 0.18 alpha picked live in cmdop-web: a quiet, self-adapting
+    // hairline (heavier over an elevated card, lighter on the page).
+    divider: 'hsl(240 4% 46% / 0.18)',
     ring: 'hsl(211 100% 58%)',
     radius: '0.625rem',
+    // Modal scrim — a touch lighter than the base 0.7. The page is already near
+    // black (L≈8); 0.55 dims it enough to separate the dialog without crushing
+    // the backdrop into a flat black slab the panel can't lift off of.
+    overlay: 'hsl(0 0% 0% / 0.55)',
     // Sidebar: near-black floor — #0D0D0F
     'sidebar-background': 'hsl(240 5% 5%)',
     'sidebar-foreground': 'hsl(0 0% 90%)',
@@ -132,7 +158,10 @@ export const macosPreset: ThemePreset = {
     'sidebar-primary-foreground': 'hsl(0 0% 100%)',
     'sidebar-accent': 'hsl(211 22% 16%)',
     'sidebar-accent-foreground': 'hsl(211 100% 72%)',
-    'sidebar-border': 'hsl(240 3% 15%)',
+    // 22 — the sidebar rail floor is #0D0D0F (L5), darker than the page (L8), so
+    // its edge needs a touch more lift than the page-calibrated `--border` (18)
+    // to read at all. Still a hairline, not the hard rule an outline weight draws.
+    'sidebar-border': 'hsl(240 3% 22%)',
     'sidebar-ring': 'hsl(211 100% 58%)',
     // Chart: brighter variants for contrast on dark
     'chart-1': 'hsl(211 100% 58%)',

package/src/styles/presets/themes/soft.ts

@@ -39,7 +39,7 @@ export const softPreset: ThemePreset = {
     'accent-foreground': 'hsl(0 0% 96%)',
     border: 'hsl(240 5% 20%)',
     input: 'hsl(240 5% 20%)',
-    divider: 'hsl(240 5% 16%)',
+    divider: 'hsl(240 5% 48% / 0.18)',  // translucent hairline — dissolves into the page
     radius: '1rem',
     'sidebar-background': 'hsl(240 6% 6%)',
     'sidebar-accent': 'hsl(240 5% 14%)',

package/src/styles/presets/themes/windows.ts

@@ -47,6 +47,8 @@ export const windowsPreset: ThemePreset = {
     // Hairline between rows — slightly lighter than border
     divider: 'hsl(0 0% 84%)',
     ring: 'hsl(210 100% 45%)',
+    // Fluent SmokeFillColorDefault — content dialogs dim the layer beneath.
+    overlay: 'hsl(0 0% 0% / 0.4)',
     // WinUI 3: 4px controls, 8px cards/dialogs
     radius: '0.375rem',
     'sidebar-background': 'hsl(0 0% 92%)',
@@ -101,7 +103,9 @@ export const windowsPreset: ThemePreset = {
     'primary-foreground': 'hsl(0 0% 9%)',
     secondary: 'hsl(0 0% 22%)',
     'secondary-foreground': 'hsl(0 0% 90%)',
-    muted: 'hsl(0 0% 18%)',
+    // Recessed surface — below the page (bg 13%) and below card (17%), so
+    // bg-muted rails/chips read as sunk, not raised above the panel.
+    muted: 'hsl(0 0% 15%)',
     'muted-foreground': 'hsl(0 0% 62%)',
     accent: 'hsl(210 25% 20%)',
     'accent-foreground': 'hsl(200 100% 75%)',
@@ -111,8 +115,10 @@ export const windowsPreset: ThemePreset = {
     border: 'hsl(0 0% 28%)',
     input: 'hsl(0 0% 24%)',
     // Hairline between rows — softer than border
-    divider: 'hsl(0 0% 22%)',
+    divider: 'hsl(0 0% 46% / 0.18)',  // translucent hairline — dissolves into the page
     ring: 'hsl(200 100% 69%)',
+    // Fluent SmokeFillColorDefault dark — dims the dark page behind the dialog.
+    overlay: 'hsl(0 0% 0% / 0.55)',
     radius: '0.375rem',
     // NavigationView pane background
     'sidebar-background': 'hsl(0 0% 10%)',

package/src/styles/presets/types.ts

@@ -35,8 +35,12 @@ export type ThemeCssVarColorKey =
  * Layout / focus tokens — `radius` is a CSS length, the rest are wrapped colors.
  * `divider` is the hairline-between-rows token (deliberately *lighter* than
  * `--card` so it stays visible on elevated surfaces — see styles README).
+ * `overlay` is the modal scrim behind dialogs/drawers/sheets — a wrapped color
+ * that OWNS its own opacity (`hsl(0 0% 0% / 0.55)`). Brand presets that set a
+ * custom `background` should set `overlay` too: on a near-black canvas the base
+ * 0.6/0.7 scrim crushes the backdrop flat and the dialog can't lift off it.
  */
-export type ThemeCssVarChromeKey = 'border' | 'input' | 'divider' | 'ring' | 'radius';
+export type ThemeCssVarChromeKey = 'border' | 'input' | 'divider' | 'overlay' | 'ring' | 'radius';
 
 /**
  * Status surfaces — each role has a 4-token set (icon/accent, banner background,

package/src/styles/theme/dark.css

@@ -44,9 +44,11 @@
   --border: hsl(48 3% 28%);
   /* Input surface — a notch above card so fields read as raised controls. */
   --input: hsl(48 2.5% 24%);
-  /* Divider — hairline; slightly softer than --border so rows don't read as a
-   * hard rule (Claude menus/rows). */
-  --divider: hsl(48 3% 24%);
+  /* Divider — TRANSLUCENT hairline (Apple-style): a light warm-gray at low alpha
+   * that dissolves into whatever sits behind it, so structural separators
+   * (columns, headers, rows) stay quiet on the dark page instead of reading as a
+   * hard opaque rule. Backs default + django-cfg (they don't re-declare it). */
+  --divider: hsl(48 4% 46% / 0.18);
   /* Overlay — modal scrim / backdrop behind dialogs, drawers, sheets. Black in
    * both themes; slightly darker here so it still reads on the dark page. */
   --overlay: hsl(0 0% 0% / 0.7);