@djangocfg/ui-core 2.1.404 → 2.1.408

package/README.md

@@ -33,7 +33,8 @@ Organized in `components/` by category — everything re-exported from the root
 | **Forms** | `Button`, `ButtonLink`, `ButtonGroup`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Label`, `Form`, `Field`, `InputOTP`, `PhoneInput`, `InputGroup`, `DownloadButton` |
 | **Select** | `Select`, `Combobox`, `ComboboxAsync`, `MultiSelect`, `MultiSelectPro`, `MultiSelectProAsync`, `CountrySelect`, `LanguageSelect` (all support icons + badges; `Select` accepts empty-string values; `ComboboxAsync` is the single-select counterpart to `MultiSelectProAsync` for server-side typeahead) |
 | **Overlay** | `Dialog`, `AlertDialog`, `Sheet`, `Drawer`, `Popover`, `Tooltip`, `HoverCard`, `ResponsiveSheet`, `SidePanel` |
-| **Navigation** | `Link`, `Breadcrumb`, `BreadcrumbNavigation`, `Pagination`, `StaticPagination`, `SSRPagination`, `Sidebar` (full shadcn primitives), `Tabs`, `Accordion`, `Collapsible`, `Command`, `DropdownMenu`, `ContextMenu`, `Menubar`, `NavigationMenu` |
+| **Navigation** | `Link`, `Breadcrumb`, `BreadcrumbNavigation`, `Pagination`, `StaticPagination`, `SSRPagination`, `Sidebar` (full shadcn primitives), `Tabs`, `Accordion`, `Collapsible`, `Command`, `DropdownMenu`, `ContextMenu`, `Menubar`, `NavigationMenu`, `MenuBuilder` (declarative data-driven menu) |
+| **Theme** | `ThemeProvider`, `ThemeToggle`, `ForceTheme`, `ThemeOverride`, `useThemeContext`, `useForcedTheme` — framework-agnostic theme runtime |
 | **Layout** | `Card`, `Section`, `Sticky`, `ScrollArea`, `Resizable`, `Separator`, `Skeleton`, `AspectRatio` |
 | **Data** | `Table`, `Badge`, `Avatar`, `Progress`, `Carousel`, `Calendar`, `DatePicker`, `DateRangePicker`, `Toggle`, `ToggleGroup`, `Chart*` |
 | **Feedback** | `Alert`, `Spinner`, `Empty`, `Preloader`, `Toaster` (Sonner) |
@@ -68,12 +69,12 @@ import { useNavigate, useLocation, useQueryParams, useRouter, useIsActive } from
 
 | Group | Hooks |
 |---|---|
-| **Router** (adapter-driven) | `useNavigate`, `useLocation`, `useQueryParams`, `useQueryState` (typed), `useRouter`, `useUrlBuilder`, `useSmartLink`, `useIsActive`, `useBackOrFallback` + parsers (`parseAsInteger`, `parseAsBoolean`, …) |
+| **Router** (adapter-driven) | `useNavigate`, `useLocation`, `useLocationProperty`, `useQueryParams`, `useQueryState` (typed), `useRouter`, `useUrlBuilder`, `useSmartLink`, `useIsActive`, `useBackOrFallback` + parsers (`parseAsInteger`, `parseAsBoolean`, …) |
 | **Media** | `useIsMobile`, `useIsPhone`, `useIsTabletOrBelow`, `useMediaQuery` |
 | **Device** | `useDeviceDetect`, `useBrowserDetect`, `useShortcutModLabel` |
 | **State** | `useDebounce`, `useDebouncedCallback`, `useCountdown`, `useImageLoader`, `useMounted` |
 | **DOM** | `useEventListener` |
-| **Theme** | `useThemeColor`, `useThemePalette` (palette-aware hex colors for Canvas/SVG) |
+| **Theme** | `useResolvedTheme` (light/dark detection), `useThemeColor`, `useThemePalette` (palette-aware hex colors for Canvas/SVG) |
 | **Hotkey** | `useHotkey` (smart `inInput` + `preventDefault` policy), `useHotkeyChord` (sequences), `formatHotkey('mod+k') → ⌘K`, `useHotkeyHelp` (auto cheat-sheet) |
 | **Audio** | `createSoundBus`, `useNotificationSounds`, `useAudioPrefs`, `useSoundEffect` — Safari unlock, mute persist, per-event toggles + volume scale, native-host bridge |
 | **Tabs** | `useActiveTab`, `useIsTabActive`, `useIsTabLeader` — cross-tab focus + leader election via BroadcastChannel |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.404",
+  "version": "2.1.408",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -43,6 +43,11 @@
       "import": "./src/hooks/index.ts",
       "require": "./src/hooks/index.ts"
     },
+    "./theme": {
+      "types": "./src/theme/index.ts",
+      "import": "./src/theme/index.ts",
+      "require": "./src/theme/index.ts"
+    },
     "./adapters/nextjs": {
       "types": "./src/hooks/router/adapters/nextjs.tsx",
       "import": "./src/hooks/router/adapters/nextjs.tsx",
@@ -90,7 +95,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.404",
+    "@djangocfg/i18n": "^2.1.408",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -149,6 +154,7 @@
     "i18n-iso-countries": "^7.14.0",
     "input-otp": "1.4.2",
     "libphonenumber-js": "^1.12.24",
+    "next-themes": "^0.4.6",
     "nextjs-toploader": "^3.9.17",
     "react-day-picker": "9.11.1",
     "react-hotkeys-hook": "^4.6.1",
@@ -160,8 +166,8 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.404",
-    "@djangocfg/typescript-config": "^2.1.404",
+    "@djangocfg/i18n": "^2.1.408",
+    "@djangocfg/typescript-config": "^2.1.408",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/forms/textarea/index.tsx

@@ -41,7 +41,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       return (
         <textarea
           className={cn(
-            "flex min-h-[60px] w-full rounded-[var(--radius)] border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+            "flex min-h-[60px] w-full rounded-[var(--radius)] border border-input bg-transparent px-3 py-2 text-sm text-foreground shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
             className
           )}
           ref={ref}

package/src/components/index.ts

@@ -56,6 +56,8 @@ export { navigationMenuTriggerStyle, NavigationMenu, NavigationMenuList, Navigat
 export { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarPortal, MenubarSubContent, MenubarSubTrigger, MenubarGroup, MenubarSub, MenubarShortcut } from './navigation/menubar';
 export { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup } from './navigation/dropdown-menu';
 export { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuItem, ContextMenuLabel, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from './navigation/context-menu';
+export { MenuBuilder } from './navigation/menu';
+export type { MenuItem, MenuActionItem, MenuSubmenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioOption, MenuSeparator, MenuLabel, MenuSection, MenuCustom, MenuRowBase, MenuBuilderProps } from './navigation/menu';
 export { Tabs, TabsContent, TabsList, TabsTrigger } from './navigation/tabs';
 export { useTabsState } from './navigation/tabs/useTabsState';
 export type { UseTabsStateOptions, UseTabsStateResult } from './navigation/tabs/useTabsState';

package/src/components/navigation/menu/index.tsx

@@ -0,0 +1,15 @@
+export { MenuBuilder } from './menu-builder';
+export type {
+  MenuItem,
+  MenuActionItem,
+  MenuSubmenuItem,
+  MenuCheckboxItem,
+  MenuRadioGroup,
+  MenuRadioOption,
+  MenuSeparator,
+  MenuLabel,
+  MenuSection,
+  MenuCustom,
+  MenuRowBase,
+  MenuBuilderProps,
+} from './types';

package/src/components/navigation/menu/menu-builder.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import { cn } from '../../../lib';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+} from '../dropdown-menu';
+import { renderItems } from './render-items';
+import type { MenuBuilderProps } from './types';
+
+/**
+ * MenuBuilder — declarative menu.
+ *
+ * Pass `items: MenuItem[]` and a trigger; it renders a fully accessible
+ * menu through the existing Radix `DropdownMenu*` primitives (items,
+ * submenus, radio groups, checkboxes, separators, section labels,
+ * shortcuts, icons, descriptions).
+ *
+ * @example
+ * <MenuBuilder items={menu} side="top" align="start">
+ *   <Button variant="ghost" size="icon"><Plus /></Button>
+ * </MenuBuilder>
+ */
+export function MenuBuilder({
+  items,
+  children,
+  open,
+  onOpenChange,
+  defaultOpen,
+  side,
+  align = 'start',
+  sideOffset,
+  alignOffset,
+  contentClassName,
+  showDescriptions = true,
+}: MenuBuilderProps) {
+  return (
+    <DropdownMenu
+      open={open}
+      onOpenChange={onOpenChange}
+      defaultOpen={defaultOpen}
+    >
+      <DropdownMenuTrigger asChild>{children}</DropdownMenuTrigger>
+      <DropdownMenuContent
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        className={cn('min-w-56 max-w-xs', contentClassName)}
+      >
+        {renderItems(items, { showDescriptions })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/components/navigation/menu/menu-row.tsx

@@ -0,0 +1,95 @@
+import { createElement, isValidElement, type ReactNode } from 'react';
+
+import { cn } from '../../../lib';
+import { DropdownMenuShortcut } from '../dropdown-menu';
+import type { MenuRowBase } from './types';
+
+/**
+ * Resolve the `icon` field to a node. `icon` may be:
+ *  - a ready React element (`<Foo />`)
+ *  - a component *type*: a plain function component OR a
+ *    `forwardRef`/`memo` object (lucide-react icons are forwardRef
+ *    objects, so a bare `typeof === 'function'` check misses them).
+ */
+function renderIcon(icon: MenuRowBase['icon']): ReactNode {
+  if (!icon) return null;
+  if (isValidElement(icon)) return icon;
+
+  const isFunctionComponent = typeof icon === 'function';
+  const isObjectComponent =
+    typeof icon === 'object' && icon !== null && '$$typeof' in icon;
+
+  if (isFunctionComponent || isObjectComponent) {
+    return createElement(
+      icon as React.ComponentType<{ className?: string }>,
+      { className: 'size-4 shrink-0' },
+    );
+  }
+  return icon as ReactNode;
+}
+
+export interface MenuRowProps {
+  icon?: MenuRowBase['icon'];
+  label: ReactNode;
+  description?: ReactNode;
+  shortcut?: string;
+  showDescription?: boolean;
+}
+
+/**
+ * Inner layout shared by every menu row kind: leading icon, label with
+ * an optional muted description line, trailing shortcut. Sits inside the
+ * Radix `Item` / `SubTrigger` / `CheckboxItem` wrappers.
+ */
+export function MenuRow({
+  icon,
+  label,
+  description,
+  shortcut,
+  showDescription = true,
+}: MenuRowProps) {
+  const iconNode = renderIcon(icon);
+
+  return (
+    <>
+      {iconNode}
+      <span className="flex min-w-0 flex-1 flex-col">
+        <span className="truncate">{label}</span>
+        {showDescription && description ? (
+          <span className="truncate text-xs text-muted-foreground">
+            {description}
+          </span>
+        ) : null}
+      </span>
+      {shortcut ? <DropdownMenuShortcut>{shortcut}</DropdownMenuShortcut> : null}
+    </>
+  );
+}
+
+/** Row layout for radio/checkbox rows — the Radix wrapper reserves the
+ *  indicator column (`pl-8`) so the icon is placed inside the flex flow
+ *  after that reserved space rather than as a leading element. */
+export function MenuIndicatorRow({
+  icon,
+  label,
+  description,
+  shortcut,
+  showDescription = true,
+}: MenuRowProps) {
+  const iconNode = renderIcon(icon);
+
+  return (
+    <span className={cn('flex min-w-0 flex-1 items-center gap-2')}>
+      {iconNode}
+      <span className="flex min-w-0 flex-1 flex-col">
+        <span className="truncate">{label}</span>
+        {showDescription && description ? (
+          <span className="truncate text-xs text-muted-foreground">
+            {description}
+          </span>
+        ) : null}
+      </span>
+      {shortcut ? <DropdownMenuShortcut>{shortcut}</DropdownMenuShortcut> : null}
+    </span>
+  );
+}

package/src/components/navigation/menu/render-items.tsx

@@ -0,0 +1,166 @@
+import { Fragment, type ReactNode } from 'react';
+
+import {
+  DropdownMenuCheckboxItem,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuPortal,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+} from '../dropdown-menu';
+import { MenuIndicatorRow, MenuRow } from './menu-row';
+import type { MenuItem } from './types';
+
+interface RenderOptions {
+  showDescriptions: boolean;
+}
+
+/** Drop `hidden` rows before rendering. */
+function isVisible(item: MenuItem): boolean {
+  return !('hidden' in item && item.hidden);
+}
+
+/**
+ * Recursive renderer — powers both the root content and every
+ * `SubContent`. Pure: it only maps data to Radix elements.
+ */
+export function renderItems(
+  items: MenuItem[],
+  opts: RenderOptions,
+): ReactNode {
+  return items.filter(isVisible).map((item, index) => {
+    switch (item.kind) {
+      case 'separator':
+        return <DropdownMenuSeparator key={item.id ?? `sep-${index}`} />;
+
+      case 'label':
+        return (
+          <DropdownMenuLabel key={item.id ?? `label-${index}`}>
+            {item.label}
+          </DropdownMenuLabel>
+        );
+
+      case 'custom':
+        return <Fragment key={item.id}>{item.render()}</Fragment>;
+
+      case 'item':
+        return (
+          <DropdownMenuItem
+            key={item.id}
+            href={item.href}
+            variant={item.variant}
+            disabled={item.disabled}
+            onSelect={(event) => {
+              // closeOnSelect=false → keep the menu open.
+              if (item.closeOnSelect === false) event.preventDefault();
+              item.onSelect?.(event);
+            }}
+          >
+            <MenuRow
+              icon={item.icon}
+              label={item.label}
+              description={item.description}
+              shortcut={item.shortcut}
+              showDescription={opts.showDescriptions}
+            />
+          </DropdownMenuItem>
+        );
+
+      case 'submenu':
+        return (
+          <DropdownMenuSub key={item.id}>
+            <DropdownMenuSubTrigger disabled={item.disabled}>
+              <MenuRow
+                icon={item.icon}
+                label={item.label}
+                description={item.description}
+                showDescription={opts.showDescriptions}
+              />
+            </DropdownMenuSubTrigger>
+            <DropdownMenuPortal>
+              <DropdownMenuSubContent>
+                {renderItems(item.items, opts)}
+              </DropdownMenuSubContent>
+            </DropdownMenuPortal>
+          </DropdownMenuSub>
+        );
+
+      case 'checkbox':
+        return (
+          <DropdownMenuCheckboxItem
+            key={item.id}
+            checked={item.checked}
+            disabled={item.disabled}
+            onCheckedChange={item.onCheckedChange}
+          >
+            <MenuIndicatorRow
+              icon={item.icon}
+              label={item.label}
+              description={item.description}
+              shortcut={item.shortcut}
+              showDescription={opts.showDescriptions}
+            />
+          </DropdownMenuCheckboxItem>
+        );
+
+      case 'radio-group':
+        return (
+          <Fragment key={item.id}>
+            {item.label ? (
+              <DropdownMenuLabel>{item.label}</DropdownMenuLabel>
+            ) : null}
+            <DropdownMenuRadioGroup
+              value={item.value}
+              onValueChange={item.onValueChange}
+            >
+              {item.options.filter((o) => !o.hidden).map((option) => (
+                <DropdownMenuRadioItem
+                  key={option.id}
+                  value={option.value}
+                  disabled={option.disabled}
+                >
+                  <MenuIndicatorRow
+                    icon={option.icon}
+                    label={option.label}
+                    description={option.description}
+                    shortcut={option.shortcut}
+                    showDescription={opts.showDescriptions}
+                  />
+                </DropdownMenuRadioItem>
+              ))}
+            </DropdownMenuRadioGroup>
+          </Fragment>
+        );
+
+      case 'section': {
+        // A separator follows the section unless explicitly disabled or
+        // it is the last visible item.
+        const isLast =
+          index === items.filter(isVisible).length - 1;
+        const withSeparator = item.separator !== false && !isLast;
+        return (
+          <Fragment key={item.id}>
+            <DropdownMenuGroup>
+              {item.label ? (
+                <DropdownMenuLabel>{item.label}</DropdownMenuLabel>
+              ) : null}
+              {renderItems(item.items, opts)}
+            </DropdownMenuGroup>
+            {withSeparator ? <DropdownMenuSeparator /> : null}
+          </Fragment>
+        );
+      }
+
+      default: {
+        // Exhaustiveness guard — a new `kind` without a branch fails here.
+        const _never: never = item;
+        return _never;
+      }
+    }
+  });
+}

package/src/components/navigation/menu/types.ts

@@ -0,0 +1,137 @@
+import type { ComponentType, ReactNode } from 'react';
+
+/**
+ * Declarative menu model. A host passes `MenuItem[]` and a trigger to
+ * `MenuBuilder`; it renders through the existing Radix `DropdownMenu*`
+ * primitives. The `kind` field is the discriminator.
+ */
+
+/** Shared fields for any selectable row. */
+export interface MenuRowBase {
+  /** Stable identity — used as the React key. */
+  id: string;
+  label: ReactNode;
+  /** Leading icon: a lucide-react component or any node. */
+  icon?: ComponentType<{ className?: string }> | ReactNode;
+  /** Secondary muted line under the label. */
+  description?: ReactNode;
+  /** Keyboard hint, right-aligned (display only), e.g. "⌘U". */
+  shortcut?: string;
+  disabled?: boolean;
+  /** When true the row is filtered out before render. */
+  hidden?: boolean;
+}
+
+/** Plain action row. */
+export interface MenuActionItem extends MenuRowBase {
+  kind: 'item';
+  onSelect?: (event: Event) => void;
+  /** Renders the row as a link. */
+  href?: string;
+  variant?: 'default' | 'destructive';
+  /** Keep the menu open after select. Default: true (closes). */
+  closeOnSelect?: boolean;
+}
+
+/** Nested menu. */
+export interface MenuSubmenuItem extends MenuRowBase {
+  kind: 'submenu';
+  items: MenuItem[];
+}
+
+/** A single checkbox row. */
+export interface MenuCheckboxItem extends MenuRowBase {
+  kind: 'checkbox';
+  checked: boolean;
+  onCheckedChange: (checked: boolean) => void;
+}
+
+/** One option inside a radio group. */
+export interface MenuRadioOption {
+  id: string;
+  value: string;
+  label: ReactNode;
+  icon?: MenuRowBase['icon'];
+  description?: ReactNode;
+  shortcut?: string;
+  disabled?: boolean;
+  hidden?: boolean;
+}
+
+/** Controlled radio group with an optional heading. */
+export interface MenuRadioGroup {
+  kind: 'radio-group';
+  id: string;
+  label?: ReactNode;
+  value: string;
+  onValueChange: (value: string) => void;
+  options: MenuRadioOption[];
+}
+
+/** Visual divider. */
+export interface MenuSeparator {
+  kind: 'separator';
+  id?: string;
+}
+
+/** Non-interactive section header. */
+export interface MenuLabel {
+  kind: 'label';
+  id?: string;
+  label: ReactNode;
+  hidden?: boolean;
+}
+
+/**
+ * A labelled group of items — sugar over label + items + a trailing
+ * separator.
+ */
+export interface MenuSection {
+  kind: 'section';
+  id: string;
+  label?: ReactNode;
+  items: MenuItem[];
+  /** Draw a separator after the section. Default: true. */
+  separator?: boolean;
+}
+
+/**
+ * Escape hatch — arbitrary node wrapped in a non-focusable row. Use for
+ * static content (banners, inline inputs), never for actions: it is not
+ * a Radix `Item` and cannot receive keyboard focus.
+ */
+export interface MenuCustom {
+  kind: 'custom';
+  id: string;
+  render: () => ReactNode;
+}
+
+export type MenuItem =
+  | MenuActionItem
+  | MenuSubmenuItem
+  | MenuCheckboxItem
+  | MenuRadioGroup
+  | MenuSeparator
+  | MenuLabel
+  | MenuSection
+  | MenuCustom;
+
+export interface MenuBuilderProps {
+  /** Declarative menu tree. */
+  items: MenuItem[];
+  /** Trigger element — rendered via Radix `asChild`. */
+  children: ReactNode;
+  /** Controlled open state. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  defaultOpen?: boolean;
+  /** Positioning — forwarded to the content panel. */
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+  alignOffset?: number;
+  /** Extra class for the content panel. */
+  contentClassName?: string;
+  /** Render the muted description line on rows that have one. Default: true. */
+  showDescriptions?: boolean;
+}

package/src/hooks/index.ts

@@ -35,6 +35,7 @@ export {
   useRouterAdapter,
   // useLocation
   useLocation,
+  useLocationProperty,
   NAVIGATE_EVENT,
   // useNavigate
   useNavigate,

package/src/hooks/theme/useResolvedTheme.ts

@@ -5,62 +5,77 @@ import { useEffect, useState } from 'react';
 export type ResolvedTheme = 'light' | 'dark';
 
 /**
- * Hook to detect the current resolved theme (light or dark)
+ * Detect the current resolved theme (light or dark).
  *
- * Standalone hook - doesn't require ThemeProvider.
- * Detects theme from:
- * 1. 'dark' class on html element
- * 2. System preference (prefers-color-scheme)
+ * Standalone hook — does not require ThemeProvider. Resolution order:
+ *  1. Explicit `dark` / `light` class on `<html>`.
+ *  2. Explicit `data-theme` attribute on `<html>`.
+ *  3. The *rendered* page background — sampled from `--background`.
+ *     This covers hosts where "light" is the absence of a class
+ *     (e.g. Storybook's `withThemeByClassName({ light: '', dark:
+ *     'dark' })`): without this step the hook would fall through to
+ *     the system preference and report `dark` for a light page on a
+ *     dark OS.
+ *  4. System `prefers-color-scheme` — last resort, only when no theme
+ *     tokens have been applied yet.
  *
- * For full theme control (setTheme, toggleTheme), use useThemeContext instead.
+ * For full theme control (setTheme, toggleTheme), use useThemeContext.
  *
  * @example
- * ```tsx
  * const theme = useResolvedTheme(); // 'light' | 'dark'
- * ```
  */
 export const useResolvedTheme = (): ResolvedTheme => {
   const [theme, setTheme] = useState<ResolvedTheme>('light');
 
   useEffect(() => {
+    const sampleBackground = (): ResolvedTheme | null => {
+      const probe = document.createElement('div');
+      probe.style.cssText =
+        'background-color:var(--background);position:absolute;width:0;height:0;pointer-events:none;';
+      document.body.appendChild(probe);
+      const rgb = getComputedStyle(probe).backgroundColor;
+      probe.remove();
+
+      const match = rgb.match(/\d+(\.\d+)?/g);
+      if (!match || match.length < 3) return null;
+      const [r, g, b] = match.map(Number) as [number, number, number];
+      // Perceived luminance (ITU-R BT.601).
+      const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+      return luminance > 0.5 ? 'light' : 'dark';
+    };
+
     const checkTheme = (): ResolvedTheme => {
-      // Check if dark class is applied to html element
-      if (document.documentElement.classList.contains('dark')) {
-        return 'dark';
-      }
+      const root = document.documentElement;
 
-      // Check if light class is explicitly applied (takes precedence over system)
-      if (document.documentElement.classList.contains('light')) {
-        return 'light';
-      }
+      if (root.classList.contains('dark')) return 'dark';
+      if (root.classList.contains('light')) return 'light';
+
+      const dataTheme = root.getAttribute('data-theme');
+      if (dataTheme === 'dark') return 'dark';
+      if (dataTheme === 'light') return 'light';
+
+      // No explicit theme class/attr — infer from the painted surface.
+      const sampled = sampleBackground();
+      if (sampled) return sampled;
 
-      // Check system preference only if no explicit theme class
       if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
         return 'dark';
       }
-
       return 'light';
     };
 
-    // Set initial theme
     setTheme(checkTheme());
 
-    // Listen for class changes on html element
     const observer = new MutationObserver(() => {
       setTheme(checkTheme());
     });
-
     observer.observe(document.documentElement, {
       attributes: true,
-      attributeFilter: ['class']
+      attributeFilter: ['class', 'data-theme', 'style'],
     });
 
-    // Listen for system theme changes
     const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-    const handleMediaChange = () => {
-      setTheme(checkTheme());
-    };
-
+    const handleMediaChange = () => setTheme(checkTheme());
     mediaQuery.addEventListener('change', handleMediaChange);
 
     return () => {

package/src/theme/ForceTheme.tsx

@@ -0,0 +1,116 @@
+/**
+ * ForceTheme - Force a specific theme for a section
+ *
+ * Wraps content to override the global theme setting.
+ * Works by adding both the theme class and inline CSS variables
+ * to ensure proper theme application regardless of parent context.
+ */
+
+'use client';
+
+import React, { ReactNode } from 'react';
+
+import { cn } from '../lib/utils';
+
+interface ForceThemeProps {
+  theme: 'light' | 'dark';
+  children: ReactNode;
+  className?: string;
+}
+
+// Dark theme CSS variables
+const darkThemeVars = {
+  // Base HSL values
+  '--background': '0 0% 4%',
+  '--foreground': '0 0% 98%',
+  '--card': '0 0% 8%',
+  '--card-foreground': '0 0% 98%',
+  '--popover': '0 0% 12%',
+  '--popover-foreground': '0 0% 98%',
+  '--primary': '217 91% 60%',
+  '--primary-foreground': '0 0% 100%',
+  '--secondary': '0 0% 98%',
+  '--secondary-foreground': '0 0% 9%',
+  '--muted': '0 0% 10%',
+  '--muted-foreground': '0 0% 60%',
+  '--accent': '0 0% 15%',
+  '--accent-foreground': '0 0% 98%',
+  '--destructive': '0 84% 60%',
+  '--destructive-foreground': '0 0% 98%',
+  '--border': '0 0% 15%',
+  '--input': '0 0% 15%',
+  '--ring': '217 91% 60%',
+  // Tailwind color tokens (used by bg-*, text-*, etc)
+  '--color-background': 'hsl(0 0% 4%)',
+  '--color-foreground': 'hsl(0 0% 98%)',
+  '--color-card': 'hsl(0 0% 8%)',
+  '--color-card-foreground': 'hsl(0 0% 98%)',
+  '--color-primary': 'hsl(217 91% 60%)',
+  '--color-primary-foreground': 'hsl(0 0% 100%)',
+  '--color-secondary': 'hsl(0 0% 98%)',
+  '--color-secondary-foreground': 'hsl(0 0% 9%)',
+  '--color-muted': 'hsl(0 0% 10%)',
+  '--color-muted-foreground': 'hsl(0 0% 60%)',
+  '--color-accent': 'hsl(0 0% 15%)',
+  '--color-accent-foreground': 'hsl(0 0% 98%)',
+  '--color-destructive': 'hsl(0 84% 60%)',
+  '--color-destructive-foreground': 'hsl(0 0% 98%)',
+  '--color-border': 'hsl(0 0% 15%)',
+  '--color-input': 'hsl(0 0% 15%)',
+  '--color-ring': 'hsl(217 91% 60%)',
+} as React.CSSProperties;
+
+// Light theme CSS variables
+const lightThemeVars = {
+  // Base HSL values
+  '--background': '0 0% 96%',
+  '--foreground': '0 0% 9%',
+  '--card': '0 0% 100%',
+  '--card-foreground': '0 0% 9%',
+  '--popover': '0 0% 100%',
+  '--popover-foreground': '0 0% 9%',
+  '--primary': '217 91% 60%',
+  '--primary-foreground': '0 0% 100%',
+  '--secondary': '0 0% 9%',
+  '--secondary-foreground': '0 0% 98%',
+  '--muted': '0 0% 96%',
+  '--muted-foreground': '0 0% 40%',
+  '--accent': '0 0% 92%',
+  '--accent-foreground': '0 0% 9%',
+  '--destructive': '0 84% 60%',
+  '--destructive-foreground': '0 0% 98%',
+  '--border': '0 0% 90%',
+  '--input': '0 0% 90%',
+  '--ring': '217 91% 60%',
+  // Tailwind color tokens (used by bg-*, text-*, etc)
+  '--color-background': 'hsl(0 0% 96%)',
+  '--color-foreground': 'hsl(0 0% 9%)',
+  '--color-card': 'hsl(0 0% 100%)',
+  '--color-card-foreground': 'hsl(0 0% 9%)',
+  '--color-primary': 'hsl(217 91% 60%)',
+  '--color-primary-foreground': 'hsl(0 0% 100%)',
+  '--color-secondary': 'hsl(0 0% 9%)',
+  '--color-secondary-foreground': 'hsl(0 0% 98%)',
+  '--color-muted': 'hsl(0 0% 96%)',
+  '--color-muted-foreground': 'hsl(0 0% 40%)',
+  '--color-accent': 'hsl(0 0% 92%)',
+  '--color-accent-foreground': 'hsl(0 0% 9%)',
+  '--color-destructive': 'hsl(0 84% 60%)',
+  '--color-destructive-foreground': 'hsl(0 0% 98%)',
+  '--color-border': 'hsl(0 0% 90%)',
+  '--color-input': 'hsl(0 0% 90%)',
+  '--color-ring': 'hsl(217 91% 60%)',
+} as React.CSSProperties;
+
+export function ForceTheme({ theme, children, className }: ForceThemeProps) {
+  const themeVars = theme === 'dark' ? darkThemeVars : lightThemeVars;
+
+  return (
+    <div
+      className={cn(theme, className)}
+      style={themeVars}
+    >
+      {children}
+    </div>
+  );
+}

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/ThemeProvider.tsx

@@ -0,0 +1,78 @@
+/**
+ * ThemeProvider - Universal theme management
+ *
+ * Re-exports next-themes ThemeProvider with sensible defaults.
+ * Supports light, dark, and system themes with localStorage persistence.
+ *
+ * Framework-agnostic: works in any React app (Electron, Vite, Next.js).
+ *
+ * @example
+ * ```tsx
+ * import { ThemeProvider } from '@djangocfg/ui-core/theme';
+ *
+ * <ThemeProvider
+ *   attribute="class"
+ *   defaultTheme="system"
+ *   enableSystem
+ * >
+ *   {children}
+ * </ThemeProvider>
+ * ```
+ */
+
+'use client';
+
+import { ThemeProvider as NextThemesProvider, useTheme as useNextTheme } from 'next-themes';
+
+import type { ThemeProviderProps as NextThemesProviderProps } from 'next-themes';
+
+// Re-export types
+export type Theme = 'light' | 'dark' | 'system';
+export type ThemeProviderProps = NextThemesProviderProps;
+
+/**
+ * ThemeProvider wraps next-themes with sensible defaults
+ */
+export function ThemeProvider({
+  children,
+  attribute = 'class',
+  defaultTheme = 'system',
+  enableSystem = true,
+  disableTransitionOnChange = true,
+  ...props
+}: ThemeProviderProps) {
+  return (
+    <NextThemesProvider
+      attribute={attribute}
+      defaultTheme={defaultTheme}
+      enableSystem={enableSystem}
+      disableTransitionOnChange={disableTransitionOnChange}
+      {...props}
+    >
+      {children}
+    </NextThemesProvider>
+  );
+}
+
+/**
+ * Hook to access theme context
+ * Returns theme, setTheme, resolvedTheme, systemTheme, and themes
+ */
+export function useThemeContext() {
+  const { theme, setTheme, resolvedTheme, systemTheme, themes } = useNextTheme();
+
+  const toggleTheme = () => {
+    // Toggle between light and dark (ignore system)
+    const currentResolved = resolvedTheme || 'light';
+    setTheme(currentResolved === 'light' ? 'dark' : 'light');
+  };
+
+  return {
+    theme: theme as Theme | undefined,
+    setTheme,
+    resolvedTheme: resolvedTheme as 'light' | 'dark' | undefined,
+    systemTheme: systemTheme as 'light' | 'dark' | undefined,
+    themes,
+    toggleTheme,
+  };
+}

package/src/theme/ThemeToggle.tsx

@@ -0,0 +1,108 @@
+/**
+ * ThemeToggle - Theme switcher component
+ *
+ * Switches between light and dark themes.
+ * Must be used within ThemeProvider.
+ *
+ * @example
+ * ```tsx
+ * import { ThemeToggle } from '@djangocfg/ui-core/theme';
+ *
+ * // Default
+ * <ThemeToggle />
+ *
+ * // Compact (for mobile/tight spaces)
+ * <ThemeToggle size="compact" />
+ *
+ * // Custom className
+ * <ThemeToggle className="ml-auto" />
+ * ```
+ */
+
+'use client';
+
+import { Moon, Sun } from 'lucide-react';
+import { useEffect, useState } from 'react';
+
+import { Button } from '../components/forms/button';
+import { useIsMobile } from '../hooks/media/useMobile';
+import { cn } from '../lib/utils';
+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',
+  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();
+
+  // Prevent hydration mismatch
+  useEffect(() => {
+    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
+        variant="ghost"
+        size="icon"
+        className={cn(buttonSize, className)}
+        disabled
+      >
+        <Sun className={iconSize} />
+        <span className="sr-only">Toggle theme</span>
+      </Button>
+    );
+  }
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      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)}
+    >
+      {showSun ? <Sun className={iconSize} /> : <Moon className={iconSize} />}
+      <span className="sr-only">{isLocked ? lockedTitle : 'Toggle theme'}</span>
+    </Button>
+  );
+}

package/src/theme/index.ts

@@ -0,0 +1,10 @@
+'use client';
+
+export { ThemeProvider, useThemeContext } from './ThemeProvider';
+export type { Theme, ThemeProviderProps } from './ThemeProvider';
+export { ThemeToggle } from './ThemeToggle';
+export type { ThemeToggleProps, ThemeLockBehavior } from './ThemeToggle';
+export { ForceTheme } from './ForceTheme';
+export { ThemeOverride, resolveForcedTheme } from './ThemeOverride';
+export type { ThemeOverrideRule, ThemeOverrideProps, ForcedTheme } from './ThemeOverride';
+export { ForcedThemeProvider, useForcedTheme } from './ForcedThemeContext';