@djangocfg/ui-core 2.1.293 → 2.1.297

package/src/hooks/router/adapter.tsx

@@ -0,0 +1,139 @@
+'use client';
+
+/**
+ * Router adapter — pluggable navigation backend.
+ *
+ * WHY:
+ *   `@djangocfg/ui-core` is framework-agnostic, but consumers using Next.js,
+ *   TanStack Router, wouter, etc. need SPA navigations to flow through their
+ *   own router so server components / data loaders / route guards fire
+ *   correctly. The adapter pattern lets the consumer swap the implementation
+ *   without changing call-sites inside library components.
+ *
+ * Default behavior uses `window.history.pushState` + `window.location` (works
+ * in any browser, zero deps). When no provider is mounted, the default is
+ * silently used.
+ *
+ * @example
+ * // In a Next.js app:
+ * import { useRouter as useNextRouter } from 'next/navigation';
+ * import { RouterAdapterProvider } from '@djangocfg/ui-core/hooks';
+ *
+ * function NextAdapter({ children }: { children: React.ReactNode }) {
+ *   const next = useNextRouter();
+ *   const adapter = useMemo(() => ({
+ *     push: (url: string) => next.push(url),
+ *     replace: (url: string) => next.replace(url),
+ *     back: () => next.back(),
+ *     forward: () => next.forward(),
+ *     getLocation: () => ({
+ *       pathname: window.location.pathname,
+ *       search: window.location.search,
+ *       hash: window.location.hash,
+ *     }),
+ *   }), [next]);
+ *   return <RouterAdapterProvider value={adapter}>{children}</RouterAdapterProvider>;
+ * }
+ */
+
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+
+/**
+ * Snapshot of the current URL location.
+ * Mirrors the parts of `window.location` we actually use.
+ */
+export interface RouterLocation {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+/**
+ * Pluggable navigation backend. Implementations must be SSR-safe
+ * (mutations should no-op when `typeof window === 'undefined'`).
+ */
+export interface RouterAdapter {
+  /** Push a new entry onto the history stack. */
+  push: (url: string) => void;
+  /** Replace the current history entry. */
+  replace: (url: string) => void;
+  /** Go back one entry. */
+  back: () => void;
+  /** Go forward one entry. */
+  forward: () => void;
+  /** Read the current location (synchronous). */
+  getLocation: () => RouterLocation;
+}
+
+const SSR_LOCATION: RouterLocation = Object.freeze({
+  pathname: '/',
+  search: '',
+  hash: '',
+});
+
+/**
+ * Default adapter — uses History API + window.location.
+ * No-ops on the server. Triggers our internal `djc:navigate` event so
+ * `useLocation` reflects the change (see `useLocation.ts`).
+ */
+export const defaultAdapter: RouterAdapter = Object.freeze({
+  push(url: string) {
+    if (typeof window === 'undefined') return;
+    window.history.pushState(null, '', url);
+  },
+  replace(url: string) {
+    if (typeof window === 'undefined') return;
+    window.history.replaceState(null, '', url);
+  },
+  back() {
+    if (typeof window === 'undefined') return;
+    window.history.back();
+  },
+  forward() {
+    if (typeof window === 'undefined') return;
+    window.history.forward();
+  },
+  getLocation(): RouterLocation {
+    if (typeof window === 'undefined') return SSR_LOCATION;
+    return {
+      pathname: window.location.pathname,
+      search: window.location.search,
+      hash: window.location.hash,
+    };
+  },
+});
+
+/**
+ * React context carrying the active adapter. `null` means "use default".
+ * Kept intentionally nullable so we don't burn a Provider for the default case.
+ */
+export const RouterAdapterContext = createContext<RouterAdapter | null>(null);
+
+export interface RouterAdapterProviderProps {
+  /** Adapter implementation. Will be used by every router hook in subtree. */
+  value: RouterAdapter;
+  children: ReactNode;
+}
+
+/**
+ * Wrap a subtree to override the navigation backend used by router hooks.
+ */
+export function RouterAdapterProvider({ value, children }: RouterAdapterProviderProps) {
+  // Memoizing here is the consumer's job (the value usually comes from another hook).
+  // We don't double-memo — that just adds noise.
+  return (
+    <RouterAdapterContext.Provider value={value}>
+      {children}
+    </RouterAdapterContext.Provider>
+  );
+}
+
+/**
+ * Read the active router adapter. Returns the default History API adapter
+ * if no provider is mounted.
+ */
+export function useRouterAdapter(): RouterAdapter {
+  const ctx = useContext(RouterAdapterContext);
+  // useMemo so consumers can put the returned value in deps without churn.
+  return useMemo(() => ctx ?? defaultAdapter, [ctx]);
+}

package/src/hooks/router/adapters/index.ts

@@ -0,0 +1,5 @@
+// Adapters live behind sub-path imports so framework-specific peer
+// deps (next, react-router, etc.) load only when the consumer asks
+// for them. Do NOT re-export adapters from the package barrel — that
+// would force every consumer to resolve all peer deps.
+export type {} from '../adapter';

package/src/hooks/router/adapters/nextjs.tsx

@@ -0,0 +1,140 @@
+'use client';
+
+/**
+ * Next.js adapter — bridges our framework-agnostic router hooks
+ * to `next/navigation` so server components, route loaders, and
+ * `prefetch` all fire correctly.
+ *
+ * USAGE:
+ *   Mount once near the root of the App Router tree, e.g. inside
+ *   the locale layout's client provider stack:
+ *
+ *   ```tsx
+ *   import { NextRouterAdapter } from '@djangocfg/ui-core/adapters/nextjs';
+ *
+ *   <I18nProvider locale={locale} messages={messages}>
+ *     <NextRouterAdapter>
+ *       <AppLayout>{children}</AppLayout>
+ *     </NextRouterAdapter>
+ *   </I18nProvider>
+ *   ```
+ *
+ *   Without this provider, our hooks fall back to the History API
+ *   adapter — which works in plain SPAs (Wails, Electron, Vite, CRA)
+ *   but in Next.js means: no server component refetch on navigation,
+ *   no route loader, no prefetch. So always mount it in Next apps.
+ *
+ * PEER DEPENDENCY:
+ *   `next` is an OPTIONAL peer of @djangocfg/ui-core. The base package
+ *   never imports from `next/*`. This sub-path entry does — so it only
+ *   loads when the consumer explicitly imports `/adapters/nextjs`.
+ *   Wails / Electron consumers: don't import this file and `next` is
+ *   never resolved.
+ */
+
+import { forwardRef, useMemo, type ReactNode } from 'react';
+import { useRouter as useNextRouter } from 'next/navigation';
+import NextLink from 'next/link';
+
+import {
+  RouterAdapterProvider,
+  type RouterAdapter,
+  type RouterLocation,
+} from '../adapter';
+import {
+  LinkProvider,
+  type LinkComponent,
+  type LinkComponentProps,
+} from '../../../components/navigation/link';
+
+const SSR_LOCATION: RouterLocation = Object.freeze({
+  pathname: '/',
+  search: '',
+  hash: '',
+});
+
+export interface NextRouterAdapterProps {
+  children: ReactNode;
+  /**
+   * Pass `scroll: false` to every Next router call by default.
+   * Useful for filter/pagination apps where the page should never
+   * jump on URL changes. Default: undefined (use Next's own default).
+   */
+  defaultScroll?: boolean;
+}
+
+/**
+ * Wraps a subtree so all `@djangocfg/ui-core/hooks` router calls go
+ * through Next's App Router. Server components, loaders, and prefetch
+ * keep working as if you used `next/navigation` directly.
+ */
+export function NextRouterAdapter({
+  children,
+  defaultScroll,
+}: NextRouterAdapterProps) {
+  const next = useNextRouter();
+
+  const adapter = useMemo<RouterAdapter>(
+    () => ({
+      push(url) {
+        next.push(url, defaultScroll === undefined ? undefined : { scroll: defaultScroll });
+      },
+      replace(url) {
+        next.replace(url, defaultScroll === undefined ? undefined : { scroll: defaultScroll });
+      },
+      back() {
+        next.back();
+      },
+      forward() {
+        next.forward();
+      },
+      getLocation() {
+        if (typeof window === 'undefined') return SSR_LOCATION;
+        return {
+          pathname: window.location.pathname,
+          search: window.location.search,
+          hash: window.location.hash,
+        };
+      },
+    }),
+    [next, defaultScroll]
+  );
+
+  return (
+    <RouterAdapterProvider value={adapter}>{children}</RouterAdapterProvider>
+  );
+}
+
+/**
+ * Maps our agnostic Link API → next/link props. Lives at module scope so
+ * the component identity is stable (avoids tree remounts on every render).
+ */
+const NextLinkAdapter: LinkComponent = forwardRef<HTMLAnchorElement, LinkComponentProps>(
+  function NextLinkAdapter({ href, replace, scroll, prefetch, children, ...rest }, ref) {
+    return (
+      <NextLink
+        href={href}
+        replace={replace}
+        scroll={scroll}
+        prefetch={prefetch ?? undefined}
+        ref={ref}
+        {...rest}
+      >
+        {children}
+      </NextLink>
+    );
+  }
+);
+
+export interface NextLinkProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Wires `<Link>` from `@djangocfg/ui-core/components` to `next/link`.
+ * Mount alongside `NextRouterAdapter` near the root of a Next app so
+ * every Link picks up Next's prefetch / RSC handling automatically.
+ */
+export function NextLinkProvider({ children }: NextLinkProviderProps) {
+  return <LinkProvider value={NextLinkAdapter}>{children}</LinkProvider>;
+}

package/src/hooks/router/index.ts

@@ -0,0 +1,90 @@
+// ============================================================================
+// Router hooks — framework-agnostic navigation primitives.
+// See ./README.md for design rationale and Next.js adapter example.
+// ============================================================================
+
+'use client';
+
+// Adapter (context + provider + default + types)
+export {
+  RouterAdapterContext,
+  RouterAdapterProvider,
+  defaultAdapter,
+  useRouterAdapter,
+} from './adapter';
+export type {
+  RouterAdapter,
+  RouterAdapterProviderProps,
+  RouterLocation,
+} from './adapter';
+
+// useLocation (+ per-property subscription)
+export {
+  useLocation,
+  useLocationProperty,
+  NAVIGATE_EVENT,
+  PUSH_STATE_EVENT,
+  REPLACE_STATE_EVENT,
+} from './useLocation';
+export type { LocationSnapshot } from './useLocation';
+
+// useNavigate
+export { useNavigate } from './useNavigate';
+export type { NavigateOptions, UseNavigateReturn } from './useNavigate';
+
+// useQueryParams
+export { useQueryParams } from './useQueryParams';
+export type {
+  QueryParamsSnapshot,
+  QueryParamValue,
+  QueryParamUpdates,
+  SetQueryParamsOptions,
+  UseQueryParamsReturn,
+} from './useQueryParams';
+
+// useBackOrFallback
+export { useBackOrFallback } from './useBackOrFallback';
+export type { UseBackOrFallbackReturn } from './useBackOrFallback';
+
+// useUrlBuilder (+ pure helpers)
+export { useUrlBuilder, buildUrl, buildQueryString } from './useUrlBuilder';
+export type {
+  QueryValue,
+  QueryParamsInput,
+  UseUrlBuilderReturn,
+} from './useUrlBuilder';
+
+// useSmartLink
+export { useSmartLink } from './useSmartLink';
+export type {
+  UseSmartLinkOptions,
+  SmartLinkHandlers,
+} from './useSmartLink';
+
+// useIsActive
+export { useIsActive } from './useIsActive';
+export type { UseIsActiveOptions } from './useIsActive';
+
+// useQueryState (typed single-key URL state, nuqs-style)
+export { useQueryState } from './useQueryState';
+export type {
+  UseQueryStateOptions,
+  QueryStateUpdater,
+} from './useQueryState';
+
+// Parsers (typed marshalling between URL strings and JS values)
+export {
+  parseAsString,
+  parseAsInteger,
+  parseAsFloat,
+  parseAsBoolean,
+  parseAsIsoDate,
+  parseAsStringEnum,
+  parseAsArrayOf,
+  parseAsJson,
+} from './parsers';
+export type { QueryParser, QueryParserBuilder } from './parsers';
+
+// useRouter (composite facade)
+export { useRouter } from './useRouter';
+export type { UseRouterReturn } from './useRouter';

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