@djangocfg/ui-core 2.1.293 → 2.1.294

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

package/src/hooks/router/useRouter.ts

@@ -0,0 +1,81 @@
+'use client';
+
+/**
+ * useRouter — composite facade over the atomic router hooks.
+ *
+ * WHY:
+ *   For consumers who want a single import that "feels like" Next's
+ *   `useRouter`. Composes useLocation + useNavigate + useQueryParams +
+ *   useBackOrFallback + useUrlBuilder.
+ *
+ * NOTE on perf and tree-shaking:
+ *   This hook subscribes to EVERY URL change (location, search, depth)
+ *   because it composes hooks that subscribe to those things. If your
+ *   component only needs `navigate` (no location read), prefer the
+ *   atomic `useNavigate()` to avoid extra re-renders. Same for
+ *   `useQueryParams`, `useUrlBuilder`, etc. The atomic hooks also
+ *   tree-shake better — pulling in just `useNavigate` doesn't pay the
+ *   cost of the snapshot machinery.
+ *
+ * @example
+ *   const router = useRouter();
+ *   router.navigate('/users');
+ *   router.query.set({ page: 2 });
+ *   router.backOrFallback('/dashboard');
+ */
+
+import { useMemo } from 'react';
+import { useLocation, type LocationSnapshot } from './useLocation';
+import { useNavigate, type UseNavigateReturn } from './useNavigate';
+import { useQueryParams, type UseQueryParamsReturn } from './useQueryParams';
+import { useBackOrFallback } from './useBackOrFallback';
+import { useUrlBuilder, type UseUrlBuilderReturn } from './useUrlBuilder';
+
+export interface UseRouterReturn extends LocationSnapshot, UseNavigateReturn {
+  /** Same as `useQueryParams()`. */
+  query: UseQueryParamsReturn;
+  /** Same as `useUrlBuilder().build`. */
+  build: UseUrlBuilderReturn['build'];
+  /** Same as `useUrlBuilder().withCurrentParams`. */
+  withCurrentParams: UseUrlBuilderReturn['withCurrentParams'];
+  /** Same as `useBackOrFallback().back`. */
+  backOrFallback: (fallback?: string) => void;
+  /** Same as `useBackOrFallback().canGoBack`. */
+  canGoBack: boolean;
+}
+
+/**
+ * Convenience hook that exposes the full router surface.
+ * For minimal re-renders / smaller bundles, prefer the atomic hooks.
+ */
+export function useRouter(): UseRouterReturn {
+  const location = useLocation();
+  const nav = useNavigate();
+  const query = useQueryParams();
+  const builder = useUrlBuilder();
+  const { back: backOrFallback, canGoBack } = useBackOrFallback();
+
+  return useMemo<UseRouterReturn>(
+    () => ({
+      // Location snapshot
+      pathname: location.pathname,
+      search: location.search,
+      hash: location.hash,
+      href: location.href,
+      // Navigation pass-through
+      navigate: nav.navigate,
+      navigateExternal: nav.navigateExternal,
+      push: nav.push,
+      replace: nav.replace,
+      back: nav.back,
+      forward: nav.forward,
+      // Sub-APIs
+      query,
+      build: builder.build,
+      withCurrentParams: builder.withCurrentParams,
+      backOrFallback,
+      canGoBack,
+    }),
+    [location, nav, query, builder, backOrFallback, canGoBack]
+  );
+}

package/src/hooks/router/useSmartLink.ts

@@ -0,0 +1,157 @@
+'use client';
+
+/**
+ * useSmartLink — turn a non-`<a>` element (card, table row, list item)
+ * into a proper link.
+ *
+ * WHY:
+ *   "Clickable cards" used to either nest an `<a>` (which then can't
+ *   contain other interactive children) or attach `onClick={navigate}`
+ *   (which loses cmd-click, middle-click, keyboard, accessibility).
+ *   This hook returns a small bag of handlers that gives a non-anchor
+ *   element the right behavior in all those cases.
+ *
+ *   Key behaviors:
+ *     - Cmd/Ctrl+click and middle-click open in a new tab.
+ *     - Plain click does SPA nav.
+ *     - Enter / Space activate from keyboard.
+ *     - Clicks inside nested `<a>` / `<button>` are ignored (so the
+ *       inner element handles its own action).
+ *     - `role="link"` and `tabIndex={0}` for screen readers / keyboard.
+ *
+ * @example
+ *   const link = useSmartLink('/products/42');
+ *   <div {...link}>Product card</div>
+ */
+
+import { useCallback, useMemo, type KeyboardEvent, type MouseEvent } from 'react';
+import { useNavigate, type NavigateOptions } from './useNavigate';
+
+export interface UseSmartLinkOptions extends NavigateOptions {
+  /** Disable all navigation (e.g. while a row is being edited). */
+  disabled?: boolean;
+  /**
+   * If true, modifier-clicks (cmd/ctrl) and middle-clicks DON'T open
+   * a new tab — they're treated as plain clicks. Default: false.
+   */
+  ignoreModifiers?: boolean;
+}
+
+export interface SmartLinkHandlers {
+  onClick: (event: MouseEvent<HTMLElement>) => void;
+  onAuxClick: (event: MouseEvent<HTMLElement>) => void;
+  onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+  role: 'link';
+  /** -1 when disabled so the element is removed from the tab order. */
+  tabIndex: 0 | -1;
+  /** Forwarded to the consumer element so AT announces disabled state. */
+  'aria-disabled'?: true;
+}
+
+const INTERACTIVE_SELECTOR =
+  'a,button,input,textarea,select,label,[role="button"],[role="link"],[role="checkbox"],[role="switch"],[role="tab"],[role="menuitem"]';
+
+/**
+ * True if the click target is inside another interactive element
+ * nested within `currentTarget` — in which case we shouldn't intercept.
+ * Uses Element.closest for a single C-side traversal that also handles
+ * SVG/MathML, custom elements, and `:where()` semantics correctly.
+ */
+function isInsideNestedInteractive(event: MouseEvent<HTMLElement>): boolean {
+  const target = event.target as Element | null;
+  const current = event.currentTarget;
+  if (!target || target === current) return false;
+  const interactive = target.closest(INTERACTIVE_SELECTOR);
+  // Found an interactive ancestor strictly between target and currentTarget.
+  return !!interactive && interactive !== current && current.contains(interactive);
+}
+
+/** True if the user has selected text — don't navigate, they're reading. */
+function hasTextSelection(): boolean {
+  if (typeof window === 'undefined') return false;
+  const selection = window.getSelection();
+  return !!selection && selection.toString().length > 0;
+}
+
+/**
+ * Hook variant — gives an element link semantics with keyboard + new-tab support.
+ */
+export function useSmartLink(
+  href: string,
+  options?: UseSmartLinkOptions
+): SmartLinkHandlers {
+  const { navigate } = useNavigate();
+  const disabled = options?.disabled ?? false;
+  const ignoreModifiers = options?.ignoreModifiers ?? false;
+  const replace = options?.replace;
+  const scroll = options?.scroll;
+
+  const openInNewTab = useCallback((url: string) => {
+    if (typeof window === 'undefined') return;
+    window.open(url, '_blank', 'noopener,noreferrer');
+  }, []);
+
+  const onClick = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      if (disabled) return;
+      if (event.defaultPrevented) return;
+      if (isInsideNestedInteractive(event)) return;
+      if (hasTextSelection()) return;
+
+      // Modifier click → open in new tab. Don't preventDefault on a
+      // real <a>, but for div/span our default IS to navigate so we
+      // can branch freely.
+      if (
+        !ignoreModifiers &&
+        (event.metaKey || event.ctrlKey || event.shiftKey)
+      ) {
+        event.preventDefault();
+        openInNewTab(href);
+        return;
+      }
+
+      event.preventDefault();
+      navigate(href, { replace, scroll });
+    },
+    [disabled, ignoreModifiers, navigate, href, replace, scroll, openInNewTab]
+  );
+
+  const onAuxClick = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      if (disabled) return;
+      if (event.defaultPrevented) return;
+      if (isInsideNestedInteractive(event)) return;
+      // Middle-click only.
+      if (event.button !== 1) return;
+      if (ignoreModifiers) return;
+      event.preventDefault();
+      openInNewTab(href);
+    },
+    [disabled, ignoreModifiers, href, openInNewTab]
+  );
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      if (disabled) return;
+      // Only handle when the focused element IS the link container,
+      // otherwise we steal Enter from inputs etc.
+      if (event.target !== event.currentTarget) return;
+      if (event.key !== 'Enter' && event.key !== ' ') return;
+      event.preventDefault();
+      navigate(href, { replace, scroll });
+    },
+    [disabled, navigate, href, replace, scroll]
+  );
+
+  return useMemo<SmartLinkHandlers>(
+    () => ({
+      onClick,
+      onAuxClick,
+      onKeyDown,
+      role: 'link',
+      tabIndex: disabled ? -1 : 0,
+      ...(disabled ? { 'aria-disabled': true as const } : {}),
+    }),
+    [onClick, onAuxClick, onKeyDown, disabled]
+  );
+}