@polderlabs/bizar 6.3.0 → 7.0.1

package/bizar-dash/src/web/ui/feedback/Dialog.tsx

@@ -0,0 +1,209 @@
+/*
+ * Dialog.tsx — Modal dialog for the Bizar design system (Wave 2C).
+ *
+ * Backed by `react-dom` portals: rendered into `document.body` so it sits
+ * above the rest of the page chrome and stacking-context issues don't
+ * trap it inside a parent with overflow / transform. Backdrop click +
+ * Escape close the dialog unless `persistent` is true, in which case
+ * the user must use the close button or the actions slot to dismiss.
+ *
+ * Accessibility:
+ *   - `role="dialog"`, `aria-modal="true"`, `aria-labelledby` + `aria-describedby`
+ *   - Focus is moved to the first focusable child (or the dialog itself) on open
+ *   - Tab/Shift+Tab cycle within the dialog only
+ *   - On close, focus is restored to the element that was active when the
+ *     dialog opened
+ *
+ * Coexists with the legacy `<ModalProvider>` from src/components/Modal —
+ * the two context names are different, so a single tree can hold both.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+import { X } from 'lucide-react';
+import { cx } from '../utils/cx';
+
+export type DialogProps = {
+  open: boolean;
+  onClose: () => void;
+  title?: ReactNode;
+  description?: ReactNode;
+  children?: ReactNode;
+  actions?: ReactNode;
+  width?: number;
+  /** When true, Escape and backdrop clicks do not close the dialog. */
+  persistent?: boolean;
+  className?: string;
+};
+
+const FOCUSABLE_SELECTOR = [
+  'button:not([disabled])',
+  '[href]',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+
+export function Dialog({
+  open,
+  onClose,
+  title,
+  description,
+  children,
+  actions,
+  width,
+  persistent = false,
+  className,
+}: DialogProps): React.JSX.Element | null {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+  const titleId = useId();
+  const descriptionId = useId();
+
+  // Escape key — close unless persistent.
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        if (!persistent) onClose();
+      }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [open, persistent, onClose]);
+
+  // Lock body scroll while the dialog is open.
+  useEffect(() => {
+    if (!open) return;
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, [open]);
+
+  // Initial focus + focus trap + restore focus on close.
+  useEffect(() => {
+    if (!open) return;
+    previousFocusRef.current =
+      document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : null;
+
+    const root = dialogRef.current;
+    if (!root) return;
+
+    // Focus the first focusable child or the dialog itself.
+    const initialFocus = (): void => {
+      const focusables = Array.from(
+        root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+      ).filter((el) => el.tabIndex !== -1);
+      const target = focusables[0] ?? root;
+      target.focus();
+    };
+    initialFocus();
+
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key !== 'Tab') return;
+      const focusables = Array.from(
+        root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+      ).filter((el) => el.tabIndex !== -1);
+      if (focusables.length === 0) {
+        e.preventDefault();
+        root.focus();
+        return;
+      }
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey) {
+        if (active === first || !root.contains(active)) {
+          e.preventDefault();
+          last.focus();
+        }
+      } else {
+        if (active === last || !root.contains(active)) {
+          e.preventDefault();
+          first.focus();
+        }
+      }
+    };
+
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      const previous = previousFocusRef.current;
+      if (previous && previous.isConnected) {
+        previous.focus();
+      }
+    };
+  }, [open]);
+
+  const onBackdropClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>): void => {
+      if (persistent) return;
+      if (e.target === e.currentTarget) {
+        onClose();
+      }
+    },
+    [persistent, onClose],
+  );
+
+  if (!open) return null;
+  if (typeof document === 'undefined') return null;
+
+  return createPortal(
+    <div
+      className="bizar-dialog-backdrop"
+      onClick={onBackdropClick}
+      role="presentation"
+    >
+      <div
+        ref={dialogRef}
+        className={cx('bizar-dialog', className)}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title ? titleId : undefined}
+        aria-describedby={description ? descriptionId : undefined}
+        tabIndex={-1}
+        style={width ? { maxWidth: width } : undefined}
+      >
+        {(title || description) && (
+          <div className="bizar-dialog__header">
+            <div style={{ flex: 1, minWidth: 0 }}>
+              {title && (
+                <h2 id={titleId} className="bizar-dialog__title">
+                  {title}
+                </h2>
+              )}
+              {description && (
+                <p id={descriptionId} className="bizar-dialog__description">
+                  {description}
+                </p>
+              )}
+            </div>
+            <button
+              type="button"
+              className="bizar-dialog__close"
+              aria-label="Close dialog"
+              onClick={onClose}
+            >
+              <X size={16} />
+            </button>
+          </div>
+        )}
+        <div className="bizar-dialog__body">{children}</div>
+        {actions && <div className="bizar-dialog__actions">{actions}</div>}
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/bizar-dash/src/web/ui/feedback/ProgressBar.tsx

@@ -0,0 +1,69 @@
+/*
+ * ProgressBar.tsx — Horizontal progress indicator (Wave 2C).
+ *
+ * Three modes:
+ *   - Determinate (`value` 0..max): width = `value / max` percent.
+ *   - Indeterminate: a 25%-wide bar slides across the track infinitely.
+ *   - Without any inputs: renders a 0% determinate bar (callers should
+ *     pass `indeterminate` for spinner-style states).
+ *
+ * Accessible: a `role="progressbar"` element with `aria-valuenow`,
+ * `aria-valuemin`, `aria-valuemax`. Indeterminate progress passes
+ * `aria-valuenow={undefined}` per the ARIA spec so assistive tech knows
+ * not to read a value.
+ */
+
+import type { ReactNode } from 'react';
+import { cx } from '../utils/cx';
+
+export type ProgressVariant = 'neutral' | 'accent' | 'success' | 'danger';
+export type ProgressSize = 'sm' | 'md' | 'lg';
+
+export type ProgressBarProps = {
+  value?: number;
+  max?: number;
+  indeterminate?: boolean;
+  size?: ProgressSize;
+  variant?: ProgressVariant;
+  label?: ReactNode;
+  className?: string;
+};
+
+export function ProgressBar({
+  value = 0,
+  max = 100,
+  indeterminate = false,
+  size = 'md',
+  variant = 'accent',
+  label,
+  className,
+}: ProgressBarProps): React.JSX.Element {
+  const safeMax = max > 0 ? max : 100;
+  const clamped = Math.max(0, Math.min(value, safeMax));
+  const pct = (clamped / safeMax) * 100;
+
+  return (
+    <div className={cx('bizar-progress-wrap', className)}>
+      {label !== undefined && (
+        <span className="bizar-progress__label">{label}</span>
+      )}
+      <div
+        className={cx(
+          'bizar-progress',
+          `bizar-progress--${size}`,
+          indeterminate && 'bizar-progress--indeterminate',
+        )}
+        role="progressbar"
+        aria-valuenow={indeterminate ? undefined : clamped}
+        aria-valuemin={indeterminate ? undefined : 0}
+        aria-valuemax={indeterminate ? undefined : safeMax}
+        aria-label={typeof label === 'string' ? label : undefined}
+      >
+        <div
+          className={cx('bizar-progress__fill', `bizar-progress__fill--${variant}`)}
+          style={indeterminate ? undefined : { width: `${pct}%` }}
+        />
+      </div>
+    </div>
+  );
+}

package/bizar-dash/src/web/ui/feedback/StatusDot.tsx

@@ -0,0 +1,50 @@
+/*
+ * StatusDot.tsx — Small colored indicator dot (Wave 2C).
+ *
+ * Renders a 6–8px circle in one of five semantic colors. When `pulse` is
+ * true a 2s opacity animation makes the dot appear to "breathe" — used
+ * sparingly to call attention to live or in-flight states. No context,
+ * no effects — pure styled span.
+ */
+
+import { cx } from '../utils/cx';
+
+export type StatusDotVariant =
+  | 'neutral'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger';
+
+export type StatusDotSize = 'sm' | 'md';
+
+export type StatusDotProps = {
+  variant?: StatusDotVariant;
+  size?: StatusDotSize;
+  pulse?: boolean;
+  className?: string;
+  /** Accessible label for screen readers — the dot itself is decorative. */
+  label?: string;
+};
+
+export function StatusDot({
+  variant = 'neutral',
+  size = 'md',
+  pulse = false,
+  className,
+  label,
+}: StatusDotProps): React.JSX.Element {
+  return (
+    <span
+      className={cx(
+        'bizar-status-dot',
+        `bizar-status-dot--${variant}`,
+        `bizar-status-dot--${size}`,
+        pulse && 'bizar-status-dot--pulse',
+        className,
+      )}
+      role={label ? 'status' : 'presentation'}
+      aria-label={label}
+    />
+  );
+}

package/bizar-dash/src/web/ui/feedback/Toast.tsx

@@ -0,0 +1,200 @@
+/*
+ * Toast.tsx — Self-contained toast provider + hook (Wave 2C).
+ *
+ * Replaces the legacy useToast API in src/components/Toast.tsx but lives
+ * under a different context name (`BizarToastContext`) so the legacy
+ * provider and the new provider can coexist in the same tree. The hook
+ * throws when used outside a provider — a missing provider is a developer
+ * error, not a runtime fallback.
+ *
+ * Defaults: 4000ms duration, errors pin to 6000ms, viewport pinned to the
+ * bottom-right (`fixed`), max 5 toasts visible at once. New toasts past
+ * the cap evict the oldest. Manual dismiss via the close button or
+ * imperatively via `useToast().dismiss(id)`.
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import {
+  AlertCircle,
+  AlertTriangle,
+  CheckCircle2,
+  Info,
+  X,
+} from 'lucide-react';
+import { cx } from '../utils/cx';
+
+export type ToastKind = 'info' | 'success' | 'warning' | 'error';
+
+export type ToastItem = {
+  id: number;
+  kind: ToastKind;
+  message: string;
+};
+
+export type ToastApi = {
+  info: (message: string, durationMs?: number) => number;
+  success: (message: string, durationMs?: number) => number;
+  warning: (message: string, durationMs?: number) => number;
+  error: (message: string, durationMs?: number) => number;
+  dismiss: (id: number) => void;
+};
+
+const BizarToastContext = createContext<ToastApi | null>(null);
+
+const MAX_VISIBLE = 5;
+const DEFAULT_DURATION = 4000;
+const ERROR_DURATION = 6000;
+
+const ICONS: Record<ToastKind, typeof Info> = {
+  info: Info,
+  success: CheckCircle2,
+  warning: AlertTriangle,
+  error: AlertCircle,
+};
+
+export function useToast(): ToastApi {
+  const ctx = useContext(BizarToastContext);
+  if (!ctx) {
+    throw new Error(
+      'useToast must be used inside a <ToastProvider>. ' +
+        'Wrap your app root in <ToastProvider> before calling useToast().',
+    );
+  }
+  return ctx;
+}
+
+export type ToastProviderProps = {
+  children: ReactNode;
+  /** Override the cap for tests and unusual surfaces. Default 5. */
+  maxVisible?: number;
+};
+
+export function ToastProvider({
+  children,
+  maxVisible = MAX_VISIBLE,
+}: ToastProviderProps): React.JSX.Element {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const idRef = useRef(1);
+  const timersRef = useRef<Map<number, ReturnType<typeof setTimeout>>>(new Map());
+
+  const dismiss = useCallback((id: number) => {
+    setToasts((cur) => cur.filter((t) => t.id !== id));
+    const timer = timersRef.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersRef.current.delete(id);
+    }
+  }, []);
+
+  const push = useCallback(
+    (kind: ToastKind, message: string, durationMs?: number): number => {
+      const id = idRef.current++;
+      setToasts((cur) => {
+        const next = [...cur, { id, kind, message }];
+        // Evict oldest if we exceed the visible cap. Use queue-style FIFO.
+        if (next.length > maxVisible) {
+          const toEvict = next.slice(0, next.length - maxVisible);
+          for (const t of toEvict) {
+            const timer = timersRef.current.get(t.id);
+            if (timer) {
+              clearTimeout(timer);
+              timersRef.current.delete(t.id);
+            }
+          }
+          return next.slice(-maxVisible);
+        }
+        return next;
+      });
+      const effective =
+        durationMs ??
+        (kind === 'error' ? ERROR_DURATION : DEFAULT_DURATION);
+      if (effective > 0) {
+        const timer = setTimeout(() => dismiss(id), effective);
+        timersRef.current.set(id, timer);
+      }
+      return id;
+    },
+    [dismiss, maxVisible],
+  );
+
+  useEffect(() => {
+    return () => {
+      for (const timer of timersRef.current.values()) clearTimeout(timer);
+      timersRef.current.clear();
+    };
+  }, []);
+
+  const api = useMemo<ToastApi>(
+    () => ({
+      info: (m, d) => push('info', m, d),
+      success: (m, d) => push('success', m, d),
+      warning: (m, d) => push('warning', m, d),
+      error: (m, d) => push('error', m, d),
+      dismiss,
+    }),
+    [push, dismiss],
+  );
+
+  return (
+    <BizarToastContext.Provider value={api}>
+      {children}
+      <ToastViewport toasts={toasts} onDismiss={dismiss} />
+    </BizarToastContext.Provider>
+  );
+}
+
+function ToastViewport({
+  toasts,
+  onDismiss,
+}: {
+  toasts: ToastItem[];
+  onDismiss: (id: number) => void;
+}): React.JSX.Element {
+  return (
+    <div className="bizar-toast-viewport" aria-live="polite">
+      {toasts.map((t) => (
+        <ToastCard key={t.id} toast={t} onDismiss={onDismiss} />
+      ))}
+    </div>
+  );
+}
+
+function ToastCard({
+  toast,
+  onDismiss,
+}: {
+  toast: ToastItem;
+  onDismiss: (id: number) => void;
+}): React.JSX.Element {
+  const Icon = ICONS[toast.kind];
+  return (
+    <div
+      className={cx('bizar-toast', `bizar-toast--${toast.kind}`)}
+      role={toast.kind === 'error' ? 'alert' : 'status'}
+      aria-live={toast.kind === 'error' ? 'assertive' : 'polite'}
+      aria-atomic="true"
+    >
+      <span className="bizar-toast__icon">
+        <Icon size={16} />
+      </span>
+      <span className="bizar-toast__message">{toast.message}</span>
+      <button
+        type="button"
+        className="bizar-toast__close"
+        aria-label="Dismiss notification"
+        onClick={() => onDismiss(toast.id)}
+      >
+        <X size={14} />
+      </button>
+    </div>
+  );
+}

package/bizar-dash/src/web/ui/feedback/Tooltip.tsx

@@ -0,0 +1,126 @@
+/*
+ * Tooltip.tsx — Lightweight tooltip wrapper for the Bizar design system (Wave 2C).
+ *
+ * Wraps a single child element and shows a textual popup on hover or focus
+ * after a configurable delay (default 200ms). The popup disappears on
+ * pointerleave / blur. Positioning is hand-rolled using absolute CSS over
+ * an internal `bizar-tooltip` positioning wrapper — the wrapper owns the
+ * `position: relative` containing block so popup children can position
+ * themselves against it via the four cardinal sides (top / right /
+ * bottom / left). No Radix or Popper.js dep.
+ *
+ * Accessibility:
+ *   - The wrapped child receives `aria-describedby` pointing at the popup id
+ *   - The popup carries `role="tooltip"`
+ */
+
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { cx } from '../utils/cx';
+
+export type TooltipSide = 'top' | 'right' | 'bottom' | 'left';
+
+export type TooltipProps = {
+  content: ReactNode;
+  side?: TooltipSide;
+  delay?: number;
+  children: ReactElement;
+  className?: string;
+};
+
+export function Tooltip({
+  content,
+  side = 'top',
+  delay = 200,
+  children,
+  className,
+}: TooltipProps): React.JSX.Element {
+  const [open, setOpen] = useState(false);
+  const id = useId();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  // Tear down any pending timer on unmount so we don't update unmounted state.
+  useEffect(() => {
+    return clearTimer;
+  }, [clearTimer]);
+
+  const show = (): void => {
+    clearTimer();
+    timerRef.current = setTimeout(() => setOpen(true), delay);
+  };
+  const hide = (): void => {
+    clearTimer();
+    setOpen(false);
+  };
+
+  if (!isValidElement(children)) {
+    throw new Error('Tooltip requires a single React element child.');
+  }
+
+  // We pick the first ReactElement's props and add tooltip wiring. We
+  // deliberately keep the wrapper element-agnostic — it can be a button,
+  // an anchor, or a generic span — by attaching the triggers directly via
+  // inline handlers + props. The positioning class lives on an OUTER
+  // wrapper (the popup's parent), not on the cloned child, so absolutely-
+  // positioned descendants resolve against the wrapper as their containing
+  // block — siblings don't share a containing block in CSS.
+  type ChildPropsHack = {
+    onPointerEnter?: (e: React.PointerEvent) => void;
+    onPointerLeave?: (e: React.PointerEvent) => void;
+    onFocus?: (e: React.FocusEvent) => void;
+    onBlur?: (e: React.FocusEvent) => void;
+    'aria-describedby'?: string;
+  };
+
+  const childProps = children.props as ChildPropsHack;
+  const enhanced = cloneElement(children, {
+    onPointerEnter: (e: React.PointerEvent): void => {
+      childProps.onPointerEnter?.(e);
+      show();
+    },
+    onPointerLeave: (e: React.PointerEvent): void => {
+      childProps.onPointerLeave?.(e);
+      hide();
+    },
+    onFocus: (e: React.FocusEvent): void => {
+      childProps.onFocus?.(e);
+      show();
+    },
+    onBlur: (e: React.FocusEvent): void => {
+      childProps.onBlur?.(e);
+      hide();
+    },
+    'aria-describedby': open ? id : undefined,
+  } as ChildPropsHack);
+
+  return (
+    <span className={cx('bizar-tooltip', className)}>
+      {enhanced}
+      {open && (
+        <span
+          role="tooltip"
+          id={id}
+          className={cx('bizar-tooltip__popup', `bizar-tooltip__popup--${side}`)}
+        >
+          {content}
+        </span>
+      )}
+    </span>
+  );
+}