@djangocfg/ui-core 2.1.293 → 2.1.294

package/src/hooks/router/parsers.ts

@@ -0,0 +1,154 @@
+/**
+ * Query string parsers — typed marshalling between URL strings and JS values.
+ *
+ * WHY:
+ *   `URLSearchParams.get('page')` is always a string. Coercing it
+ *   inside every component (`Number(...) || 1`) is repetitive and
+ *   error-prone. A parser bakes in `parse(string) → T | null` and
+ *   `serialize(T) → string`, plus optional equality (so we can clear
+ *   default values from the URL — known as `clearOnDefault`).
+ *
+ *   Parsers are zero-runtime objects — pure functions in plain
+ *   structures. No deps, no validation libraries. If a consumer wants
+ *   zod / standard-schema, they wrap `parseAsJson` themselves.
+ *
+ * @example
+ *   import { useQueryState, parseAsInteger, parseAsString } from '@djangocfg/ui-core/hooks';
+ *   const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
+ *   const [q,    setQ]    = useQueryState('q',    parseAsString);
+ */
+
+/** Convert a URL string value into a typed value, or `null` on parse failure. */
+export interface QueryParser<T> {
+  parse: (value: string) => T | null;
+  serialize: (value: T) => string;
+  /** Equality check, used by `clearOnDefault` to strip default values from the URL. */
+  eq: (a: T, b: T) => boolean;
+  /** Optional default. When set, missing key returns it instead of `null`. */
+  defaultValue?: T;
+}
+
+/** Builder — adds `withDefault` chain on top of a parser. */
+export interface QueryParserBuilder<T> extends QueryParser<T> {
+  withDefault(value: T): QueryParser<T> & { defaultValue: T };
+}
+
+function builder<T>(parser: Omit<QueryParser<T>, 'eq'> & { eq?: QueryParser<T>['eq'] }): QueryParserBuilder<T> {
+  const eq = parser.eq ?? ((a, b) => a === b);
+  const base: QueryParser<T> = { ...parser, eq };
+  return {
+    ...base,
+    withDefault(defaultValue: T) {
+      return { ...base, defaultValue };
+    },
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Built-in parsers
+// ────────────────────────────────────────────────────────────────────
+
+export const parseAsString: QueryParserBuilder<string> = builder({
+  parse: (v) => v,
+  serialize: (v) => v,
+});
+
+export const parseAsInteger: QueryParserBuilder<number> = builder({
+  parse: (v) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : null;
+  },
+  serialize: (v) => String(v),
+});
+
+export const parseAsFloat: QueryParserBuilder<number> = builder({
+  parse: (v) => {
+    const n = Number.parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+  },
+  serialize: (v) => String(v),
+});
+
+export const parseAsBoolean: QueryParserBuilder<boolean> = builder({
+  // `?debug` (no value) → true, `?debug=true` → true, `?debug=false` → false.
+  parse: (v) => v === '' || v === 'true' || v === '1',
+  serialize: (v) => (v ? 'true' : 'false'),
+});
+
+export const parseAsIsoDate: QueryParserBuilder<Date> = builder({
+  parse: (v) => {
+    const ms = Date.parse(v);
+    return Number.isFinite(ms) ? new Date(ms) : null;
+  },
+  serialize: (v) => v.toISOString(),
+  eq: (a, b) => a.getTime() === b.getTime(),
+});
+
+/**
+ * `parseAsStringEnum(['asc','desc'])` — restricts values to a fixed list.
+ * Returns `null` on anything outside the set, so `withDefault` falls back.
+ */
+export function parseAsStringEnum<T extends string>(
+  values: readonly T[]
+): QueryParserBuilder<T> {
+  const set = new Set<string>(values);
+  return builder({
+    parse: (v) => (set.has(v) ? (v as T) : null),
+    serialize: (v) => v,
+  });
+}
+
+/**
+ * `parseAsArrayOf(parseAsInteger)` — comma-separated list of typed values.
+ * Empty array serializes to empty string (which `useQueryState` strips).
+ */
+export function parseAsArrayOf<T>(
+  itemParser: QueryParser<T>,
+  separator: string = ','
+): QueryParserBuilder<T[]> {
+  return builder({
+    parse: (v) => {
+      if (v === '') return [];
+      const parts = v.split(separator);
+      const out: T[] = [];
+      for (const part of parts) {
+        const parsed = itemParser.parse(part);
+        if (parsed === null) return null;
+        out.push(parsed);
+      }
+      return out;
+    },
+    serialize: (arr) => arr.map(itemParser.serialize).join(separator),
+    eq: (a, b) => {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        if (!itemParser.eq(a[i] as T, b[i] as T)) return false;
+      }
+      return true;
+    },
+  });
+}
+
+/**
+ * `parseAsJson<{ a: number }>()` — JSON-encode complex shapes.
+ * Pass a guard for runtime validation; without one any JSON-parsable
+ * value passes (TypeScript-only safety).
+ */
+export function parseAsJson<T>(
+  guard?: (value: unknown) => value is T
+): QueryParserBuilder<T> {
+  return builder({
+    parse: (v) => {
+      try {
+        const parsed = JSON.parse(v) as unknown;
+        if (guard && !guard(parsed)) return null;
+        return parsed as T;
+      } catch {
+        return null;
+      }
+    },
+    serialize: (value) => JSON.stringify(value),
+    // Identity by JSON shape — fine for small objects, expensive for big ones.
+    eq: (a, b) => JSON.stringify(a) === JSON.stringify(b),
+  });
+}

package/src/hooks/router/useBackOrFallback.ts

@@ -0,0 +1,145 @@
+'use client';
+
+/**
+ * useBackOrFallback — smart "go back" that doesn't escape the app.
+ *
+ * WHY:
+ *   `history.back()` on the first entry of a tab takes the user out of
+ *   the app (or does nothing in some browsers). For in-app Back buttons
+ *   we want: go back if there's in-app history, otherwise navigate to
+ *   a sensible fallback.
+ *
+ *   We track app-internal entries by stamping a monotonically growing
+ *   serial into `history.state` on every navigation. On click we compare
+ *   the current serial to the entry serial — if current > 0, there's
+ *   an earlier app entry to go back to. This is bullet-proof against
+ *   forward/back jitter (unlike a depth counter that can drift) and
+ *   against `replace`-style navigations (they preserve the serial).
+ *
+ * @example
+ *   const { back } = useBackOrFallback();
+ *   <button onClick={() => back('/dashboard')}>Back</button>
+ */
+
+import { useCallback, useEffect, useMemo } from 'react';
+import { useNavigate } from './useNavigate';
+import { NAVIGATE_EVENT } from './useLocation';
+
+const SERIAL_KEY = '__djcSerial';
+const COUNTER_KEY = '__djc_router_serial';
+
+interface SerialState {
+  [SERIAL_KEY]?: number;
+}
+
+function readCounter(): number {
+  if (typeof window === 'undefined') return 0;
+  try {
+    const raw = window.sessionStorage.getItem(COUNTER_KEY);
+    if (!raw) return 0;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeCounter(value: number): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.sessionStorage.setItem(COUNTER_KEY, String(Math.max(0, value)));
+  } catch {
+    // sessionStorage can throw in privacy modes — degrade silently.
+  }
+}
+
+function readEntrySerial(): number {
+  if (typeof window === 'undefined') return 0;
+  const state = window.history.state as SerialState | null;
+  return typeof state?.[SERIAL_KEY] === 'number' ? state[SERIAL_KEY] : 0;
+}
+
+function stampEntrySerial(value: number): void {
+  if (typeof window === 'undefined') return;
+  const current = (window.history.state ?? {}) as SerialState;
+  // Don't double-stamp the same entry — `djc:navigate` can fire twice
+  // if a custom adapter wraps push too.
+  if (current[SERIAL_KEY] === value) return;
+  try {
+    window.history.replaceState(
+      { ...current, [SERIAL_KEY]: value },
+      '',
+      window.location.href
+    );
+  } catch {
+    // Some sandboxes disallow replaceState — skip.
+  }
+}
+
+// Module-level guard: a single listener stamps every new app entry.
+let serialListenerAttached = false;
+
+function attachSerialListener(): void {
+  if (serialListenerAttached) return;
+  if (typeof window === 'undefined') return;
+  serialListenerAttached = true;
+
+  const onNavigate = () => {
+    // If the current entry already has a serial (e.g. `replace`), keep it.
+    // Otherwise stamp a fresh one and bump the counter.
+    if (readEntrySerial() > 0) return;
+    const next = readCounter() + 1;
+    writeCounter(next);
+    stampEntrySerial(next);
+  };
+
+  // Stamp the very first entry so popstate-only flows still work.
+  if (readEntrySerial() === 0) {
+    const next = readCounter() + 1;
+    writeCounter(next);
+    stampEntrySerial(next);
+  }
+
+  window.addEventListener(NAVIGATE_EVENT, onNavigate);
+}
+
+export interface UseBackOrFallbackReturn {
+  /**
+   * Go back if we have in-app history, otherwise navigate to `fallback`.
+   * @param fallback - Where to go when there's no app history. Defaults to `/`.
+   */
+  back: (fallback?: string) => void;
+  /** True when there's an earlier app entry to go back to. */
+  canGoBack: boolean;
+}
+
+/**
+ * Smart "back" that falls back to a route when the user landed
+ * directly on the current page (no in-app history).
+ */
+export function useBackOrFallback(): UseBackOrFallbackReturn {
+  const { back: adapterBack, navigate } = useNavigate();
+
+  useEffect(() => {
+    attachSerialListener();
+  }, []);
+
+  const back = useCallback(
+    (fallback: string = '/') => {
+      // Serial > 1 means at least one earlier app entry exists.
+      if (readEntrySerial() > 1) {
+        adapterBack();
+      } else {
+        navigate(fallback, { replace: true });
+      }
+    },
+    [adapterBack, navigate]
+  );
+
+  // Snapshot once per render — back/forward changes the serial on the
+  // entry we're sitting on, so we'll get a fresh value next render
+  // anyway via React's normal re-render cycle.
+  const canGoBack = readEntrySerial() > 1;
+
+  return useMemo(() => ({ back, canGoBack }), [back, canGoBack]);
+}

package/src/hooks/router/useIsActive.ts

@@ -0,0 +1,60 @@
+'use client';
+
+/**
+ * useIsActive — boolean for "current pathname matches this href".
+ *
+ * WHY:
+ *   Highlighting the active item in a navbar / sidebar is the most-copy-
+ *   pasted snippet in any SPA: `pathname === href || pathname.startsWith(href + '/')`.
+ *   This hook bakes in the right semantics (exact-vs-prefix, trailing-slash
+ *   tolerance, query/hash ignoring) so consumers don't have to reinvent them.
+ *
+ * @example
+ *   const isActive = useIsActive('/dashboard');
+ *   const isProductsActive = useIsActive('/products', { exact: false });
+ *   <Link className={isActive ? 'active' : ''}>...</Link>
+ */
+
+import { useMemo } from 'react';
+import { useLocation } from './useLocation';
+
+export interface UseIsActiveOptions {
+  /**
+   * `true` (default) — match only when pathname === href.
+   * `false` — match when pathname is href OR a sub-path (`href/...`).
+   * Most navbar items want `false`; tab strips usually want `true`.
+   */
+  exact?: boolean;
+  /**
+   * Strip a trailing slash from both sides before comparing.
+   * Default: true.
+   */
+  ignoreTrailingSlash?: boolean;
+}
+
+function normalize(path: string, ignoreTrailingSlash: boolean): string {
+  if (!ignoreTrailingSlash) return path;
+  if (path.length > 1 && path.endsWith('/')) return path.slice(0, -1);
+  return path;
+}
+
+/**
+ * Returns `true` if `href` matches the current pathname.
+ * Pure path-based — search and hash are ignored.
+ */
+export function useIsActive(href: string, options?: UseIsActiveOptions): boolean {
+  const { pathname } = useLocation();
+  const exact = options?.exact ?? false;
+  const ignoreTrailingSlash = options?.ignoreTrailingSlash ?? true;
+
+  return useMemo(() => {
+    // Strip search/hash from href if the consumer passed a full URL.
+    const cleanHref = href.split('?')[0]?.split('#')[0] ?? href;
+    const a = normalize(pathname, ignoreTrailingSlash);
+    const b = normalize(cleanHref, ignoreTrailingSlash);
+    if (a === b) return true;
+    if (exact) return false;
+    // Sub-path match: prefix + boundary so `/foobar` doesn't match `/foo`.
+    return a.startsWith(b + '/');
+  }, [pathname, href, exact, ignoreTrailingSlash]);
+}

package/src/hooks/router/useLocation.ts

@@ -0,0 +1,163 @@
+'use client';
+
+/**
+ * useLocation — reactive snapshot of `window.location`.
+ *
+ * WHY:
+ *   Native `popstate` only fires on back/forward, NOT on `pushState` /
+ *   `replaceState`. To make SPA navigations observable we monkey-patch
+ *   those two methods once (idempotent) and dispatch a custom
+ *   `djc:navigate` event after each call. All router hooks, the default
+ *   adapter, and any code that calls history.* APIs anywhere in the page
+ *   will trigger this event automatically.
+ *
+ *   We use `useSyncExternalStore` because that is the React-19-blessed
+ *   way to bridge external mutable state (window.location) into React's
+ *   render model — it gets concurrent-render and SSR right (via
+ *   getServerSnapshot).
+ *
+ * @example
+ *   const { pathname, search, hash, href } = useLocation();
+ *   useEffect(() => { analytics.page(pathname); }, [pathname]);
+ */
+
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Browser-event name we dispatch when pushState/replaceState run.
+ * `pushState` and `replaceState` events fire alongside this for consumers
+ * that want to distinguish between the two history operations (wouter
+ * uses the same convention: separate per-method events PLUS a generic one).
+ */
+export const NAVIGATE_EVENT = 'djc:navigate';
+export const PUSH_STATE_EVENT = 'pushState';
+export const REPLACE_STATE_EVENT = 'replaceState';
+
+/** Frozen snapshot returned to React. Identity changes only on URL change. */
+export interface LocationSnapshot {
+  pathname: string;
+  search: string;
+  hash: string;
+  href: string;
+}
+
+const SSR_SNAPSHOT: LocationSnapshot = Object.freeze({
+  pathname: '/',
+  search: '',
+  hash: '',
+  href: '/',
+});
+
+// Patch-once guard via a Symbol on `window`. We use a Symbol-on-window
+// (wouter's pattern) instead of tagging the function because it survives
+// other libraries re-patching the methods on top of us — once anybody
+// (us or them) has installed a patch, the marker stays until full reload.
+const PATCH_KEY = Symbol.for('djc.router.historyPatched');
+
+function patchHistoryOnce(): void {
+  if (typeof window === 'undefined') return;
+  const w = window as Window & { [PATCH_KEY]?: true };
+  if (w[PATCH_KEY]) return;
+
+  const originalPush = window.history.pushState.bind(window.history);
+  const originalReplace = window.history.replaceState.bind(window.history);
+
+  window.history.pushState = function patchedPushState(
+    ...args: Parameters<History['pushState']>
+  ) {
+    const result = originalPush(...args);
+    // Two events: the per-method one (consumers can listen narrowly)
+    // and a generic NAVIGATE_EVENT for "any url change" subscribers.
+    window.dispatchEvent(new Event(PUSH_STATE_EVENT));
+    window.dispatchEvent(new Event(NAVIGATE_EVENT));
+    return result;
+  };
+
+  window.history.replaceState = function patchedReplaceState(
+    ...args: Parameters<History['replaceState']>
+  ) {
+    const result = originalReplace(...args);
+    window.dispatchEvent(new Event(REPLACE_STATE_EVENT));
+    window.dispatchEvent(new Event(NAVIGATE_EVENT));
+    return result;
+  };
+
+  Object.defineProperty(w, PATCH_KEY, { value: true });
+}
+
+// Cache the snapshot so getSnapshot returns the same reference between
+// notifications. useSyncExternalStore demands referential stability between
+// reads — recomputing the object on every call would loop in React 18+.
+let cachedSnapshot: LocationSnapshot = SSR_SNAPSHOT;
+
+function readLocation(): LocationSnapshot {
+  if (typeof window === 'undefined') return SSR_SNAPSHOT;
+  const { pathname, search, hash, href } = window.location;
+  // Only mint a new object if something actually changed.
+  if (
+    cachedSnapshot.pathname === pathname &&
+    cachedSnapshot.search === search &&
+    cachedSnapshot.hash === hash &&
+    cachedSnapshot.href === href
+  ) {
+    return cachedSnapshot;
+  }
+  cachedSnapshot = Object.freeze({ pathname, search, hash, href });
+  return cachedSnapshot;
+}
+
+function subscribe(onChange: () => void): () => void {
+  if (typeof window === 'undefined') return () => {};
+  patchHistoryOnce();
+  // Wrap the callback so both popstate and our custom event refresh
+  // the cached snapshot before React re-reads it.
+  const handler = () => {
+    // Force re-read on next getSnapshot call by resetting the cache.
+    // We intentionally don't read here — getSnapshot will compare and
+    // return a stable ref if nothing changed (e.g. duplicate events).
+    onChange();
+  };
+  window.addEventListener('popstate', handler);
+  window.addEventListener(NAVIGATE_EVENT, handler);
+  // hashchange covers programmatic location.hash assignments that bypass
+  // pushState. Cheap to subscribe to.
+  window.addEventListener('hashchange', handler);
+  return () => {
+    window.removeEventListener('popstate', handler);
+    window.removeEventListener(NAVIGATE_EVENT, handler);
+    window.removeEventListener('hashchange', handler);
+  };
+}
+
+function getServerSnapshot(): LocationSnapshot {
+  return SSR_SNAPSHOT;
+}
+
+/**
+ * Reactive snapshot of the current URL.
+ * Re-renders the calling component on every history navigation
+ * (pushState / replaceState / back / forward / hashchange).
+ *
+ * If you only need ONE field (e.g. just pathname), prefer
+ * `useLocationProperty(() => location.pathname)` — it subscribes to
+ * the same store but lets React skip re-renders when other fields
+ * change. Same pattern as `wouter`'s `usePathname` / `useSearch`.
+ */
+export function useLocation(): LocationSnapshot {
+  return useSyncExternalStore(subscribe, readLocation, getServerSnapshot);
+}
+
+/**
+ * Subscribe to one derived value from `window.location`. React only
+ * re-renders when the returned value changes — so a component reading
+ * just `pathname` won't re-render on `?page=2` updates.
+ *
+ * @example
+ *   const pathname = useLocationProperty(() => window.location.pathname, () => '/');
+ */
+export function useLocationProperty<T>(
+  getValue: () => T,
+  getServerValue: () => T
+): T {
+  return useSyncExternalStore(subscribe, getValue, getServerValue);
+}

package/src/hooks/router/useNavigate.ts

@@ -0,0 +1,96 @@
+'use client';
+
+/**
+ * useNavigate — programmatic navigation primitive.
+ *
+ * WHY:
+ *   Wraps the active adapter's push/replace and adds the small ergonomics
+ *   we want on every nav: optional scroll-to-top, replace flag, and a
+ *   distinct `navigateExternal` for full-reload flows (logout, OAuth,
+ *   cross-origin redirects) where SPA navigation would be wrong.
+ *
+ *   No `useTransition` here — that's a Next/React-internal concern; if
+ *   the consumer wants pending state they wrap our calls themselves.
+ *
+ * @example
+ *   const { navigate, navigateExternal } = useNavigate();
+ *   navigate('/dashboard');
+ *   navigate('/dashboard', { replace: true, scroll: false });
+ *   navigateExternal('/api/auth/logout');
+ */
+
+import { useCallback, useMemo } from 'react';
+import { useRouterAdapter } from './adapter';
+
+export interface NavigateOptions {
+  /** Use `replaceState` instead of `pushState`. Default: false. */
+  replace?: boolean;
+  /**
+   * Scroll to top after navigation. Default: false.
+   *
+   * Most SPA flows (filter/pagination/tab switches) shouldn't jump,
+   * which is why this is opt-in. Pass `true` for top-level page
+   * transitions where you want the user back at the masthead.
+   */
+  scroll?: boolean;
+}
+
+export interface UseNavigateReturn {
+  /**
+   * SPA navigation through the active adapter.
+   * Default: pushState + scroll to top.
+   */
+  navigate: (href: string, opts?: NavigateOptions) => void;
+  /**
+   * Hard navigation via `window.location.assign` — full page reload.
+   * Use for logout, OAuth, or any cross-origin handoff.
+   */
+  navigateExternal: (href: string) => void;
+  /** Pass-through: adapter.push */
+  push: (url: string) => void;
+  /** Pass-through: adapter.replace */
+  replace: (url: string) => void;
+  /** Pass-through: adapter.back */
+  back: () => void;
+  /** Pass-through: adapter.forward */
+  forward: () => void;
+}
+
+/**
+ * Returns stable navigation functions backed by the active router adapter.
+ * Safe to put returned functions in deps arrays.
+ */
+export function useNavigate(): UseNavigateReturn {
+  const adapter = useRouterAdapter();
+
+  const navigate = useCallback(
+    (href: string, opts?: NavigateOptions) => {
+      const replace = opts?.replace ?? false;
+      const scroll = opts?.scroll ?? false;
+      if (replace) {
+        adapter.replace(href);
+      } else {
+        adapter.push(href);
+      }
+      if (scroll && typeof window !== 'undefined') {
+        window.scrollTo(0, 0);
+      }
+    },
+    [adapter]
+  );
+
+  const navigateExternal = useCallback((href: string) => {
+    if (typeof window === 'undefined') return;
+    window.location.assign(href);
+  }, []);
+
+  const push = useCallback((url: string) => adapter.push(url), [adapter]);
+  const replace = useCallback((url: string) => adapter.replace(url), [adapter]);
+  const back = useCallback(() => adapter.back(), [adapter]);
+  const forward = useCallback(() => adapter.forward(), [adapter]);
+
+  return useMemo<UseNavigateReturn>(
+    () => ({ navigate, navigateExternal, push, replace, back, forward }),
+    [navigate, navigateExternal, push, replace, back, forward]
+  );
+}