@djangocfg/ui-core 2.1.379 → 2.1.381

package/README.md

@@ -37,9 +37,40 @@ Organized in `components/` by category — everything re-exported from the root
 | **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) |
+| **Boundary** | `Boundary` (React error boundary with `silent`/`inline`/`card`/`fullscreen` variants, `resetKeys`, custom `fallback`) |
 | **Specialized** | `Kbd`, `CopyButton`, `CopyField`, `TokenIcon`, `Item`, `Portal`, `ImageWithFallback`, `Flag`, `LanguageFlag` |
 | **Effects** | `GlowBackground` |
 
+### Boundary
+
+Wrap untrusted subtrees so a single render error does not crash the whole page.
+
+```tsx
+import { Boundary } from '@djangocfg/ui-core';
+
+// non-critical widget — disappears on error, page stays alive
+<Boundary variant="silent"><ChatLauncher /></Boundary>
+
+// inline status — compact alert with Retry
+<Boundary variant="inline" name="catalog-row"><Row /></Boundary>
+
+// feature panel — card with Retry button (default)
+<Boundary><AnalyticsPanel /></Boundary>
+
+// fullscreen — for top-level layouts
+<Boundary variant="fullscreen"><AppShell /></Boundary>
+
+// custom fallback + auto-reset on route change
+<Boundary
+  resetKeys={[pathname]}
+  fallback={({ error, reset }) => <MyErrorCard error={error} onRetry={reset} />}
+>
+  <Page />
+</Boundary>
+```
+
+For automatic reporting to your backend, use `MonitorBoundary` from `@djangocfg/layouts` (it wraps `Boundary` and pushes events through `@djangocfg/monitor/client`).
+
 > Pagination, breadcrumb and sidebar live here (not in ui-nextjs). `SSRPagination` reads URL state through `useLocation` + `useQueryParams`, so it works under any router adapter.
 
 ## Hooks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.379",
+  "version": "2.1.381",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -96,7 +96,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.379",
+    "@djangocfg/i18n": "^2.1.381",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -166,9 +166,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.379",
+    "@djangocfg/i18n": "^2.1.381",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.379",
+    "@djangocfg/typescript-config": "^2.1.381",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/boundary/Boundary.tsx

@@ -0,0 +1,194 @@
+'use client';
+
+import { AlertTriangle, RotateCcw } from 'lucide-react';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+import { isDev } from '../../lib/env';
+import { cn } from '../../lib/utils';
+import { Button } from '../forms/button';
+
+export type BoundaryVariant = 'silent' | 'inline' | 'card' | 'fullscreen';
+
+export interface BoundaryRenderProps {
+  error: Error;
+  reset: () => void;
+}
+
+export interface BoundaryProps {
+  children: ReactNode;
+  /**
+   * Visual style of the fallback.
+   * - silent: render nothing (good for non-critical widgets like a chat launcher)
+   * - inline: compact one-line warning (good for inline blocks inside a page)
+   * - card: bordered card with retry button (good for panels/features)
+   * - fullscreen: centered fullscreen fallback (good for top-level layout)
+   * @default 'card'
+   */
+  variant?: BoundaryVariant;
+  /**
+   * Custom fallback. Receives the caught error and a reset() function.
+   * Overrides `variant` rendering when provided.
+   */
+  fallback?: ReactNode | ((props: BoundaryRenderProps) => ReactNode);
+  /**
+   * Auto-reset the boundary when any of these values change.
+   * Common use: pass the current pathname or a feature id.
+   */
+  resetKeys?: ReadonlyArray<unknown>;
+  /**
+   * Called when an error is caught. Hook up Sentry / logging here.
+   */
+  onError?: (error: Error, info: ErrorInfo) => void;
+  /**
+   * Optional label shown in dev console logs to help locate the source.
+   */
+  name?: string;
+  /**
+   * Extra className for the fallback wrapper (variant: inline / card).
+   */
+  className?: string;
+}
+
+interface BoundaryState {
+  error: Error | null;
+}
+
+function arraysShallowEqual(a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!Object.is(a[i], b[i])) return false;
+  }
+  return true;
+}
+
+export class Boundary extends Component<BoundaryProps, BoundaryState> {
+  state: BoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): BoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info);
+    if (isDev) {
+      const tag = this.props.name ? `[Boundary:${this.props.name}]` : '[Boundary]';
+      console.error(tag, error, info);
+    }
+  }
+
+  componentDidUpdate(prevProps: BoundaryProps) {
+    if (!this.state.error) return;
+    const prevKeys = prevProps.resetKeys;
+    const nextKeys = this.props.resetKeys;
+    if (prevKeys && nextKeys && !arraysShallowEqual(prevKeys, nextKeys)) {
+      this.reset();
+    }
+  }
+
+  reset = () => {
+    this.setState({ error: null });
+  };
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+
+    const { fallback, variant = 'card', className } = this.props;
+
+    if (typeof fallback === 'function') {
+      return fallback({ error, reset: this.reset });
+    }
+    if (fallback !== undefined) {
+      return fallback;
+    }
+
+    return renderVariant(variant, error, this.reset, className);
+  }
+}
+
+function renderVariant(
+  variant: BoundaryVariant,
+  error: Error,
+  reset: () => void,
+  className?: string,
+): ReactNode {
+  if (variant === 'silent') return null;
+
+  const message = isDev ? error.message : null;
+
+  if (variant === 'inline') {
+    return (
+      <div
+        role="alert"
+        className={cn(
+          'flex items-center gap-2 rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2 text-sm text-destructive',
+          className,
+        )}
+      >
+        <AlertTriangle className="h-4 w-4 shrink-0" />
+        <span className="flex-1 truncate">
+          {message ?? 'Something went wrong.'}
+        </span>
+        <button
+          type="button"
+          onClick={reset}
+          className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs font-medium underline-offset-2 hover:underline"
+        >
+          <RotateCcw className="h-3 w-3" />
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  if (variant === 'fullscreen') {
+    return (
+      <div className={cn('flex min-h-screen items-center justify-center bg-background p-4', className)}>
+        <div className="max-w-md w-full space-y-4 text-center">
+          <AlertTriangle className="mx-auto h-10 w-10 text-destructive" />
+          <h1 className="text-2xl font-bold text-foreground">Something went wrong</h1>
+          <p className="text-muted-foreground">
+            We&apos;re sorry, but something unexpected happened. Please try refreshing the page.
+          </p>
+          {message && (
+            <pre className="text-left text-xs text-muted-foreground bg-muted rounded p-2 overflow-auto max-h-40">
+              {message}
+            </pre>
+          )}
+          <div className="flex justify-center gap-2">
+            <Button variant="outline" onClick={reset}>
+              <RotateCcw className="mr-2 h-4 w-4" />
+              Try again
+            </Button>
+            <Button onClick={() => window.location.reload()}>Refresh page</Button>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // card (default)
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'rounded-[var(--radius)] border border-destructive/40 bg-destructive/5 p-4 text-sm',
+        className,
+      )}
+    >
+      <div className="flex items-start gap-3">
+        <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-destructive" />
+        <div className="flex-1 space-y-2">
+          <p className="font-medium text-destructive">Something went wrong</p>
+          {message && (
+            <p className="text-xs text-muted-foreground break-words">{message}</p>
+          )}
+          <Button size="sm" variant="outline" onClick={reset}>
+            <RotateCcw className="mr-2 h-3 w-3" />
+            Try again
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/boundary/boundary.story.tsx

@@ -0,0 +1,109 @@
+import { defineStory, useSelect } from '@djangocfg/playground';
+import { useState } from 'react';
+
+import { Button } from '../forms/button';
+import { Boundary } from '.';
+import type { BoundaryVariant } from '.';
+
+export default defineStory({
+  title: 'Core/Boundary',
+  component: Boundary,
+  description:
+    'React error boundary with multiple visual variants. Wrap untrusted subtrees (widgets, third-party iframes, dynamic renderers) so a single render error does not crash the whole page.',
+});
+
+function BoomButton({ label = 'Throw error' }: { label?: string }) {
+  const [boom, setBoom] = useState(false);
+  if (boom) throw new Error('Demo crash from BoomButton');
+  return (
+    <Button variant="outline" size="sm" onClick={() => setBoom(true)}>
+      {label}
+    </Button>
+  );
+}
+
+export const Interactive = () => {
+  const [variant] = useSelect('variant', {
+    options: ['silent', 'inline', 'card', 'fullscreen'] as const,
+    defaultValue: 'card',
+    label: 'Variant',
+    description: 'Fallback visual style',
+  });
+
+  return (
+    <div className="max-w-lg space-y-3">
+      <p className="text-sm text-muted-foreground">
+        Click the button to throw — the surrounding page stays alive, only this block swaps to the fallback.
+      </p>
+      <Boundary variant={variant as BoundaryVariant} name="story">
+        <div className="rounded-md border p-4">
+          <BoomButton />
+        </div>
+      </Boundary>
+    </div>
+  );
+};
+
+export const Silent = () => (
+  <div className="max-w-lg space-y-2">
+    <p className="text-sm text-muted-foreground">
+      variant=&quot;silent&quot; renders nothing on error. Use for non-critical widgets (chat launcher, embeds).
+    </p>
+    <Boundary variant="silent" name="silent-demo">
+      <BoomButton label="Crash silently" />
+    </Boundary>
+    <p className="text-xs text-muted-foreground">↑ button disappears after click. Page is fine.</p>
+  </div>
+);
+
+export const Inline = () => (
+  <div className="max-w-lg">
+    <Boundary variant="inline" name="inline-demo">
+      <BoomButton />
+    </Boundary>
+  </div>
+);
+
+export const Card = () => (
+  <div className="max-w-lg">
+    <Boundary variant="card" name="card-demo">
+      <BoomButton />
+    </Boundary>
+  </div>
+);
+
+export const CustomFallback = () => (
+  <div className="max-w-lg">
+    <Boundary
+      fallback={({ error, reset }) => (
+        <div className="rounded-md border-2 border-dashed border-amber-500 bg-amber-500/5 p-4">
+          <p className="text-sm font-semibold text-amber-700">Custom fallback</p>
+          <p className="mt-1 text-xs text-amber-700/80">{error.message}</p>
+          <Button size="sm" variant="outline" className="mt-2" onClick={reset}>
+            Reset boundary
+          </Button>
+        </div>
+      )}
+    >
+      <BoomButton />
+    </Boundary>
+  </div>
+);
+
+export const ResetKeys = () => {
+  const [key, setKey] = useState(0);
+  return (
+    <div className="max-w-lg space-y-3">
+      <p className="text-sm text-muted-foreground">
+        Pass <code className="text-xs">resetKeys</code> — when any value in the array changes, the boundary auto-resets.
+        Good for clearing errors on route change.
+      </p>
+      <Button size="sm" onClick={() => setKey((k) => k + 1)}>
+        Bump resetKey ({key})
+      </Button>
+      <Boundary variant="card" resetKeys={[key]} name="resetkeys-demo">
+        <BoomButton />
+      </Boundary>
+    </div>
+  );
+};

package/src/components/boundary/index.ts

@@ -0,0 +1,2 @@
+export { Boundary } from './Boundary';
+export type { BoundaryProps, BoundaryVariant, BoundaryRenderProps } from './Boundary';

package/src/components/index.ts

@@ -162,6 +162,12 @@ export { Preloader, PreloaderSkeleton } from './feedback/preloader';
 export type { PreloaderProps, PreloaderSkeletonProps } from './feedback/preloader';
 export { Toaster } from './feedback/sonner';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Boundary
+// ─────────────────────────────────────────────────────────────────────────────
+export { Boundary } from './boundary';
+export type { BoundaryProps, BoundaryVariant, BoundaryRenderProps } from './boundary';
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Specialized
 // ─────────────────────────────────────────────────────────────────────────────