@djangocfg/ui-core 2.1.443 → 2.1.444

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.444",
   "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.444",
     "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.444",
+    "@djangocfg/typescript-config": "^2.1.444",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

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% 21%)',  // hairline, softer than border
     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,18 @@ 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
-    border: 'hsl(240 3% 78%)',
+    // Apple opaque separator: rgba(60,60,67,0.29) on white ≈ #C6C6C8 → HSL 240 3% 78%.
+    // Nudged a touch darker (78→74) so control/panel outlines actually read on
+    // white cards — the pure hairline vanished on elevated surfaces.
+    border: 'hsl(240 3% 74%)',
     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 +101,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 +115,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 +128,20 @@ 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
-    border: 'hsl(240 3% 22%)',
-    input: 'hsl(240 3% 19%)',
+    // Separator dark: rgba(84,84,88,0.36). Raised 22→28 — Apple's hairline is
+    // authored for content-on-content, but on the near-black #141414 page it was
+    // invisible, so control/panel outlines had no edge. 28 keeps it a hairline
+    // while actually drawing against the dark canvas.
+    border: 'hsl(240 3% 28%)',
+    input: 'hsl(240 3% 22%)',
     // Row hairline — softer than border so dark rows don't read as a hard rule
-    divider: 'hsl(240 3% 18%)',
+    divider: 'hsl(240 3% 22%)',
     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 +149,9 @@ 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%)',
+    // Raised 15→22 to match --border: the sidebar edge was lost against the
+    // near-black rail + page.
+    '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/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%)',
@@ -113,6 +117,8 @@ export const windowsPreset: ThemePreset = {
     // Hairline between rows — softer than border
     divider: 'hsl(0 0% 22%)',
     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,