@djangocfg/ui-core 2.1.394 → 2.1.397

package/README.md

@@ -76,6 +76,7 @@ import { useNavigate, useLocation, useQueryParams, useRouter, useIsActive } from
 | **Theme** | `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 |
 | **Feedback** | `useToast`, `toast` (Sonner) |
 | **Debug** | `useDebugTools` |
 
@@ -170,6 +171,19 @@ Lower level: `createSoundBus<E>({ sounds, getMuted, getVolume, isEnabled })` exp
 
 For an opinionated, fully-wired example with bundled audio assets see `useChatAudio` in [`@djangocfg/ui-tools`](../../ui-tools/src/tools/Chat/README.md#audio) — it inlines six notification mp3s into the lazy chat chunk as `data:`-URLs so consumers need no asset setup.
 
+## Cross-tab coordination
+
+```tsx
+import { useActiveTab, useIsTabLeader } from '@djangocfg/ui-core/hooks';
+
+const { isActive, isLeader, tabId } = useActiveTab();
+// isActive  — this tab has user focus (visibilitychange + focus/blur)
+// isLeader  — elected leader among open tabs (stable; oldest tab wins)
+// tabId     — stable per-tab id (sessionStorage, survives in-tab reload)
+```
+
+Single shared coordinator over `BroadcastChannel` — leader election runs locally on every tab from the same peer-set view, no server. Use the leader flag to dedupe side-effects across tabs: only the leader mutates `document.title` / favicon, holds the websocket, plays a sound; followers stay silent but still read state. Zustand-backed, SSR-safe, single-tab fallback when `BroadcastChannel` is unavailable.
+
 ## Schema-driven configurators
 
 `@djangocfg/ui-core/lib` exports a portable JSON Schema 7 subset (`CustomJsonSchema7`, `CustomJsonUiSchema7`, `CustomJsonUiGroup`, `CustomJsonUiDisabledWhenRule`) for packages that ship configurator schemas without taking a runtime dependency on RJSF.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.394",
+  "version": "2.1.397",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -90,7 +90,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.394",
+    "@djangocfg/i18n": "^2.1.397",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -160,8 +160,8 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.394",
-    "@djangocfg/typescript-config": "^2.1.394",
+    "@djangocfg/i18n": "^2.1.397",
+    "@djangocfg/typescript-config": "^2.1.397",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/effects/GlowBackground.tsx

@@ -40,7 +40,7 @@ export const GlowBackground = React.memo(({ className }: GlowBackgroundProps) =>
       width: 700,
       height: 700,
       borderRadius: '50%',
-      background: 'radial-gradient(circle, hsl(var(--primary) / 0.45) 0%, transparent 70%)',
+      background: 'radial-gradient(circle, color-mix(in oklab, var(--primary) 45%, transparent) 0%, transparent 70%)',
       filter: 'blur(80px)',
       animation: 'blob 10s ease-in-out infinite',
     }} />

package/src/components/navigation/sidebar/sidebar.tsx

@@ -201,7 +201,7 @@ const Sidebar = React.forwardRef<
               )}
               style={
                 {
-                  backgroundColor: "hsl(var(--sidebar-background))",
+                  backgroundColor: "var(--sidebar-background)",
                 } as React.CSSProperties
               }
             >
@@ -289,8 +289,8 @@ const Sidebar = React.forwardRef<
                 aria-hidden
                 className={cn(
                   "pointer-events-none absolute inset-y-0 right-0 z-[1] w-px",
-                  "bg-[linear-gradient(180deg,hsl(var(--sidebar-border)_/_0.02)_0%,hsl(var(--sidebar-border)_/_0.22)_18%,hsl(var(--sidebar-border)_/_0.4)_50%,hsl(var(--sidebar-border)_/_0.2)_82%,hsl(var(--sidebar-border)_/_0.03)_100%)]",
-                  "dark:bg-[linear-gradient(180deg,hsl(var(--sidebar-border)_/_0.08)_0%,hsl(var(--sidebar-border)_/_0.34)_22%,hsl(var(--sidebar-border)_/_0.55)_50%,hsl(var(--sidebar-border)_/_0.28)_78%,hsl(var(--sidebar-border)_/_0.06)_100%)]"
+                  "bg-[linear-gradient(180deg,color-mix(in_oklab,var(--sidebar-border)_2%,transparent)_0%,color-mix(in_oklab,var(--sidebar-border)_22%,transparent)_18%,color-mix(in_oklab,var(--sidebar-border)_40%,transparent)_50%,color-mix(in_oklab,var(--sidebar-border)_20%,transparent)_82%,color-mix(in_oklab,var(--sidebar-border)_3%,transparent)_100%)]",
+                  "dark:bg-[linear-gradient(180deg,color-mix(in_oklab,var(--sidebar-border)_8%,transparent)_0%,color-mix(in_oklab,var(--sidebar-border)_34%,transparent)_22%,color-mix(in_oklab,var(--sidebar-border)_55%,transparent)_50%,color-mix(in_oklab,var(--sidebar-border)_28%,transparent)_78%,color-mix(in_oklab,var(--sidebar-border)_6%,transparent)_100%)]"
                 )}
               />
             )}
@@ -610,7 +610,7 @@ const sidebarMenuButtonVariants = cva(
       variant: {
         default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
         outline:
-          "bg-background shadow-[0_0_0_1px_hsl(var(--sidebar-border))] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_hsl(var(--sidebar-accent))]",
+          "bg-background shadow-[0_0_0_1px_var(--sidebar-border)] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_var(--sidebar-accent)]",
       },
       size: {
         default: "h-8 text-sm",

package/src/hooks/index.ts

@@ -21,6 +21,7 @@ export * from './events';
 export * from './hotkey';
 export * from './audio';
 export * from './debug';
+export * from './tabs';
 
 // ----------------------------------------------------------------------------
 // Router — framework-agnostic navigation primitives.

package/src/hooks/tabs/activeTabStore.ts

@@ -0,0 +1,167 @@
+'use client';
+
+import { create } from 'zustand';
+
+import { getTabId } from './tabId';
+
+/**
+ * Cross-tab coordination store. Singleton, lazily initialised on the
+ * first hook subscription.
+ *
+ * Two orthogonal concepts:
+ *   - `isActive` — this tab has user focus right now (visibilitychange
+ *     + focus/blur).
+ *   - `isLeader` — among open tabs of this app, this tab won the
+ *     election. Leadership is stable; it only changes when the current
+ *     leader closes/refreshes.
+ *
+ * Election protocol over a single BroadcastChannel:
+ *   on mount:
+ *     - announce HELLO with our tabId
+ *     - listen for HELLO/CLAIM/BYE
+ *   on HELLO from a peer:
+ *     - if we think we're leader, reply CLAIM (so the newcomer learns
+ *       the current leader without forcing a re-election)
+ *   on CLAIM from a peer:
+ *     - record their tabId in the peer set; the smallest tabId wins
+ *       (tabIds are time-prefixed so smallest == oldest)
+ *   on BYE (beforeunload):
+ *     - remove peer; if it was the leader, re-elect locally
+ *
+ * Leader election runs locally on each tab from the same peer-set view,
+ * so all tabs converge on the same answer without a coordinator.
+ */
+
+export type ActiveTabMessage =
+  | { type: 'hello'; tabId: string }
+  | { type: 'claim'; tabId: string }
+  | { type: 'bye'; tabId: string };
+
+interface ActiveTabState {
+  /** Stable id for the current tab. */
+  tabId: string;
+  /** This tab has user focus. */
+  isActive: boolean;
+  /** This tab is the elected leader among open tabs. */
+  isLeader: boolean;
+  /** Currently elected leader id (may be this tab or another). */
+  leaderId: string;
+  /** All tabs we've seen, including ourselves. */
+  peers: string[];
+}
+
+const CHANNEL_NAME = 'djangocfg:active-tab';
+
+const initialId = getTabId();
+
+export const useActiveTabStore = create<ActiveTabState>(() => ({
+  tabId: initialId,
+  isActive: typeof document !== 'undefined' ? !document.hidden : true,
+  isLeader: true, // Optimistic — corrected by election on first peer HELLO.
+  leaderId: initialId,
+  peers: [initialId],
+}));
+
+let initialised = false;
+let channel: BroadcastChannel | null = null;
+let visibilityTeardown: (() => void) | null = null;
+
+function elect(peers: string[]): string {
+  // Smallest tabId wins. tabIds are time-prefixed; smallest == oldest.
+  return peers.slice().sort()[0]!;
+}
+
+function applyPeers(nextPeers: string[]) {
+  const me = useActiveTabStore.getState().tabId;
+  const peers = Array.from(new Set([me, ...nextPeers])).sort();
+  const leaderId = elect(peers);
+  useActiveTabStore.setState({
+    peers,
+    leaderId,
+    isLeader: leaderId === me,
+  });
+}
+
+function post(msg: ActiveTabMessage) {
+  channel?.postMessage(msg);
+}
+
+function setupVisibility(): () => void {
+  if (typeof document === 'undefined') return () => {};
+
+  const sync = () => {
+    const hidden = document.hidden || (
+      typeof document.hasFocus === 'function' && !document.hasFocus()
+    );
+    useActiveTabStore.setState({ isActive: !hidden });
+  };
+
+  sync();
+  document.addEventListener('visibilitychange', sync);
+  window.addEventListener('focus', sync);
+  window.addEventListener('blur', sync);
+
+  return () => {
+    document.removeEventListener('visibilitychange', sync);
+    window.removeEventListener('focus', sync);
+    window.removeEventListener('blur', sync);
+  };
+}
+
+/**
+ * Idempotent — first call wires up the channel and listeners, later
+ * calls are no-ops. Called automatically by `useActiveTab` on mount.
+ * Exposed for hosts that want to warm the coordinator before any hook
+ * subscribes (e.g. inside an app shell).
+ */
+export function ensureActiveTabCoordinator(): void {
+  if (initialised) return;
+  initialised = true;
+
+  visibilityTeardown = setupVisibility();
+
+  if (typeof BroadcastChannel === 'undefined') {
+    // Single-tab fallback: we are trivially the leader.
+    return;
+  }
+
+  channel = new BroadcastChannel(CHANNEL_NAME);
+  const me = useActiveTabStore.getState().tabId;
+
+  channel.addEventListener('message', (e) => {
+    const msg = e.data as ActiveTabMessage | undefined;
+    if (!msg || typeof msg !== 'object') return;
+
+    const { peers: currentPeers } = useActiveTabStore.getState();
+
+    if (msg.type === 'hello') {
+      // Acknowledge the newcomer with a CLAIM so they learn about us.
+      applyPeers([...currentPeers, msg.tabId]);
+      post({ type: 'claim', tabId: me });
+    } else if (msg.type === 'claim') {
+      applyPeers([...currentPeers, msg.tabId]);
+    } else if (msg.type === 'bye') {
+      applyPeers(currentPeers.filter((id) => id !== msg.tabId));
+    }
+  });
+
+  // Announce ourselves.
+  post({ type: 'hello', tabId: me });
+
+  const onUnload = () => post({ type: 'bye', tabId: me });
+  window.addEventListener('beforeunload', onUnload);
+  window.addEventListener('pagehide', onUnload);
+}
+
+/**
+ * Tear down everything (channel, listeners). Tests only — production
+ * tabs live and die with the page.
+ */
+export function disposeActiveTabCoordinator(): void {
+  if (!initialised) return;
+  initialised = false;
+  channel?.close();
+  channel = null;
+  visibilityTeardown?.();
+  visibilityTeardown = null;
+}

package/src/hooks/tabs/index.ts

@@ -0,0 +1,17 @@
+'use client';
+
+export {
+  useActiveTab,
+  useIsTabActive,
+  useIsTabLeader,
+  type UseActiveTabReturn,
+} from './useActiveTab';
+
+export {
+  useActiveTabStore,
+  ensureActiveTabCoordinator,
+  disposeActiveTabCoordinator,
+  type ActiveTabMessage,
+} from './activeTabStore';
+
+export { getTabId } from './tabId';

package/src/hooks/tabs/tabId.ts

@@ -0,0 +1,44 @@
+/**
+ * Stable per-tab identifier. Persisted in sessionStorage so a single
+ * tab keeps its id across in-tab reloads (Cmd-R) but a new tab gets a
+ * fresh one. Falls back to an in-memory id when sessionStorage is
+ * unavailable (private mode, sandboxed iframes, SSR).
+ *
+ * The id includes `performance.timeOrigin` so leader election can
+ * prefer the longest-lived tab without an extra "born_at" field —
+ * lexicographic ordering of the id matches age ordering closely enough
+ * for our purposes (ties broken by random suffix).
+ */
+
+const KEY = 'djangocfg:tab-id';
+
+let cached: string | null = null;
+
+function makeId(): string {
+  const origin = typeof performance !== 'undefined' ? performance.timeOrigin : Date.now();
+  const rand = Math.random().toString(36).slice(2, 10);
+  // Zero-padded so string compare matches numeric compare.
+  return `${Math.floor(origin).toString(10).padStart(16, '0')}-${rand}`;
+}
+
+export function getTabId(): string {
+  if (cached) return cached;
+  if (typeof sessionStorage === 'undefined') {
+    cached = makeId();
+    return cached;
+  }
+  try {
+    const existing = sessionStorage.getItem(KEY);
+    if (existing) {
+      cached = existing;
+      return existing;
+    }
+    const next = makeId();
+    sessionStorage.setItem(KEY, next);
+    cached = next;
+    return next;
+  } catch {
+    cached = makeId();
+    return cached;
+  }
+}

package/src/hooks/tabs/useActiveTab.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useShallow } from 'zustand/react/shallow';
+
+import {
+  ensureActiveTabCoordinator,
+  useActiveTabStore,
+} from './activeTabStore';
+
+export interface UseActiveTabReturn {
+  /** Stable id for this tab. Survives in-tab reload, dies with the tab. */
+  tabId: string;
+  /** True while the user has focus on this tab. */
+  isActive: boolean;
+  /** True when this tab is the elected leader across all open app tabs. */
+  isLeader: boolean;
+  /** Current leader id (may be this tab or another). */
+  leaderId: string;
+}
+
+/**
+ * Subscribe to cross-tab state: focus + leader election.
+ *
+ * Use cases:
+ *   - Only the leader mutates `document.title` / favicon to avoid all
+ *     open tabs blinking in unison.
+ *   - Only the leader holds a websocket; followers consume snapshots
+ *     via broadcast.
+ *   - `isActive` for "the user is watching this exact tab" gating.
+ *
+ * The coordinator is shared across every consumer in the app — calling
+ * the hook in multiple components costs only a store subscription.
+ */
+export function useActiveTab(): UseActiveTabReturn {
+  useEffect(() => {
+    ensureActiveTabCoordinator();
+  }, []);
+
+  return useActiveTabStore(
+    useShallow((s) => ({
+      tabId: s.tabId,
+      isActive: s.isActive,
+      isLeader: s.isLeader,
+      leaderId: s.leaderId,
+    })),
+  );
+}
+
+/** Subscribe to just the `isActive` flag — no leader-election reads. */
+export function useIsTabActive(): boolean {
+  useEffect(() => {
+    ensureActiveTabCoordinator();
+  }, []);
+  return useActiveTabStore((s) => s.isActive);
+}
+
+/** Subscribe to just the `isLeader` flag. */
+export function useIsTabLeader(): boolean {
+  useEffect(() => {
+    ensureActiveTabCoordinator();
+  }, []);
+  return useActiveTabStore((s) => s.isLeader);
+}