@djangocfg/ui-core 2.1.380 → 2.1.382

package/src/components/boundary/README.md

@@ -0,0 +1,249 @@
+# Boundary
+
+React error boundary primitive with four visual variants, a `useBoundary()` hook for async errors, and safe-by-default behaviour (no infinite loops, normalized errors, accessible fallbacks).
+
+Designed as a drop-in replacement for `react-error-boundary` with batteries included: built-in fallback variants, dev logging, optional context-based escape hatch.
+
+---
+
+## When to use
+
+| Situation | Component |
+|---|---|
+| Wrap a non-critical widget (chat launcher, embed, ad) | `<Boundary variant="silent">` |
+| Wrap a row / inline block (table cell, list item) | `<Boundary variant="inline">` |
+| Wrap a feature panel (analytics card, settings group) | `<Boundary>` (card, default) |
+| Wrap an entire screen / root layout | `<Boundary variant="fullscreen">` |
+| Page/layout level with backend reporting | `<MonitorBoundary>` from `@djangocfg/layouts` |
+
+**Granularity matters.** One global boundary at the app root hides bugs and ruins UX (whole page = error screen). Prefer many small per-feature boundaries.
+
+---
+
+## Basic usage
+
+```tsx
+import { Boundary } from '@djangocfg/ui-core';
+
+<Boundary variant="card" name="dashboard-stats">
+  <StatsPanel />
+</Boundary>
+```
+
+The `name` prop is used in dev console logs — set it to something findable.
+
+---
+
+## Variants
+
+```tsx
+<Boundary variant="silent">…</Boundary>      // renders null on error
+<Boundary variant="inline">…</Boundary>      // compact one-line alert + Retry
+<Boundary variant="card">…</Boundary>        // bordered card with Retry (default)
+<Boundary variant="fullscreen">…</Boundary>  // centered fullscreen + Refresh page
+```
+
+All visible variants get `role="alert"` and `aria-live="assertive"` so screen readers announce them.
+
+---
+
+## Custom fallback
+
+Two forms — pick by use case:
+
+```tsx
+// Render-prop: simple inline cases
+<Boundary fallback={({ error, reset }) => <MyError onRetry={reset} />}>…</Boundary>
+
+// Component: better for memoization / testing
+function MyFallback({ error, errorInfo, reset }: BoundaryRenderProps) {
+  return <ErrorCard message={error.message} onRetry={reset} />;
+}
+<Boundary FallbackComponent={MyFallback}>…</Boundary>
+```
+
+`fallback` (function form) takes precedence over `FallbackComponent`. Both receive `{ error, errorInfo, reset }`.
+
+---
+
+## Reset patterns
+
+### 1. Auto-reset on route change
+
+```tsx
+const pathname = usePathname();
+<Boundary resetKeys={[pathname]}>{children}</Boundary>
+```
+
+When any value in `resetKeys` changes (shallow `Object.is` per index), the boundary clears its error state.
+
+**⚠ Anti-pattern:** `resetKeys={[Math.random()]}` or `resetKeys={[{}, []]}` causes an infinite reset loop because the array contents change on every render.
+
+### 2. React Query / refetch on recovery
+
+```tsx
+<Boundary
+  onReset={({ reason }) => {
+    // reason === 'imperative' (Retry button) or 'keys' (resetKeys changed)
+    queryClient.invalidateQueries({ queryKey: ['dashboard'] });
+  }}
+>
+  <Dashboard />
+</Boundary>
+```
+
+`onReset` is called in a microtask **after** state is cleared — your refetch sees a fresh component.
+
+### 3. Full remount (rare)
+
+If you need to fully discard component state (not just the error), use React's `key` prop instead:
+
+```tsx
+<Boundary key={feature.id} resetKeys={[feature.id]}>…</Boundary>
+```
+
+---
+
+## Async / event-handler errors
+
+**React error boundaries do not catch async errors.** That's a React limitation, not a bug.
+
+Use `useBoundary()` to push them into the nearest boundary:
+
+```tsx
+import { useBoundary } from '@djangocfg/ui-core';
+
+function LoadButton() {
+  const { showBoundary, resetBoundary } = useBoundary();
+
+  return (
+    <Button onClick={async () => {
+      try {
+        await api.loadData();
+      } catch (err) {
+        showBoundary(err);  // bubbles up to the closest <Boundary>
+      }
+    }}>
+      Load
+    </Button>
+  );
+}
+```
+
+`useBoundary()` works inside any component rendered under a `<Boundary>`. Throws if used outside one.
+
+---
+
+## Logging
+
+By default, caught errors are logged with `console.error` in development and silenced in production. Wire to your telemetry by passing `logger` or `onError`:
+
+```tsx
+<Boundary
+  onError={(error, info) => {
+    Sentry.captureException(error, { extra: { componentStack: info.componentStack } });
+  }}
+>
+  …
+</Boundary>
+```
+
+Or use `MonitorBoundary` from `@djangocfg/layouts` for automatic reporting to `@djangocfg/monitor`.
+
+---
+
+## Safety guarantees
+
+- **Fallback can throw safely.** If the user's fallback render itself errors, the boundary degrades to a minimal static alert instead of looping forever.
+- **`onError` / `onReset` can throw safely.** Caught and logged via `logger`. Won't crash the boundary.
+- **Non-`Error` throws are normalized.** `throw 'oops'`, `throw { code: 500 }` and bare objects become real `Error` instances with stack traces (where possible).
+- **No duplicate `onError` calls.** Internal tracking prevents firing twice for the same error instance.
+- **Reset clears state before `onReset`.** Errors thrown inside `onReset` don't re-trigger the just-cleared boundary.
+
+---
+
+## Pairing with `<Suspense>`
+
+Put `<Boundary>` **outside** `<Suspense>` — otherwise errors thrown by a suspended component bubble past it.
+
+```tsx
+<Boundary variant="card">
+  <Suspense fallback={<Spinner />}>
+    <DataPanel />
+  </Suspense>
+</Boundary>
+```
+
+---
+
+## Edge cases & gotchas
+
+| Issue | Cause | Solution |
+|---|---|---|
+| Boundary doesn't catch error | Error thrown in async code / event handler | Use `useBoundary().showBoundary(err)` |
+| Boundary doesn't catch error (SSR) | `componentDidCatch` doesn't run on server | Errors are caught on client hydration. For SSR-only errors, use Next.js `error.tsx` |
+| Infinite reset loop | `resetKeys` contains unstable values | Don't put new objects/arrays/random in `resetKeys` |
+| Fallback renders briefly with stale data | React 18 concurrent rendering / `useDeferredValue` | Expected — the boundary unmounts children on error |
+| `error.stack` is missing | Code threw a non-`Error` value | Boundary normalizes, but stack is reconstructed from current line. Prefer `throw new Error(...)` |
+| Component stack only in dev | React strips it in prod by default | Use `onError`'s `info.componentStack` server-side via monitor |
+
+---
+
+## API
+
+```ts
+interface BoundaryProps {
+  children: ReactNode;
+  variant?: 'silent' | 'inline' | 'card' | 'fullscreen';  // default 'card'
+  fallback?: ReactNode | ((props: BoundaryRenderProps) => ReactNode);
+  FallbackComponent?: ComponentType<BoundaryRenderProps>;
+  resetKeys?: ReadonlyArray<unknown>;
+  onError?: (error: Error, info: ErrorInfo) => void;
+  onReset?: (details: BoundaryResetDetails) => void;
+  name?: string;           // dev log tag
+  className?: string;      // fallback wrapper className
+  logger?: BoundaryLogger; // override default console.error in dev
+}
+
+interface BoundaryRenderProps {
+  error: Error;
+  errorInfo: ErrorInfo | null;
+  reset: () => void;
+}
+
+interface BoundaryResetDetails {
+  reason: 'imperative' | 'keys';
+  prevResetKeys?: ReadonlyArray<unknown>;
+  nextResetKeys?: ReadonlyArray<unknown>;
+}
+
+function useBoundary(): {
+  showBoundary: (error: unknown) => void;
+  resetBoundary: () => void;
+};
+```
+
+---
+
+## Comparison with `react-error-boundary`
+
+| Feature | `react-error-boundary` | `@djangocfg/ui-core` `Boundary` |
+|---|---|---|
+| `fallback` / `fallbackRender` / `FallbackComponent` | ✅ separate props | ✅ unified: `fallback` (node or fn) + `FallbackComponent` |
+| `resetKeys` | ✅ | ✅ (shallow `Object.is` per index) |
+| `onError` | ✅ | ✅ |
+| `onReset` | ✅ | ✅ (with `reason` + prev/next keys) |
+| `useErrorBoundary()` / `useBoundary()` | ✅ | ✅ |
+| Built-in visual variants | ❌ | ✅ silent / inline / card / fullscreen |
+| Safe fallback rendering | ❌ (can loop) | ✅ |
+| `onError` / `onReset` thrown errors caught | ❌ | ✅ |
+| Non-Error normalization | ❌ | ✅ |
+| Accessible defaults (`role`, `aria-live`) | ❌ | ✅ |
+| Backend telemetry integration | manual | `MonitorBoundary` wrapper |
+
+---
+
+## Related
+
+- **`MonitorBoundary`** (`@djangocfg/layouts`) — wraps `Boundary` and reports to `@djangocfg/monitor` automatically.
+- **Next.js `error.tsx`** — handles route-level errors. Use `Boundary` *inside* pages for finer granularity.

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

@@ -0,0 +1,191 @@
+import { defineStory, useSelect } from '@djangocfg/playground';
+import { useState } from 'react';
+
+import { Button } from '../forms/button';
+import { Boundary, useBoundary } from '.';
+import type { BoundaryRenderProps, 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. Includes `useBoundary()` hook for async / event-handler errors.',
+});
+
+function BoomButton({ label = 'Throw render 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>
+);
+
+function MyFallback({ error, reset }: BoundaryRenderProps) {
+  return (
+    <div className="rounded-md border border-blue-500/40 bg-blue-500/5 p-4">
+      <p className="text-sm font-semibold text-blue-700">FallbackComponent prop</p>
+      <p className="mt-1 text-xs text-blue-700/80">{error.message}</p>
+      <Button size="sm" variant="outline" className="mt-2" onClick={reset}>
+        Reset
+      </Button>
+    </div>
+  );
+}
+
+export const FallbackComponentProp = () => (
+  <div className="max-w-lg space-y-2">
+    <p className="text-sm text-muted-foreground">
+      Pass a component type instead of a render function — better memoization, easier to test.
+    </p>
+    <Boundary FallbackComponent={MyFallback}>
+      <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 (e.g. <code className="text-xs">[pathname]</code>).
+      </p>
+      <Button size="sm" onClick={() => setKey((k) => k + 1)}>
+        Bump resetKey ({key})
+      </Button>
+      <Boundary variant="card" resetKeys={[key]} name="resetkeys-demo">
+        <BoomButton />
+      </Boundary>
+    </div>
+  );
+};
+
+export const OnResetCallback = () => {
+  const [resets, setResets] = useState<string[]>([]);
+  return (
+    <div className="max-w-lg space-y-3">
+      <p className="text-sm text-muted-foreground">
+        <code className="text-xs">onReset</code> fires when the boundary recovers — wire it to React Query invalidation, refetch, etc.
+      </p>
+      <Boundary
+        variant="card"
+        onReset={(details) =>
+          setResets((prev) => [...prev, `reset @ ${new Date().toISOString().slice(11, 19)} (${details.reason})`])
+        }
+      >
+        <BoomButton />
+      </Boundary>
+      <div className="text-xs text-muted-foreground">
+        Resets:
+        <ul className="mt-1 space-y-0.5">
+          {resets.map((r, i) => (
+            <li key={i}>· {r}</li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  );
+};
+
+function AsyncCrasher() {
+  const { showBoundary } = useBoundary();
+  return (
+    <Button
+      variant="outline"
+      size="sm"
+      onClick={async () => {
+        // Regular React boundaries DON'T catch this. useBoundary() does.
+        await new Promise((r) => setTimeout(r, 200));
+        try {
+          throw new Error('Async fetch failed after 200ms');
+        } catch (err) {
+          showBoundary(err);
+        }
+      }}
+    >
+      Throw async error
+    </Button>
+  );
+}
+
+export const AsyncErrorsViaHook = () => (
+  <div className="max-w-lg space-y-2">
+    <p className="text-sm text-muted-foreground">
+      React error boundaries only catch <em>render</em> errors. Use <code className="text-xs">useBoundary().showBoundary(err)</code> to push async / event-handler errors into the nearest boundary.
+    </p>
+    <Boundary variant="card" name="async-demo">
+      <AsyncCrasher />
+    </Boundary>
+  </div>
+);

package/src/components/boundary/index.ts

@@ -0,0 +1,9 @@
+export { Boundary, useBoundary } from './Boundary';
+export type {
+  BoundaryProps,
+  BoundaryVariant,
+  BoundaryRenderProps,
+  BoundaryResetReason,
+  BoundaryResetDetails,
+  BoundaryLogger,
+} from './Boundary';

package/src/components/index.ts

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

package/src/components/select/combobox.tsx

@@ -38,6 +38,23 @@ export interface ComboboxProps {
   disabled?: boolean
   renderOption?: (option: ComboboxOption) => React.ReactNode
   renderValue?: (option: ComboboxOption | undefined) => React.ReactNode
+  /**
+   * Replace the default `<Button variant="outline" w-full>` trigger
+   * entirely. Use when the default trigger is too wide / too heavy for
+   * the host (e.g. a 28×28 flag icon in a chat header). The element
+   * receives Radix `PopoverTrigger asChild` props (refs + a11y) so
+   * pass any native element here — `button`, `div role="button"`, etc.
+   */
+  renderTrigger?: (
+    selected: ComboboxOption | undefined,
+    open: boolean,
+  ) => React.ReactElement
+  /** Forwarded to `PopoverContent.className` — width, padding, etc. */
+  contentClassName?: string
+  /** Forwarded to `PopoverContent.style` — host can bump z-index when
+   *  the combobox is rendered above another overlay (chat dock,
+   *  modal, …) whose stacking context outranks ui-core's default. */
+  contentStyle?: React.CSSProperties
   /** Custom filter function. If provided, replaces default filtering logic. */
   filterFunction?: (option: ComboboxOption, search: string) => boolean
   /**
@@ -80,6 +97,9 @@ export function Combobox({
   disabled = false,
   renderOption,
   renderValue,
+  renderTrigger,
+  contentClassName,
+  contentStyle,
   filterFunction,
   storageKey,
   storageType,
@@ -242,26 +262,34 @@ export function Combobox({
       }}
     >
       <PopoverTrigger asChild>
-        <Button
-          variant="outline"
-          role="combobox"
-          aria-expanded={open}
-          className={cn(
-            "w-full justify-between",
-            !value && "text-muted-foreground",
-            className
-          )}
-          disabled={disabled}
-        >
-          {renderValue && selectedOption
-            ? renderValue(selectedOption)
-            : selectedOption
-            ? renderSelectedBadge(selectedOption)
-            : resolvedPlaceholder}
-          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
-        </Button>
+        {renderTrigger ? (
+          renderTrigger(selectedOption, open)
+        ) : (
+          <Button
+            variant="outline"
+            role="combobox"
+            aria-expanded={open}
+            className={cn(
+              "w-full justify-between",
+              !value && "text-muted-foreground",
+              className
+            )}
+            disabled={disabled}
+          >
+            {renderValue && selectedOption
+              ? renderValue(selectedOption)
+              : selectedOption
+              ? renderSelectedBadge(selectedOption)
+              : resolvedPlaceholder}
+            <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+          </Button>
+        )}
       </PopoverTrigger>
-      <PopoverContent className="w-[var(--radix-popover-trigger-width)] p-0" align="start">
+      <PopoverContent
+        className={cn("w-[var(--radix-popover-trigger-width)] p-0", contentClassName)}
+        style={contentStyle}
+        align="start"
+      >
         <Command shouldFilter={false} className="flex flex-col">
           <CommandInput
             placeholder={resolvedSearchPlaceholder}