@djangocfg/ui-core 2.1.293 → 2.1.297

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

package/src/hooks/router/useUrlBuilder.ts

@@ -0,0 +1,118 @@
+'use client';
+
+/**
+ * useUrlBuilder — pure URL/querystring assembly.
+ *
+ * WHY:
+ *   Building URLs by hand (template literals + URLSearchParams) is fiddly:
+ *   you have to remember to skip empty values, encode keys, handle arrays.
+ *   This hook centralizes those rules so callers stay declarative.
+ *   Zero side effects — only React-bound thing is `useCallback` for ref
+ *   stability inside JSX.
+ *
+ * @example
+ *   const { build, withCurrentParams } = useUrlBuilder();
+ *   build('/products', { page: 2, tag: ['a', 'b'], q: '' });
+ *   //   '/products?page=2&tag=a&tag=b'
+ *   withCurrentParams('/products', { page: 1 });
+ *   //   keeps everything in current ?…, overrides `page`
+ */
+
+import { useCallback, useMemo } from 'react';
+import { useLocation } from './useLocation';
+
+/** Value types accepted by `build`. Empty/null/undefined are stripped. */
+export type QueryValue = string | number | boolean | null | undefined;
+/** Param map. Arrays become repeated keys (`?tag=a&tag=b`), not csv. */
+export type QueryParamsInput = Record<string, QueryValue | QueryValue[]>;
+
+function appendValue(
+  params: URLSearchParams,
+  key: string,
+  value: QueryValue
+): void {
+  if (value === null || value === undefined) return;
+  if (typeof value === 'string' && value === '') return;
+  // Booleans serialize as 'true'/'false' — common-sense default.
+  params.append(key, String(value));
+}
+
+/**
+ * Build a query-string fragment (no leading `?`) from a param map.
+ * Skips empty / null / undefined values; arrays become repeated keys.
+ * Exported standalone so utilities can share the same rules without a hook.
+ */
+export function buildQueryString(params?: QueryParamsInput): string {
+  if (!params) return '';
+  const search = new URLSearchParams();
+  for (const key of Object.keys(params)) {
+    const value = params[key];
+    if (Array.isArray(value)) {
+      for (const item of value) appendValue(search, key, item);
+    } else {
+      appendValue(search, key, value);
+    }
+  }
+  return search.toString();
+}
+
+/**
+ * Build a full path: `path + '?' + qs` (or just `path` if qs is empty).
+ * Pure — useful outside React (link generators, server code).
+ */
+export function buildUrl(path: string, params?: QueryParamsInput): string {
+  const qs = buildQueryString(params);
+  return qs ? `${path}?${qs}` : path;
+}
+
+export interface UseUrlBuilderReturn {
+  /** Assemble `path` + serialized params. */
+  build: (path: string, params?: QueryParamsInput) => string;
+  /**
+   * Assemble `path` keeping the current page's querystring,
+   * with `overrides` merged on top. Pass `null`/`undefined`/`''` in
+   * `overrides` to drop a key.
+   */
+  withCurrentParams: (
+    path: string,
+    overrides?: QueryParamsInput
+  ) => string;
+}
+
+/**
+ * Stable URL builder helpers. `withCurrentParams` re-renders when the
+ * current querystring changes (it reads `useLocation` internally).
+ */
+export function useUrlBuilder(): UseUrlBuilderReturn {
+  const { search } = useLocation();
+
+  const build = useCallback((path: string, params?: QueryParamsInput): string => {
+    return buildUrl(path, params);
+  }, []);
+
+  const withCurrentParams = useCallback(
+    (path: string, overrides?: QueryParamsInput): string => {
+      const next = new URLSearchParams(search);
+      if (overrides) {
+        for (const key of Object.keys(overrides)) {
+          const value = overrides[key];
+          // Overrides semantics: drop on empty, replace otherwise.
+          next.delete(key);
+          if (Array.isArray(value)) {
+            for (const item of value) appendValue(next, key, item);
+          } else {
+            appendValue(next, key, value);
+          }
+        }
+      }
+      const qs = next.toString();
+      return qs ? `${path}?${qs}` : path;
+    },
+    [search]
+  );
+
+  return useMemo<UseUrlBuilderReturn>(
+    () => ({ build, withCurrentParams }),
+    [build, withCurrentParams]
+  );
+}

package/src/hooks/state/index.ts

@@ -0,0 +1,8 @@
+'use client';
+
+export { useDebounce } from './useDebounce';
+export { useDebouncedCallback } from './useDebouncedCallback';
+export { useLocalStorage } from './useLocalStorage';
+export { useSessionStorage } from './useSessionStorage';
+export { useStoredValue } from './useStoredValue';
+export type { UseStoredValueOptions, StorageType } from './useStoredValue';

package/src/hooks/theme/index.ts

@@ -0,0 +1,4 @@
+'use client';
+
+export { useResolvedTheme } from './useResolvedTheme';
+export type { ResolvedTheme } from './useResolvedTheme';

package/src/hooks/time/index.ts

@@ -0,0 +1,4 @@
+'use client';
+
+export { useCountdown, useCountdownFromSeconds } from './useCountdown';
+export type { CountdownState } from './useCountdown';

package/src/lib/dialog-service/dialogs/AlertDialogUI.tsx

@@ -11,7 +11,7 @@ import {
   AlertDialogHeader,
   AlertDialogTitle,
 } from '../../../components/overlay/alert-dialog';
-import { useHotkey } from '../../../hooks/useHotkey';
+import { useHotkey } from '../../../hooks';
 import { I18N_KEYS } from '../constants';
 import type { DialogOptions } from '../types';
 

package/src/lib/dialog-service/dialogs/ConfirmDialogUI.tsx

@@ -13,7 +13,7 @@ import {
   AlertDialogTitle,
 } from '../../../components/overlay/alert-dialog';
 import { buttonVariants } from '../../../components/forms/button';
-import { useHotkey } from '../../../hooks/useHotkey';
+import { useHotkey } from '../../../hooks';
 import { cn } from '../../utils';
 import { I18N_KEYS } from '../constants';
 import type { DialogOptions } from '../types';

package/src/lib/dialog-service/dialogs/PromptDialogUI.tsx

@@ -12,7 +12,7 @@ import {
 } from '../../../components/overlay/dialog';
 import { Button } from '../../../components/forms/button';
 import { Input } from '../../../components/forms/input';
-import { useHotkey } from '../../../hooks/useHotkey';
+import { useHotkey } from '../../../hooks';
 import { I18N_KEYS } from '../constants';
 import type { DialogOptions } from '../types';
 

package/src/styles/palette/useThemePalette.ts

@@ -15,7 +15,7 @@
  */
 
 import { useMemo } from 'react';
-import { useResolvedTheme } from '../../hooks/useResolvedTheme';
+import { useResolvedTheme } from '../../hooks';
 import { hslToHex } from './utils';
 import type { ThemePalette, StylePresets, BoxColors } from './types';