@djangocfg/ui-core 2.1.454 → 2.1.455

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.454",
+  "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.454",
+    "@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.454",
-    "@djangocfg/typescript-config": "^2.1.454",
+    "@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/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];
+}