@dashforge/tw 1.0.0 → 1.1.1

package/src/components/Snackbar/Snackbar.tsx

@@ -1,298 +0,0 @@
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
-import { cn } from '../../utils/cn.js';
-import { snackbarVariants } from './snackbar.variants.js';
-import type {
-  SnackbarApi,
-  SnackbarOptions,
-  SnackbarProviderProps,
-  SnackbarRecord,
-  SnackbarSeverity,
-} from './snackbar.types.js';
-
-const SnackbarContext = createContext<SnackbarApi | null>(null);
-
-/**
- * `useSnackbar()` — returns `{ enqueue, dismiss, dismissAll }`.
- *
- * Throws if called outside `<SnackbarProvider>` — silent no-op would
- * be a footgun for "Saved!" toasts that silently vanish.
- */
-export function useSnackbar(): SnackbarApi {
-  const ctx = useContext(SnackbarContext);
-  if (ctx == null) {
-    throw new Error(
-      '[Snackbar] useSnackbar() must be called inside <SnackbarProvider>.'
-    );
-  }
-  return ctx;
-}
-
-/**
- * Unicode glyphs for severities — keeps the bundle small (no icon dep)
- * and stays accessible because consumers pass their own message text.
- * The glyph is `aria-hidden`; the screen reader announces the message
- * via the live region.
- */
-const SEVERITY_GLYPH: Record<SnackbarSeverity, string> = {
-  info: 'ⓘ',
-  success: '✓',
-  warning: '⚠',
-  danger: '✕',
-};
-
-/**
- * Dashforge TW Snackbar provider — transient, stacked toast notifications.
- *
- * **Behaviour**:
- *   - `enqueue(opts)` returns the assigned `id`.
- *   - Items appear in a fixed-corner stack (`position` prop).
- *   - At most `maxVisible` (default 5) are shown — extras queue FIFO.
- *   - Each item auto-dismisses after `autoHideMs` (default 4000); set
- *     `0` for a persistent snackbar.
- *   - Re-enqueueing with the SAME `id` reuses the slot and resets the
- *     timer (de-dup pattern for repeated "Saved" toasts).
- *
- * **A11y**:
- *   - Container is an `aria-live="polite"` region (assistive techs
- *     announce new messages without stealing focus).
- *   - Severity icon is `aria-hidden` — the message text carries the
- *     semantic.
- *   - Close + action buttons are focusable via Tab; the visual stack
- *     order is the same as the announcement order.
- *
- * **Re-render contract**:
- *   - Provider re-renders ONLY when the visible set changes.
- *   - The `api` (returned by `useSnackbar()`) is stable across re-renders
- *     — `useCallback`'d with no deps, mutates a ref internally.
- *   - Consumers calling `useSnackbar()` get the same identity each time
- *     so they can safely pass `enqueue` to `useEffect` deps.
- */
-export function SnackbarProvider(props: SnackbarProviderProps) {
-  const {
-    children,
-    position = 'bottom-right',
-    maxVisible = 5,
-    defaults,
-    slotProps,
-  } = props;
-
-  /**
-   * The set of CURRENTLY-RENDERED snackbars. Extras enqueued past
-   * `maxVisible` wait in `queueRef` until a slot frees up.
-   */
-  const [visible, setVisible] = useState<SnackbarRecord[]>([]);
-  const queueRef = useRef<SnackbarRecord[]>([]);
-
-  /** Monotonic id seed + tick. */
-  const idSeqRef = useRef(0);
-  const tickSeqRef = useRef(0);
-
-  /** Map<id, timeoutId> for auto-dismiss timers — cleared on dismiss/replace. */
-  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(
-    new Map()
-  );
-
-  /** Stable refs so `api` callbacks don't need to depend on state. */
-  const maxVisibleRef = useRef(maxVisible);
-  maxVisibleRef.current = maxVisible;
-  const defaultsRef = useRef(defaults);
-  defaultsRef.current = defaults;
-
-  const clearTimer = (id: string) => {
-    const t = timersRef.current.get(id);
-    if (t != null) {
-      clearTimeout(t);
-      timersRef.current.delete(id);
-    }
-  };
-
-  /**
-   * `dismiss` — remove a snackbar, then attempt to promote a queued
-   * item into the freed slot.
-   */
-  const dismiss = useCallback((id: string) => {
-    clearTimer(id);
-    setVisible((curr) => {
-      const next = curr.filter((s) => s.id !== id);
-      // Promote one from the queue if there's room.
-      if (next.length < maxVisibleRef.current && queueRef.current.length > 0) {
-        const promoted = queueRef.current.shift();
-        if (promoted != null) {
-          scheduleAutoDismiss(promoted);
-          return [...next, promoted];
-        }
-      }
-      return next;
-    });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  /**
-   * Schedule the auto-dismiss timeout for a given record (if its
-   * `autoHideMs > 0`). Stable ref so it can be invoked from inside
-   * `dismiss` without a circular dep.
-   */
-  const dismissRef = useRef(dismiss);
-  dismissRef.current = dismiss;
-  const scheduleAutoDismiss = useCallback((rec: SnackbarRecord) => {
-    const ms = rec.autoHideMs ?? defaultsRef.current?.autoHideMs ?? 4000;
-    if (ms <= 0) return;
-    clearTimer(rec.id);
-    const handle = setTimeout(() => dismissRef.current(rec.id), ms);
-    timersRef.current.set(rec.id, handle);
-  }, []);
-
-  /**
-   * `enqueue` — show a new snackbar.
-   *
-   * De-dup contract: if `options.id` matches a CURRENTLY-VISIBLE or
-   * CURRENTLY-QUEUED entry, the existing entry's content is updated
-   * AND its timer is reset, instead of appending a duplicate.
-   */
-  const enqueue = useCallback((options: SnackbarOptions): string => {
-    const id = options.id ?? `sb-${++idSeqRef.current}`;
-    const tick = ++tickSeqRef.current;
-    const rec: SnackbarRecord = {
-      ...defaultsRef.current,
-      ...options,
-      id,
-      tick,
-    };
-    // Reset timer if id already exists (de-dup).
-    clearTimer(id);
-
-    setVisible((curr) => {
-      const idx = curr.findIndex((s) => s.id === id);
-      if (idx >= 0) {
-        // Replace in-place, reset timer.
-        const next = [...curr];
-        next[idx] = rec;
-        scheduleAutoDismiss(rec);
-        return next;
-      }
-      // Drop the same-id entry from the queue if it's waiting.
-      queueRef.current = queueRef.current.filter((s) => s.id !== id);
-      if (curr.length < maxVisibleRef.current) {
-        scheduleAutoDismiss(rec);
-        return [...curr, rec];
-      }
-      // Stack is full — queue and wait.
-      queueRef.current.push(rec);
-      return curr;
-    });
-    return id;
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  /** `dismissAll` — clear everything (visible + queued + timers). */
-  const dismissAll = useCallback(() => {
-    timersRef.current.forEach(clearTimeout);
-    timersRef.current.clear();
-    queueRef.current = [];
-    setVisible([]);
-  }, []);
-
-  // Clean up any straggler timers on unmount.
-  useEffect(
-    () => () => {
-      timersRef.current.forEach(clearTimeout);
-      timersRef.current.clear();
-    },
-    []
-  );
-
-  const api = useMemo<SnackbarApi>(
-    () => ({ enqueue, dismiss, dismissAll }),
-    [enqueue, dismiss, dismissAll]
-  );
-
-  const v = snackbarVariants({ position });
-
-  return (
-    <SnackbarContext.Provider value={api}>
-      {children}
-      <div
-        className={cn(v.container(), slotProps?.container?.className)}
-        role="region"
-        aria-label="Notifications"
-        aria-live="polite"
-        aria-atomic="false"
-      >
-        {visible.map((rec) => {
-          const sev = rec.severity ?? defaults?.severity ?? 'info';
-          const showClose =
-            rec.showClose ?? defaults?.showClose ?? true;
-          const itemClasses = snackbarVariants({
-            position,
-            severity: sev,
-          });
-          return (
-            <div
-              key={rec.id}
-              data-state="entered"
-              data-tick={rec.tick}
-              className={cn(
-                itemClasses.item(),
-                slotProps?.item?.className
-              )}
-            >
-              <span
-                aria-hidden="true"
-                className={cn(
-                  itemClasses.icon(),
-                  slotProps?.icon?.className
-                )}
-              >
-                {SEVERITY_GLYPH[sev]}
-              </span>
-              <div
-                className={cn(
-                  itemClasses.message(),
-                  slotProps?.message?.className
-                )}
-              >
-                {rec.message}
-              </div>
-              {rec.action != null && (
-                <button
-                  type="button"
-                  onClick={() => {
-                    rec.action?.onClick();
-                    dismiss(rec.id);
-                  }}
-                  className={cn(
-                    itemClasses.action(),
-                    slotProps?.action?.className
-                  )}
-                >
-                  {rec.action.label}
-                </button>
-              )}
-              {showClose && (
-                <button
-                  type="button"
-                  aria-label="Dismiss notification"
-                  onClick={() => dismiss(rec.id)}
-                  className={cn(
-                    itemClasses.closeButton(),
-                    slotProps?.closeButton?.className
-                  )}
-                >
-                  ×
-                </button>
-              )}
-            </div>
-          );
-        })}
-      </div>
-    </SnackbarContext.Provider>
-  );
-}

package/src/components/Snackbar/snackbar.types.ts

@@ -1,83 +0,0 @@
-import type { ReactNode } from 'react';
-import type { SnackbarVariants } from './snackbar.variants.js';
-
-/** Visual severity — drives icon color + accent on the snackbar surface. */
-export type SnackbarSeverity = 'info' | 'success' | 'warning' | 'danger';
-
-/** Corner anchor for the snackbar stack. */
-export type SnackbarPosition =
-  | 'top-left'
-  | 'top-center'
-  | 'top-right'
-  | 'bottom-left'
-  | 'bottom-center'
-  | 'bottom-right';
-
-/** One snackbar instance — what `useSnackbar().enqueue()` accepts. */
-export interface SnackbarOptions {
-  /** Required text/content. */
-  message: ReactNode;
-  /** Visual severity. @default 'info' */
-  severity?: SnackbarSeverity;
-  /**
-   * Auto-dismiss after this many ms. `0` / negative ⇒ persistent
-   * (only dismissed by the close button or `dismiss(id)`).
-   * @default 4000
-   */
-  autoHideMs?: number;
-  /** Optional action button label + handler. */
-  action?: { label: ReactNode; onClick: () => void };
-  /** Per-instance close-button visibility. @default true */
-  showClose?: boolean;
-  /**
-   * Stable identifier for de-duplication. If a snackbar with the same
-   * `id` is enqueued while already visible, the existing one is REUSED
-   * (auto-dismiss timer reset) instead of stacking a duplicate. Useful
-   * for "Saved" toasts triggered repeatedly from the same action.
-   */
-  id?: string;
-}
-
-/** Internal model — every enqueued snackbar gets a unique id + a tick. */
-export interface SnackbarRecord extends SnackbarOptions {
-  id: string;
-  /**
-   * Monotonic creation tick, used to drive the entry CSS transition
-   * (the consumer's CSS can target `data-state="entered"` keyed by tick).
-   */
-  tick: number;
-}
-
-export interface SnackbarSlotProps {
-  container?: { className?: string };
-  item?: { className?: string };
-  icon?: { className?: string };
-  message?: { className?: string };
-  action?: { className?: string };
-  closeButton?: { className?: string };
-}
-
-/** API exposed by `useSnackbar()`. */
-export interface SnackbarApi {
-  /** Show a snackbar — returns its assigned id (auto-generated if not provided). */
-  enqueue: (options: SnackbarOptions) => string;
-  /** Dismiss a specific snackbar. */
-  dismiss: (id: string) => void;
-  /** Dismiss every visible snackbar. */
-  dismissAll: () => void;
-}
-
-export interface SnackbarProviderProps extends SnackbarVariants {
-  children: ReactNode;
-  /** Corner the stack anchors to. @default 'bottom-right' */
-  position?: SnackbarPosition;
-  /**
-   * Hard cap on simultaneously visible snackbars. Excess enqueued
-   * items wait FIFO until a slot frees up. @default 5
-   */
-  maxVisible?: number;
-  /** Defaults merged into every enqueue. */
-  defaults?: Pick<SnackbarOptions, 'severity' | 'autoHideMs' | 'showClose'>;
-  /** Per-slot className overrides. */
-  slotProps?: SnackbarSlotProps;
-}

package/src/components/Snackbar/snackbar.variants.ts

@@ -1,74 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<Snackbar>` (stacked toast surface).
- *
- * Slots:
- *   - `container`   — fixed-position outer stack
- *   - `item`        — single snackbar surface
- *   - `icon`        — leading severity icon
- *   - `message`     — main text
- *   - `action`      — optional action button
- *   - `closeButton` — trailing `×` button
- */
-export const snackbarVariants = tv({
-  slots: {
-    container: [
-      'fixed z-50 flex flex-col gap-2 p-4 pointer-events-none',
-      'max-w-[min(28rem,calc(100vw-2rem))]',
-    ],
-    item: [
-      'pointer-events-auto',
-      'flex items-start gap-3 px-4 py-3 w-full',
-      'rounded-lg border shadow-lg',
-      'text-sm bg-neutral-50 text-neutral-900',
-      // Subtle enter transition — opacity + translate, kept short so a
-      // burst of snackbars feels snappy. Gated on motion-reduce
-      // (WCAG 2.3.3) — users who request reduced motion see snackbars
-      // pop in instantly without the slide animation.
-      'transition-all duration-200 motion-reduce:transition-none motion-reduce:duration-0',
-      'data-[state=entered]:opacity-100 data-[state=exited]:opacity-0',
-    ],
-    icon: 'shrink-0 mt-0.5 w-5 h-5 inline-flex items-center justify-center',
-    message: 'flex-1 min-w-0 leading-relaxed',
-    action: [
-      'shrink-0 inline-flex items-center justify-center px-2 h-7',
-      'rounded-md text-xs font-medium',
-      'text-primary-700 hover:bg-primary-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors',
-    ],
-    closeButton: [
-      'shrink-0 inline-flex items-center justify-center w-6 h-6',
-      'rounded-md text-neutral-500 hover:bg-neutral-200 hover:text-neutral-900',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors',
-    ],
-  },
-  variants: {
-    position: {
-      'top-left': { container: 'top-0 left-0 items-start' },
-      'top-center': {
-        container: 'top-0 left-1/2 -translate-x-1/2 items-center',
-      },
-      'top-right': { container: 'top-0 right-0 items-end' },
-      'bottom-left': { container: 'bottom-0 left-0 items-start' },
-      'bottom-center': {
-        container: 'bottom-0 left-1/2 -translate-x-1/2 items-center',
-      },
-      'bottom-right': { container: 'bottom-0 right-0 items-end' },
-    },
-    severity: {
-      info: { item: 'border-primary-200', icon: 'text-primary-600' },
-      success: { item: 'border-success-200', icon: 'text-success-600' },
-      warning: { item: 'border-warning-200', icon: 'text-warning-600' },
-      danger: { item: 'border-danger-200', icon: 'text-danger-600' },
-    },
-  },
-  defaultVariants: {
-    position: 'bottom-right',
-    severity: 'info',
-  },
-});
-
-export type SnackbarVariants = VariantProps<typeof snackbarVariants>;