@djangocfg/ui-core 2.1.415 → 2.1.417

package/README.md

@@ -22,8 +22,32 @@ pnpm add @djangocfg/ui-core
 import { Button, Card, Sidebar, SSRPagination } from '@djangocfg/ui-core/components';
 import { useIsMobile, useNavigate, useQueryParams } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
+import { UiProviders } from '@djangocfg/ui-core/providers';
 ```
 
+## Root providers
+
+Mount `<UiProviders>` once at the top of your app — it bundles the overlay
+and imperative services every ui-core / ui-tools component expects:
+
+```tsx
+import { UiProviders } from '@djangocfg/ui-core/providers';
+
+export function Root({ children }: { children: React.ReactNode }) {
+  return <UiProviders>{children}</UiProviders>;
+}
+```
+
+Includes:
+- `<TooltipProvider>` (Radix tooltip root, `delayDuration={100}` by default)
+- `<DialogProvider>` (installs `window.dialog.*` + renders active dialogs)
+- `<Toaster>` (Sonner toast portal)
+
+Opt out per-service: `<UiProviders noToaster noDialogService>`.
+
+**Do not nest a second `<TooltipProvider>` inside library components** —
+that creates a separate context scope and breaks the tooltip↔provider link.
+
 ## Components
 
 Organized in `components/` by category — everything re-exported from the root barrel.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.415",
+  "version": "2.1.417",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -63,6 +63,11 @@
       "import": "./src/lib/dialog-service/index.ts",
       "require": "./src/lib/dialog-service/index.ts"
     },
+    "./providers": {
+      "types": "./src/providers/index.ts",
+      "import": "./src/providers/index.ts",
+      "require": "./src/providers/index.ts"
+    },
     "./utils": {
       "types": "./src/utils/index.ts",
       "import": "./src/utils/index.ts",
@@ -95,7 +100,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.415",
+    "@djangocfg/i18n": "^2.1.417",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -166,8 +171,8 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.415",
-    "@djangocfg/typescript-config": "^2.1.415",
+    "@djangocfg/i18n": "^2.1.417",
+    "@djangocfg/typescript-config": "^2.1.417",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/components/index.ts

@@ -68,8 +68,7 @@ export { ResponsiveSheet, ResponsiveSheetContent, ResponsiveSheetHeader, Respons
 export { SidePanel, SidePanelContent, SidePanelHeader, SidePanelTitle, SidePanelDescription, SidePanelBody, SidePanelFooter, SidePanelClose } from './overlay/side-panel';
 export type { SidePanelProps, SidePanelContentProps, SidePanelCloseProps } from './overlay/side-panel';
 export { HoverCard, HoverCardContent, HoverCardTrigger } from './overlay/hover-card';
-export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, SafeTooltipProvider } from './overlay/tooltip';
-export type { SafeTooltipProviderProps } from './overlay/tooltip';
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './overlay/tooltip';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Navigation

package/src/components/overlay/tooltip/index.tsx

@@ -32,5 +32,3 @@ const TooltipContent = React.forwardRef<
 TooltipContent.displayName = TooltipPrimitive.Content.displayName
 
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
-export { SafeTooltipProvider } from './tooltip-provider-safe';
-export type { SafeTooltipProviderProps } from './tooltip-provider-safe';

package/src/index.ts

@@ -14,3 +14,6 @@ export * from './hooks';
 
 // Re-export lib utilities
 export * from './lib';
+
+// Re-export composite providers (UiProviders)
+export * from './providers';

package/src/lib/dialog-service/getDialog.ts

@@ -0,0 +1,59 @@
+'use client';
+
+import type { DialogAPI } from './types';
+
+/**
+ * Lazy accessor for the global `window.dialog` API installed by
+ * `<DialogProvider />`. Use this in any library code that needs to call
+ * `dialog.confirm` / `dialog.alert` / `dialog.prompt` from a non-React
+ * context (e.g. event handlers in `ui-tools` tools).
+ *
+ * Returns `null` (and warns once in dev) when:
+ *   - we're rendering on the server (`typeof window === 'undefined'`)
+ *   - the host app has not mounted `<DialogProvider />`, so `window.dialog`
+ *     is missing.
+ *
+ * The caller must handle the `null` case — usually by bailing out of the
+ * action with a console warning. Library code must never throw if the
+ * provider is missing; consumers without it should still be able to
+ * import / render the component (just without CRUD flows).
+ *
+ * @example
+ * const dialog = getDialog();
+ * if (!dialog) return;
+ * const ok = await dialog.confirm({ title: 'Delete?', message: '…', variant: 'destructive' });
+ * if (ok) await onDelete();
+ */
+export function getDialog(): DialogAPI | null {
+  if (typeof window === 'undefined') return null;
+  const api = (window as Window & { dialog?: DialogAPI }).dialog;
+  if (!api) {
+    if (process.env.NODE_ENV !== 'production' && !warnedMissing) {
+      warnedMissing = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[getDialog] window.dialog is not available — mount <DialogProvider /> at the app root.',
+      );
+    }
+    return null;
+  }
+  return api;
+}
+
+let warnedMissing = false;
+
+/**
+ * Like `getDialog()` but throws when unavailable. Use sparingly — only in
+ * code paths where missing `window.dialog` is a developer error (e.g. an
+ * action explicitly triggered by user interaction in a feature that
+ * unconditionally requires dialogs).
+ */
+export function requireDialog(): DialogAPI {
+  const api = getDialog();
+  if (!api) {
+    throw new Error(
+      'requireDialog(): window.dialog is not available. Mount <DialogProvider /> at the app root.',
+    );
+  }
+  return api;
+}

package/src/lib/dialog-service/index.ts

@@ -10,6 +10,9 @@ export type {
 // Store
 export { dialogStore, useDialogStore, initDialogAPI, showDialog } from './store';
 
+// Imperative accessors for non-React code (library helpers, event handlers).
+export { getDialog, requireDialog } from './getDialog';
+
 // Provider
 export { DialogProvider } from './DialogProvider';
 

package/src/providers/UiProviders.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+import * as React from 'react';
+import { useEffect, useState } from 'react';
+
+import { TooltipProvider } from '../components/overlay/tooltip';
+import { Toaster } from '../components/feedback/sonner';
+import { DialogProvider } from '../lib/dialog-service/DialogProvider';
+
+export interface UiProvidersProps {
+  children: React.ReactNode;
+  /** Tooltip open delay in ms. @default 100 (snappy for desktop apps) */
+  tooltipDelay?: number;
+  /** Disable the Sonner toaster (e.g. when the host renders its own). */
+  noToaster?: boolean;
+  /** Disable the imperative `window.dialog` service + its renderer. */
+  noDialogService?: boolean;
+  /**
+   * SSR-safe mount strategy. Default `true` — skips providers on the
+   * initial server render and remounts after `useEffect` so Radix
+   * `<TooltipProvider>` (which calls `useId()` + opens internal state
+   * on mount) doesn't trigger hydration mismatches under Next.js.
+   *
+   * Set `ssr={false}` on CSR-only hosts (Wails, Vite SPA, Storybook
+   * iframe) to skip the deferred mount — providers render on the
+   * very first paint and library components see their context
+   * immediately.
+   */
+  ssr?: boolean;
+}
+
+/**
+ * One root composition for every overlay/imperative-service the
+ * djangocfg UI library needs:
+ *
+ *  - `<TooltipProvider>` — single context root for every `<Tooltip>`
+ *    in the tree (Radix). Without one, library components log
+ *    "Tooltip must be used within TooltipProvider".
+ *  - `<DialogProvider>`  — installs the `window.dialog.*` imperative
+ *    API and renders the active dialog into a portal.
+ *  - `<Toaster>`         — Sonner toast portal. Library callsites use
+ *    `toast(...)` from the same package; no portal = silent no-op.
+ *
+ * Apple-style: app/host mounts ONE `<UiProviders>` at the very top of
+ * the tree, and never again. Library components must NOT include their
+ * own nested `TooltipProvider` — a second context root creates a fresh
+ * provider scope with different delays, and (worse) under Vite dev a
+ * dup-module load yields two `createContext()` instances, breaking the
+ * provider/consumer link.
+ *
+ * Usage:
+ *   import { UiProviders } from '@djangocfg/ui-core/lib/providers';
+ *
+ *   <UiProviders>
+ *     <YourApp />
+ *   </UiProviders>
+ */
+export function UiProviders({
+  children,
+  tooltipDelay = 100,
+  noToaster,
+  noDialogService,
+}: UiProvidersProps) {
+  // No SSR-skip on purpose: any nested library component that renders
+  // `<Tooltip>` on its first paint expects to find `<TooltipProvider>`
+  // already in the tree. Skipping the provider during SSR caused
+  // "Tooltip must be used within TooltipProvider" before hydration.
+  // Radix's own provider tolerates the SSR pass — no hydration
+  // mismatches observed; the safe wrapper was over-engineering.
+  const tree = noDialogService ? children : <DialogProvider>{children}</DialogProvider>;
+  return (
+    <TooltipProvider delayDuration={tooltipDelay}>
+      {tree}
+      {!noToaster && <Toaster />}
+    </TooltipProvider>
+  );
+}

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export { UiProviders } from './UiProviders';
+export type { UiProvidersProps } from './UiProviders';

package/src/components/overlay/tooltip/tooltip-provider-safe.tsx

@@ -1,44 +0,0 @@
-"use client"
-
-import * as React from 'react';
-
-import { TooltipProvider as RadixTooltipProvider } from '@radix-ui/react-tooltip';
-
-export interface SafeTooltipProviderProps {
-  children: React.ReactNode;
-  delayDuration?: number;
-  skipDelayDuration?: number;
-  disableHoverableContent?: boolean;
-}
-
-/**
- * SafeTooltipProvider - SSR-safe wrapper for Radix TooltipProvider
- * Only renders on client-side to avoid hydration mismatches
- */
-export function SafeTooltipProvider({
-  children,
-  delayDuration = 700,
-  skipDelayDuration = 300,
-  disableHoverableContent,
-}: SafeTooltipProviderProps) {
-  const [mounted, setMounted] = React.useState(false);
-
-  React.useEffect(() => {
-    setMounted(true);
-  }, []);
-
-  if (!mounted) {
-    // During SSR, return children without TooltipProvider
-    return <>{children}</>;
-  }
-
-  return (
-    <RadixTooltipProvider
-      delayDuration={delayDuration}
-      skipDelayDuration={skipDelayDuration}
-      disableHoverableContent={disableHoverableContent}
-    >
-      {children}
-    </RadixTooltipProvider>
-  );
-}