@djangocfg/ui-core 2.1.293 → 2.1.297

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]
+  );
+}

package/src/hooks/router/useQueryParams.ts

@@ -0,0 +1,262 @@
+'use client';
+
+/**
+ * useQueryParams — read & write `?key=value` URL state.
+ *
+ * WHY:
+ *   Pagination, filters, sort, search-as-you-type all live in the URL.
+ *   This hook gives a typed, ergonomic surface (get/getNumber/getBoolean,
+ *   set with merge semantics, remove, clear) so consumers don't reinvent
+ *   URLSearchParams plumbing in every component.
+ *
+ * @example
+ *   const { params, get, set, remove } = useQueryParams();
+ *   const page = get('page', '1');
+ *   set({ page: 2, sort: 'asc' });            // merges
+ *   set({ q: 'foo' }, { reset: true });       // drops everything else
+ *   set({ q: 'foo' }, { preserve: ['tab'] }); // keeps only `tab`
+ *   remove(['page', 'sort']);
+ */
+
+import { useCallback, useMemo } from 'react';
+import { useLocation } from './useLocation';
+import { useNavigate } from './useNavigate';
+
+/** Snapshot of current params. Single value = string, repeated key = string[]. */
+export type QueryParamsSnapshot = Record<string, string | string[]>;
+
+/** Value type accepted by `set`. Empty/null/undefined ⇒ delete the key. */
+export type QueryParamValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Array<string | number | boolean>;
+
+export interface QueryParamUpdates {
+  [key: string]: QueryParamValue;
+}
+
+export interface SetQueryParamsOptions {
+  /** Use `replaceState` instead of `pushState`. Default: false. */
+  replace?: boolean;
+  /**
+   * Drop ALL existing params before applying updates.
+   * Useful when filters change and pagination should reset.
+   */
+  reset?: boolean;
+  /**
+   * If `reset` is true, keep these keys from the current URL.
+   * Ignored when `reset` is false.
+   */
+  preserve?: string[];
+  /** Scroll to top after navigation. Default: false (filters/pagination shouldn't jump). */
+  scroll?: boolean;
+}
+
+function snapshotFromSearch(search: string): QueryParamsSnapshot {
+  const out: QueryParamsSnapshot = {};
+  if (!search) return out;
+  const params = new URLSearchParams(search);
+  // Build with multi-value awareness.
+  for (const key of new Set(params.keys())) {
+    const all = params.getAll(key);
+    out[key] = all.length > 1 ? all : (all[0] ?? '');
+  }
+  return out;
+}
+
+function applyUpdates(
+  target: URLSearchParams,
+  updates: QueryParamUpdates
+): void {
+  for (const key of Object.keys(updates)) {
+    const value = updates[key];
+    target.delete(key);
+    if (value === null || value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === '' || item === null || item === undefined) continue;
+        target.append(key, String(item));
+      }
+      continue;
+    }
+    if (typeof value === 'string' && value === '') continue;
+    target.append(key, String(value));
+  }
+}
+
+export interface UseQueryParamsReturn {
+  /** Current params snapshot. Identity changes only on querystring change. */
+  params: QueryParamsSnapshot;
+
+  /**
+   * Read a single value (first one if repeated).
+   * Returns `fallback` (or `undefined`) when the key is missing.
+   */
+  get: <T extends string = string>(key: string, fallback?: T) => T | undefined;
+
+  /** Read all values for a repeated key. Empty array if missing. */
+  getAll: (key: string) => string[];
+
+  /**
+   * Read & coerce to number. Returns fallback (or `undefined`) when
+   * missing or unparseable. NaN is treated as missing.
+   */
+  getNumber: (key: string, fallback?: number) => number | undefined;
+
+  /**
+   * Read & coerce to boolean. `'true'` / `'1'` / `''` (key present, no value)
+   * → true. Anything else → false. Returns fallback when key missing.
+   */
+  getBoolean: (key: string, fallback?: boolean) => boolean | undefined;
+
+  /** Merge updates into current params and navigate. */
+  set: (updates: QueryParamUpdates, opts?: SetQueryParamsOptions) => void;
+
+  /** Drop one or more keys and navigate. */
+  remove: (keys: string | string[], opts?: SetQueryParamsOptions) => void;
+
+  /** Drop all params and navigate. */
+  clear: (opts?: SetQueryParamsOptions) => void;
+
+  /** Current querystring without leading `?`. */
+  toString: () => string;
+
+  /** Build `path?currentSearch` for use in `<a href={...}>`. */
+  toUrl: (path: string) => string;
+}
+
+/**
+ * Reactive read + ergonomic write for `?key=value` URL state.
+ * Re-renders only when the search string changes.
+ */
+export function useQueryParams(): UseQueryParamsReturn {
+  const { pathname, search } = useLocation();
+  const { navigate } = useNavigate();
+
+  // Snapshot is rebuilt only when `search` changes — useMemo is enough.
+  const params = useMemo(() => snapshotFromSearch(search), [search]);
+
+  const get = useCallback(
+    <T extends string = string>(key: string, fallback?: T): T | undefined => {
+      const value = params[key];
+      if (value === undefined) return fallback;
+      const first = Array.isArray(value) ? value[0] : value;
+      if (first === undefined || first === '') return fallback;
+      return first as T;
+    },
+    [params]
+  );
+
+  const getAll = useCallback(
+    (key: string): string[] => {
+      const value = params[key];
+      if (value === undefined) return [];
+      return Array.isArray(value) ? value : [value];
+    },
+    [params]
+  );
+
+  const getNumber = useCallback(
+    (key: string, fallback?: number): number | undefined => {
+      const raw = get(key);
+      if (raw === undefined) return fallback;
+      const num = Number(raw);
+      return Number.isFinite(num) ? num : fallback;
+    },
+    [get]
+  );
+
+  const getBoolean = useCallback(
+    (key: string, fallback?: boolean): boolean | undefined => {
+      const raw = get(key);
+      if (raw === undefined) return fallback;
+      // '' means key was present without a value (e.g. ?debug)
+      // — treat as truthy. Match URLSearchParams behavior.
+      if (raw === '' || raw === 'true' || raw === '1') return true;
+      return false;
+    },
+    [get]
+  );
+
+  const navigateWithSearch = useCallback(
+    (next: URLSearchParams, opts?: SetQueryParamsOptions) => {
+      const qs = next.toString();
+      const href = qs ? `${pathname}?${qs}` : pathname;
+      navigate(href, {
+        replace: opts?.replace ?? false,
+        scroll: opts?.scroll ?? false,
+      });
+    },
+    [pathname, navigate]
+  );
+
+  const set = useCallback(
+    (updates: QueryParamUpdates, opts?: SetQueryParamsOptions) => {
+      let next: URLSearchParams;
+      if (opts?.reset) {
+        next = new URLSearchParams();
+        if (opts.preserve && opts.preserve.length > 0) {
+          const current = new URLSearchParams(search);
+          for (const key of opts.preserve) {
+            const all = current.getAll(key);
+            for (const item of all) next.append(key, item);
+          }
+        }
+      } else {
+        next = new URLSearchParams(search);
+      }
+      applyUpdates(next, updates);
+      navigateWithSearch(next, opts);
+    },
+    [search, navigateWithSearch]
+  );
+
+  const remove = useCallback(
+    (keys: string | string[], opts?: SetQueryParamsOptions) => {
+      const next = new URLSearchParams(search);
+      const list = Array.isArray(keys) ? keys : [keys];
+      for (const key of list) next.delete(key);
+      navigateWithSearch(next, opts);
+    },
+    [search, navigateWithSearch]
+  );
+
+  const clear = useCallback(
+    (opts?: SetQueryParamsOptions) => {
+      navigateWithSearch(new URLSearchParams(), opts);
+    },
+    [navigateWithSearch]
+  );
+
+  const toString = useCallback((): string => {
+    // search includes the leading '?', strip it.
+    return search.startsWith('?') ? search.slice(1) : search;
+  }, [search]);
+
+  const toUrl = useCallback(
+    (path: string): string => {
+      const qs = toString();
+      return qs ? `${path}?${qs}` : path;
+    },
+    [toString]
+  );
+
+  return useMemo<UseQueryParamsReturn>(
+    () => ({
+      params,
+      get,
+      getAll,
+      getNumber,
+      getBoolean,
+      set,
+      remove,
+      clear,
+      toString,
+      toUrl,
+    }),
+    [params, get, getAll, getNumber, getBoolean, set, remove, clear, toString, toUrl]
+  );
+}

package/src/hooks/router/useQueryState.ts

@@ -0,0 +1,106 @@
+'use client';
+
+/**
+ * useQueryState — typed `useState`-style hook backed by ONE URL query key.
+ *
+ * WHY:
+ *   `useQueryParams().get('page')` works, but you re-coerce to number
+ *   in every component. `useQueryState('page', parseAsInteger.withDefault(1))`
+ *   gives you `[number, setter]` directly, like `useState`. Setting to
+ *   the parser's default value clears the key from the URL (no `?page=1`
+ *   noise) — toggle off via `clearOnDefault: false`.
+ *
+ *   Inspired by nuqs (47ng/nuqs) but framework-agnostic via our adapter.
+ *
+ * @example
+ *   const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
+ *   const [tab, setTab]   = useQueryState('tab',  parseAsStringEnum(['a','b']).withDefault('a'));
+ *   setPage((p) => p + 1);   // functional updater
+ *   setPage(null);           // clear the key
+ */
+
+import { useCallback, useMemo } from 'react';
+import { useLocation } from './useLocation';
+import { useNavigate } from './useNavigate';
+import type { QueryParser } from './parsers';
+
+export interface UseQueryStateOptions {
+  /** Use `replaceState` instead of `pushState`. Default: false. */
+  replace?: boolean;
+  /** Scroll to top after navigation. Default: false. */
+  scroll?: boolean;
+  /**
+   * When the new value equals the parser's default, drop the key from
+   * the URL instead of writing `?page=1`. Default: true (recommended —
+   * keeps URLs clean). Set false if your URLs are linked / bookmarked
+   * and you need explicit values.
+   */
+  clearOnDefault?: boolean;
+}
+
+export type QueryStateUpdater<T> = T | null | ((current: T) => T | null);
+
+// Two overloads so the return type narrows on `defaultValue`.
+export function useQueryState<T>(
+  key: string,
+  parser: QueryParser<T> & { defaultValue: T },
+  options?: UseQueryStateOptions
+): [T, (next: QueryStateUpdater<T>, opts?: UseQueryStateOptions) => void];
+
+export function useQueryState<T>(
+  key: string,
+  parser: QueryParser<T>,
+  options?: UseQueryStateOptions
+): [T | null, (next: QueryStateUpdater<T>, opts?: UseQueryStateOptions) => void];
+
+export function useQueryState<T>(
+  key: string,
+  parser: QueryParser<T>,
+  options?: UseQueryStateOptions
+): [T | null, (next: QueryStateUpdater<T>, opts?: UseQueryStateOptions) => void] {
+  const { pathname, search } = useLocation();
+  const { navigate } = useNavigate();
+
+  const value = useMemo<T | null>(() => {
+    const raw = new URLSearchParams(search).get(key);
+    if (raw === null) return parser.defaultValue ?? null;
+    const parsed = parser.parse(raw);
+    return parsed === null ? (parser.defaultValue ?? null) : parsed;
+  }, [search, key, parser]);
+
+  const setValue = useCallback(
+    (next: QueryStateUpdater<T>, callOpts?: UseQueryStateOptions) => {
+      const resolved =
+        typeof next === 'function'
+          ? (next as (current: T) => T | null)(
+              (value ?? parser.defaultValue) as T
+            )
+          : next;
+
+      const params = new URLSearchParams(search);
+      const clearOnDefault =
+        callOpts?.clearOnDefault ?? options?.clearOnDefault ?? true;
+
+      if (
+        resolved === null ||
+        (clearOnDefault &&
+          parser.defaultValue !== undefined &&
+          parser.eq(resolved as T, parser.defaultValue))
+      ) {
+        params.delete(key);
+      } else {
+        params.set(key, parser.serialize(resolved as T));
+      }
+
+      const qs = params.toString();
+      const href = qs ? `${pathname}?${qs}` : pathname;
+      navigate(href, {
+        replace: callOpts?.replace ?? options?.replace ?? false,
+        scroll: callOpts?.scroll ?? options?.scroll ?? false,
+      });
+    },
+    [pathname, search, key, parser, navigate, options, value]
+  );
+
+  return [value, setValue];
+}