@djangocfg/ui-core 2.1.453 → 2.1.455

package/package.json

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

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

@@ -19,7 +19,7 @@ const AlertDialogOverlay = React.forwardRef<
 >(({ className, style, ...props }, ref) => (
   <AlertDialogPrimitive.Overlay
     className={cn(
-      "fixed inset-0 z-600 overlay-backdrop data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      "fixed inset-0 z-600 bg-overlay data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
       className
     )}
     style={style}

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

@@ -22,7 +22,7 @@ const DialogOverlay = React.forwardRef<
   <DialogPrimitive.Overlay
     ref={ref}
     className={cn(
-      "fixed inset-0 z-600 overlay-backdrop data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      "fixed inset-0 z-600 bg-overlay data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
       className
     )}
     style={style}

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

@@ -50,7 +50,7 @@ const DrawerOverlay = React.forwardRef<
 >(({ className, style, ...props }, ref) => (
   <DrawerPrimitive.Overlay
     ref={ref}
-    className={cn("fixed inset-0 z-500 overlay-backdrop transition-opacity duration-200", className)}
+    className={cn("fixed inset-0 z-500 bg-overlay transition-opacity duration-200", className)}
     style={style}
     {...props}
   />

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

@@ -22,7 +22,7 @@ const SheetOverlay = React.forwardRef<
 >(({ className, style, ...props }, ref) => (
   <SheetPrimitive.Overlay
     className={cn(
-      "fixed inset-0 z-200 overlay-backdrop data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      "fixed inset-0 z-200 bg-overlay data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
       className
     )}
     style={style}

package/src/hooks/index.ts

@@ -53,6 +53,8 @@ export {
   useIsActive,
   // useQueryState (typed single-key URL state)
   useQueryState,
+  // useHashState (useState-style URL fragment binding; adapter-bypassing)
+  useHashState,
   // Parsers
   parseAsString,
   parseAsInteger,
@@ -86,6 +88,8 @@ export type {
   UseIsActiveOptions,
   UseQueryStateOptions,
   QueryStateUpdater,
+  UseHashStateOptions,
+  HashStateUpdater,
   QueryParser,
   QueryParserBuilder,
   UseRouterReturn,

package/src/hooks/router/README.md

@@ -14,6 +14,7 @@ Framework-agnostic navigation primitives for `@djangocfg/ui-core`. Built on plai
 | `useSmartLink` | Click + keyboard handlers that turn any element into a proper link (cmd-click, middle-click, Enter, Space). |
 | `useIsActive` | `boolean` for "current pathname matches this href" — for nav-item highlighting. |
 | `useQueryState` | Typed `useState`-style hook bound to ONE URL key (with parsers + `clearOnDefault`). |
+| `useHashState` | `useState`-style hook bound to the URL fragment (`#…`). Writes bypass the adapter — see [`useHashState`](#usehashstate-url-fragment) below. |
 | `useLocationProperty` | Subscribe to ONE derived field of `window.location` (avoids re-renders on unrelated fields). |
 | `useRouter` | Convenience facade composing the above. |
 | `RouterAdapterProvider` | Swap the navigation backend (e.g. Next.js's router). |
@@ -122,6 +123,29 @@ setPage(null);               // clears the key from the URL
 
 Parsers: `parseAsString`, `parseAsInteger`, `parseAsFloat`, `parseAsBoolean`, `parseAsIsoDate`, `parseAsStringEnum([...])`, `parseAsArrayOf(item)`, `parseAsJson<T>()`. Each has `.withDefault(value)`. Build your own by satisfying the `QueryParser<T>` interface — it's three functions (`parse`, `serialize`, `eq`).
 
+## `useHashState` (URL fragment)
+
+`useState`-style binding to `window.location.hash`. The value is the fragment **without** the leading `#` (`''` when absent); setting `''`/`null` strips it.
+
+```tsx
+import { useHashState } from '@djangocfg/ui-core/hooks';
+
+const [hash, setHash] = useHashState();
+setHash('settings/account');            // → …/private#settings/account (pushState)
+setHash('overview', { replace: true }); // no new history entry
+setHash((h) => h || 'top');             // functional updater
+setHash(null);                          // strip the fragment → …/private
+```
+
+**Why it bypasses the adapter (and `useQueryState` does not).** The fragment is the one part of the URL that must NOT go through `navigate()` / `next.push()`:
+
+- The hash is invisible to the server, so a `#hash` change needs no RSC refetch / loader / prefetch — routing it through the framework router is wasteful.
+- Worse, it's **wrong** under Next.js App Router: `router.push('/path#b')` where `/path` equals the current pathname resolves the target *relative to the current URL including its existing hash*, so pushing `…#b` while the URL already reads `…#a` yields a doubled `…#a#b` (compounded by `next-intl` locale prefixing).
+
+So `useHashState` writes via `history.pushState` / `replaceState` directly, against the **absolute** URL. Reads stay reactive through the same patched-history observation as every other router hook, so the round-trip works in Next / Wails / Vite / plain React alike.
+
+Query state is the opposite: `?key=value` IS server-visible, so `useQueryParams` / `useQueryState` deliberately go **through** the adapter — a query change must drive Next's router to refetch server components and re-run loaders. Don't "fix" them to use the History API.
+
 ## How `useLocation` knows about `pushState`
 
 Browsers don't fire `popstate` for programmatic `pushState` / `replaceState`. We monkey-patch both methods once (idempotent, module-level guard) on first mount and dispatch a custom `'djc:navigate'` event after each call. Anyone calling history APIs anywhere in the page will trigger an update — including the consumer's own router, third-party scripts, and our default adapter.

package/src/hooks/router/index.ts

@@ -72,6 +72,14 @@ export type {
   QueryStateUpdater,
 } from './useQueryState';
 
+// useHashState (useState-style binding to the URL fragment; bypasses the
+// adapter so `#hash` writes are absolute — avoids Next.js hash doubling)
+export { useHashState } from './useHashState';
+export type {
+  UseHashStateOptions,
+  HashStateUpdater,
+} from './useHashState';
+
 // Parsers (typed marshalling between URL strings and JS values)
 export {
   parseAsString,

package/src/hooks/router/useHashState.ts

@@ -0,0 +1,106 @@
+'use client';
+
+/**
+ * useHashState — `useState`-style hook bound to `window.location.hash`.
+ *
+ * WHY A DEDICATED HOOK (and why it bypasses the router adapter):
+ *   The URL fragment (`#…`) is the one part of the URL that must NOT go through
+ *   the router adapter's `navigate()` / `next.push()`. Under Next.js App Router
+ *   — especially with `next-intl` locale prefixing — `router.push('/path#hash')`
+ *   where `/path` equals the current pathname resolves the target *relative to
+ *   the current URL, including its existing hash*. Pushing `…#b` while the URL
+ *   already reads `…#a` yields a doubled `…#a#b`. A `#hash` change also never
+ *   needs an RSC refetch / loader / prefetch, so routing it through the
+ *   framework router is both wrong (the doubling) and wasteful.
+ *
+ *   This hook therefore writes the hash via `history.pushState` / `replaceState`
+ *   directly, always against the *absolute* URL (`pathname + search + #hash`).
+ *   Reads stay reactive through `useLocationProperty` — which observes the same
+ *   patched history methods (see `useLocation.ts`), so the round-trip works in
+ *   every host (Next.js, Wails, Vite, plain React) with no adapter involved.
+ *
+ * SHAPE:
+ *   The value is the fragment WITHOUT the leading `#`. `''` means "no hash".
+ *   Setting `''` or `null` removes the fragment (and the trailing `#`) entirely.
+ *
+ * @example
+ *   const [hash, setHash] = useHashState();
+ *   setHash('settings/account');   // → …/private#settings/account (pushState)
+ *   setHash('overview', { replace: true }); // no new history entry
+ *   setHash((h) => h || 'top');    // functional updater
+ *   setHash(null);                 // strip the fragment → …/private
+ *
+ * @example  // deep-linkable dialog section
+ *   const [section, setSection] = useHashState();  // e.g. "settings/usage"
+ */
+
+import { useCallback } from 'react';
+
+import { useLocationProperty } from './useLocation';
+
+export interface UseHashStateOptions {
+  /** Use `replaceState` instead of `pushState` for writes. Default: false. */
+  replace?: boolean;
+}
+
+export type HashStateUpdater =
+  | string
+  | null
+  | ((current: string) => string | null);
+
+/** Strip a single leading '#'. `'#a/b'` → `'a/b'`; `''`/`'#'` → `''`. */
+function stripHash(raw: string): string {
+  if (!raw) return '';
+  return raw.startsWith('#') ? raw.slice(1) : raw;
+}
+
+/** Current pathname + search, WITHOUT the fragment. SSR-safe. */
+function baseUrl(): string {
+  if (typeof window === 'undefined') return '/';
+  const { pathname, search } = window.location;
+  return `${pathname}${search}`;
+}
+
+/**
+ * `useState`-style binding to the URL fragment. Returns `[hash, setHash]` where
+ * `hash` is the fragment without its leading `#` (`''` when absent).
+ *
+ * Writes go straight to the History API (never the router adapter) so the hash
+ * is set absolutely — see the module doc for why that matters under Next.js.
+ */
+export function useHashState(
+  options: UseHashStateOptions = {},
+): [string, (next: HashStateUpdater, opts?: UseHashStateOptions) => void] {
+  const value = useLocationProperty(
+    () => stripHash(window.location.hash),
+    () => '',
+  );
+
+  const setValue = useCallback(
+    (next: HashStateUpdater, callOpts?: UseHashStateOptions) => {
+      if (typeof window === 'undefined') return;
+
+      const current = stripHash(window.location.hash);
+      const resolved =
+        typeof next === 'function'
+          ? (next as (current: string) => string | null)(current)
+          : next;
+
+      const nextHash = stripHash(resolved ?? '');
+      if (nextHash === current) return; // no-op: don't churn history
+
+      const url = nextHash ? `${baseUrl()}#${nextHash}` : baseUrl();
+      const replace = callOpts?.replace ?? options.replace ?? false;
+
+      // Preserve any existing history.state (Next stores routing metadata there).
+      if (replace) {
+        window.history.replaceState(window.history.state, '', url);
+      } else {
+        window.history.pushState(window.history.state, '', url);
+      }
+    },
+    [options.replace],
+  );
+
+  return [value, setValue];
+}

package/src/styles/README.md

@@ -11,7 +11,7 @@ styles/
 ├── theme.css              # Imports tokens.css → animations → light → dark
 ├── base.css               # Resets + `*` border-color + body bg/color + radius scale + native focus-outline reset
 ├── utilities.css          # Custom utilities entry — imports utilities/*
-│   └── utilities/         # display · divider · controls · step · animations · glass · marquee
+│   └── utilities/         # display · divider · overlay · controls · step · animations · glass · marquee
 ├── sources.css            # @source directives for monorepo class detection
 ├── palette/               # JS-readable color access (Canvas/SVG/Mermaid)
 └── theme/
@@ -70,7 +70,7 @@ This makes opacity modifiers (`bg-card/40`, `border-foreground/20`) resolve thro
 | `bg-destructive` / `text-destructive-foreground` | `--destructive` | Error / delete filled controls |
 | `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-overlay` | `--overlay` | Modal scrim / backdrop behind dialogs, drawers, sheets — black scrim in both themes (the token owns the opacity), **plus** a `backdrop-filter` frost via `--overlay-blur` (`utilities/overlay.css` augments this same class) |
 | `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 |
 
@@ -273,6 +273,7 @@ Some classes are authored as **plain CSS** in `utilities/*.css` (not Tailwind ut
 | Class | File | Why plain CSS |
 |---|---|---|
 | `.divider-b` / `.divider-t` | `utilities/divider.css` | Hairline via `--divider` |
+| `.bg-overlay` (frost) | `utilities/overlay.css` | Adds `backdrop-filter: blur(var(--overlay-blur))` onto Tailwind's own `bg-overlay` so modal backdrops frost the page. Tune via `--overlay-blur` (base.css, default 2px; `0px` disables). Attached to `.bg-overlay` — not a new class — so overlays and host forks that render `bg-overlay` all get it |
 | `.rounded-control` | `utilities/controls.css` | Shared control radius |
 
 > **JIT-scan gotcha.** Tailwind's content scan covers `ui-core/src` but **not always every consumer package** (e.g. the `layouts` package source isn't always scanned by Storybook/apps). A *new* arbitrary Tailwind class used **only** in a consumer (`border-zinc-500/25`, `border-foreground/[0.12]`, `rounded-[var(--x)]`) then produces **no CSS rule** and silently falls back to the global `* { border-color: var(--border) }` — the class is in the DOM but the computed color is wrong. **Fix pattern:** for any token-driven visual that consumers need, add a plain `.class` in `ui-core/styles/utilities/*` and `@import` it, then use that class downstream. Don't invent new Tailwind classes in the `layouts` package.

package/src/styles/base.css

@@ -19,11 +19,11 @@
   --radius-dialog: 1rem;
   --radius-tooltip: 0.375rem;
 
-  /* Modal backdrop frosting — how hard the `.overlay-backdrop` (dialog / drawer
-   * / sheet scrim) blurs the page behind it. Theme-agnostic (same both modes);
+  /* Modal backdrop frosting — how hard the `.bg-overlay` scrim (dialog / drawer
+   * / 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. 8px = a light frost. */
-  --overlay-blur: 8px;
+   * the blur while keeping the `--overlay` dimming scrim. 2px = a subtle frost. */
+  --overlay-blur: 2px;
 
   /* Typography tokens — overridable per preset */
   --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;

package/src/styles/utilities/overlay.css

@@ -1,24 +1,24 @@
 /**
- * Modal backdrop utility — the scrim behind dialogs, drawers, sheets.
+ * Modal backdrop frosting — the blur behind dialogs, drawers, sheets.
  *
- * One class owns BOTH layers of a modal backdrop:
- *   1. the dimming scrim  → `--overlay` (a themed `hsl(… / α)` token)
- *   2. a light frosting    → `backdrop-filter: blur(var(--overlay-blur))`
+ * The dimming scrim is Tailwind's `bg-overlay` (`--overlay`, a themed
+ * `hsl(… / α)` token). Blur can't live in that color token (`--overlay` is a
+ * color, blur is a filter), so we attach `backdrop-filter` to the SAME
+ * `.bg-overlay` class every overlay already renders — no extra class, no
+ * component churn, and host forks of Dialog that render `bg-overlay` directly
+ * get the frost for free.
  *
- * Blur can't live in the color token (`--overlay` is a color, blur is a
- * filter), so it rides its own `--overlay-blur` variable — override it per
- * theme/preset to make the backdrop crisper or softer, or set it to `0` to
- * disable frosting entirely without touching the scrim color.
+ * Blur strength rides its own `--overlay-blur` variable (default in base.css) —
+ * override it per theme/preset to make the backdrop crisper or softer, or set
+ * it to `0px` to disable frosting entirely without touching the scrim color.
  *
- * Plain CSS class (NOT a JIT-scanned Tailwind utility) so it compiles
- * regardless of which package's source the Tailwind content scan covers —
- * same rationale as `divider.css`. Used by dialog / alert-dialog / drawer /
- * sheet overlays.
+ * Plain CSS (NOT a JIT-scanned Tailwind utility) so it compiles regardless of
+ * which package's source the Tailwind content scan covers — same rationale as
+ * `divider.css`.
  */
 
-.overlay-backdrop {
-  background-color: var(--overlay);
-  /* `--overlay-blur` defaults in base.css; a 0 value cleanly no-ops the blur. */
+.bg-overlay {
+  /* `--overlay-blur` defaults in base.css; a 0px value cleanly no-ops the blur. */
   backdrop-filter: blur(var(--overlay-blur, 0px));
   -webkit-backdrop-filter: blur(var(--overlay-blur, 0px));
 }