@djangocfg/ui-nextjs 2.1.283 → 2.1.285

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.283",
+  "version": "2.1.285",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -85,11 +85,11 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.283",
-    "@djangocfg/i18n": "^2.1.283",
-    "@djangocfg/nextjs": "^2.1.283",
-    "@djangocfg/ui-core": "^2.1.283",
-    "@djangocfg/ui-tools": "^2.1.283",
+    "@djangocfg/api": "^2.1.285",
+    "@djangocfg/i18n": "^2.1.285",
+    "@djangocfg/nextjs": "^2.1.285",
+    "@djangocfg/ui-core": "^2.1.285",
+    "@djangocfg/ui-tools": "^2.1.285",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -112,7 +112,7 @@
     "react-chartjs-2": "^5.3.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.283",
+    "@djangocfg/typescript-config": "^2.1.285",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-slot": "^1.2.4",
     "@types/node": "^24.7.2",

package/src/theme/ForcedThemeContext.tsx

@@ -0,0 +1,45 @@
+/**
+ * ForcedThemeContext
+ *
+ * Published by `ThemeOverride` so downstream UI (theme switchers, toggles,
+ * indicators) can tell whether the current route forces a specific theme and
+ * adapt accordingly — typically by disabling or hiding their controls.
+ *
+ * Default value is `null` (no override) — consumers outside a `ThemeOverride`
+ * mount see the same shape as consumers on an unforced route, so there's no
+ * need to guard against the provider being absent.
+ */
+
+'use client';
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+import type { ForcedTheme } from './ThemeOverride';
+
+const ForcedThemeContext = createContext<ForcedTheme | null>(null);
+
+interface ForcedThemeProviderProps {
+  value: ForcedTheme | null;
+  children: ReactNode;
+}
+
+export function ForcedThemeProvider({ value, children }: ForcedThemeProviderProps) {
+  return (
+    <ForcedThemeContext.Provider value={value}>
+      {children}
+    </ForcedThemeContext.Provider>
+  );
+}
+
+/**
+ * Read the currently-forced theme. `null` means the user is free to choose.
+ *
+ * @example
+ * ```tsx
+ * const forced = useForcedTheme();
+ * if (forced) return <p>Theme is locked to {forced} on this page.</p>;
+ * ```
+ */
+export function useForcedTheme(): ForcedTheme | null {
+  return useContext(ForcedThemeContext);
+}

package/src/theme/ThemeOverride.tsx

@@ -0,0 +1,163 @@
+/**
+ * ThemeOverride - Pathname-aware forced theme
+ *
+ * Applies a forced `light` or `dark` theme via `next-themes` while the current
+ * pathname matches any of the supplied rules, and restores the user's prior
+ * choice when the pathname no longer matches.
+ *
+ * Unlike `ForceTheme` (which scopes CSS vars to a wrapper div), this component
+ * mutates the real `next-themes` value — so the `html.dark` class is applied
+ * and every surface (navbar, footer, body, page) picks the new theme up
+ * consistently.
+ *
+ * The matcher is **dependency-free** and understands:
+ * - Exact match (`/` matches `/`)
+ * - Prefix match (`/docs` matches `/docs/getting-started`)
+ * - Glob wildcards (`*` for a single segment, `**` for any depth)
+ *
+ * Consumers pass the pathname already stripped of the locale prefix — matching
+ * is not locale-aware here.
+ *
+ * @example
+ * ```tsx
+ * <ThemeOverride
+ *   pathname={pathname}
+ *   rules={[
+ *     { path: '/', theme: 'dark' },
+ *     { path: ['/legal', '/legal/**'], theme: 'light' },
+ *   ]}
+ * />
+ * ```
+ */
+
+'use client';
+
+import { useEffect, useMemo, useRef } from 'react';
+
+import { useThemeContext } from './ThemeProvider';
+
+import type { Theme } from './ThemeProvider';
+
+export type ForcedTheme = Exclude<Theme, 'system'>;
+
+export interface ThemeOverrideRule {
+  /** Path (or array of paths) to match against. Supports `*` and `**` globs. */
+  path: string | string[];
+  /** Theme to apply while the path matches. */
+  theme: ForcedTheme;
+}
+
+export interface ThemeOverrideProps {
+  /** Pathname stripped of locale prefix. Use `usePathnameWithoutLocale()` if you have it. */
+  pathname: string;
+  /** Rules evaluated top-to-bottom — first match wins. */
+  rules?: ThemeOverrideRule[];
+}
+
+/**
+ * Resolve the first matching rule's forced theme for a pathname, or `null`.
+ * Pure helper — use this to render a `ForcedThemeProvider` in the same tree
+ * where you mount `ThemeOverride`.
+ */
+export function resolveForcedTheme(
+  pathname: string,
+  rules?: ThemeOverrideRule[],
+): ForcedTheme | null {
+  if (!rules || rules.length === 0) return null;
+  for (const rule of rules) {
+    if (matchesAny(pathname, rule.path)) return rule.theme;
+  }
+  return null;
+}
+
+// --- inlined matcher (no dep on @djangocfg/layouts) -------------------------
+
+function matchGlob(pathname: string, pattern: string): boolean {
+  const pathParts = pathname.replace(/\/+$/, '').split('/').filter(Boolean);
+  const patternParts = pattern.replace(/\/+$/, '').split('/').filter(Boolean);
+
+  let pi = 0;
+  let ti = 0;
+
+  while (ti < patternParts.length && pi < pathParts.length) {
+    const pat = patternParts[ti];
+    if (pat === '**') {
+      if (ti === patternParts.length - 1) return true;
+      const next = patternParts[ti + 1];
+      while (pi < pathParts.length) {
+        if (pathParts[pi] === next || next === '*') break;
+        pi++;
+      }
+      ti++;
+    } else if (pat === '*') {
+      pi++;
+      ti++;
+    } else {
+      if (pathParts[pi] !== pat) return false;
+      pi++;
+      ti++;
+    }
+  }
+
+  if (ti < patternParts.length) {
+    for (let i = ti; i < patternParts.length; i++) {
+      if (patternParts[i] !== '**') return false;
+    }
+  }
+
+  return pi === pathParts.length;
+}
+
+function matchOne(pathname: string, pattern: string): boolean {
+  const p = pathname.length > 1 ? pathname.replace(/\/+$/, '') : pathname;
+  const q = pattern.length > 1 ? pattern.replace(/\/+$/, '') : pattern;
+  if (q.includes('*')) return matchGlob(p, q);
+  return p === q || p.startsWith(q + '/');
+}
+
+function matchesAny(pathname: string, path: string | string[]): boolean {
+  return Array.isArray(path) ? path.some((p) => matchOne(pathname, p)) : matchOne(pathname, path);
+}
+
+// --- component --------------------------------------------------------------
+
+export function ThemeOverride({ pathname, rules }: ThemeOverrideProps) {
+  const { theme, setTheme } = useThemeContext();
+
+  // First rule whose path matches the current pathname. null = no override.
+  const forced = useMemo<ForcedTheme | null>(
+    () => resolveForcedTheme(pathname, rules),
+    [pathname, rules],
+  );
+
+  // Stash the user's own pick so we can restore it when they leave a forced route.
+  // We capture only non-override theme values (from renders where `forced === null`).
+  // Stored as a ref so it doesn't drive the effect.
+  const userThemeRef = useRef<string | undefined>(undefined);
+
+  // Keep userThemeRef in sync with what next-themes reports **while not forcing**.
+  // Every render where the route isn't overridden, the current `theme` IS the user's
+  // own pick — snapshot it. During a forced render we leave the ref alone so the
+  // original value survives until we hand control back.
+  useEffect(() => {
+    if (forced === null && theme) {
+      userThemeRef.current = theme;
+    }
+  }, [forced, theme]);
+
+  // Apply / revert the forced theme. Intentionally driven only by `forced` — the
+  // user may toggle the theme manually while forcing is off, and that's fine
+  // (the sync effect above records the new value).
+  useEffect(() => {
+    if (forced) {
+      setTheme(forced);
+      return;
+    }
+    const restore = userThemeRef.current ?? 'system';
+    setTheme(restore);
+    // setTheme from next-themes is stable by ref; omit on purpose.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [forced]);
+
+  return null;
+}

package/src/theme/ThemeToggle.tsx

@@ -27,17 +27,34 @@ import { useEffect, useState } from 'react';
 import { Button } from '@djangocfg/ui-core/components';
 import { useIsMobile } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
+import { useForcedTheme } from './ForcedThemeContext';
 import { useThemeContext } from './ThemeProvider';
 
+export type ThemeLockBehavior = 'disable' | 'hide';
+
 export interface ThemeToggleProps {
   /** Custom className */
   className?: string;
   /** Size variant (auto-detects mobile if not specified) */
   size?: 'default' | 'compact' | 'auto';
+  /**
+   * What to do when the current route forces a theme via `ThemeOverride`.
+   * - `disable` (default): render the toggle disabled with a tooltip.
+   * - `hide`: render nothing.
+   */
+  lockedBehavior?: ThemeLockBehavior;
+  /** Title shown when the control is locked. */
+  lockedTitle?: string;
 }
 
-export function ThemeToggle({ className, size = 'auto' }: ThemeToggleProps) {
+export function ThemeToggle({
+  className,
+  size = 'auto',
+  lockedBehavior = 'disable',
+  lockedTitle = 'Theme is set for this page',
+}: ThemeToggleProps) {
   const { resolvedTheme, toggleTheme } = useThemeContext();
+  const forcedTheme = useForcedTheme();
   const [mounted, setMounted] = useState(false);
   const isMobile = useIsMobile();
 
@@ -46,11 +63,20 @@ export function ThemeToggle({ className, size = 'auto' }: ThemeToggleProps) {
     setMounted(true);
   }, []);
 
+  const isLocked = Boolean(forcedTheme);
   // Determine actual size based on prop and screen size
   const actualSize = size === 'auto' ? (isMobile ? 'compact' : 'default') : size;
   const buttonSize = actualSize === 'compact' ? 'h-8 w-8' : 'h-9 w-9';
   const iconSize = actualSize === 'compact' ? 'h-3.5 w-3.5' : 'h-4 w-4';
 
+  // The icon always reflects what's on screen (forced or not) — that is
+  // `resolvedTheme`. When locked, it shows the forced theme's icon.
+  const showSun = mounted ? resolvedTheme === 'light' : true;
+
+  if (isLocked && lockedBehavior === 'hide') {
+    return null;
+  }
+
   if (!mounted) {
     return (
       <Button
@@ -69,15 +95,14 @@ export function ThemeToggle({ className, size = 'auto' }: ThemeToggleProps) {
     <Button
       variant="ghost"
       size="icon"
-      onClick={toggleTheme}
-      className={cn(buttonSize, className)}
+      onClick={isLocked ? undefined : toggleTheme}
+      disabled={isLocked}
+      title={isLocked ? lockedTitle : undefined}
+      aria-label={isLocked ? lockedTitle : 'Toggle theme'}
+      className={cn(buttonSize, isLocked && 'cursor-not-allowed opacity-60', className)}
     >
-      {resolvedTheme === 'light' ? (
-        <Sun className={iconSize} />
-      ) : (
-        <Moon className={iconSize} />
-      )}
-      <span className="sr-only">Toggle theme</span>
+      {showSun ? <Sun className={iconSize} /> : <Moon className={iconSize} />}
+      <span className="sr-only">{isLocked ? lockedTitle : 'Toggle theme'}</span>
     </Button>
   );
 }

package/src/theme/index.ts

@@ -4,3 +4,6 @@ export { ThemeProvider, useThemeContext } from './ThemeProvider';
 export type { Theme, ThemeProviderProps } from './ThemeProvider';
 export { ThemeToggle } from './ThemeToggle';
 export { ForceTheme } from './ForceTheme';
+export { ThemeOverride, resolveForcedTheme } from './ThemeOverride';
+export type { ThemeOverrideRule, ThemeOverrideProps, ForcedTheme } from './ThemeOverride';
+export { ForcedThemeProvider, useForcedTheme } from './ForcedThemeContext';