@dashforge/tw 0.11.0-beta → 1.1.0

package/src/components/Snackbar/Snackbar.tsx

@@ -9,12 +9,15 @@ import {
 } from 'react';
 import { cn } from '../../utils/cn.js';
 import { snackbarVariants } from './snackbar.variants.js';
+import {
+  getSeverityClasses,
+} from '../_shared/severity/severityVariants.js';
+import { getDefaultSeverityIcon } from '../_shared/severity/severityIcons.js';
 import type {
   SnackbarApi,
   SnackbarOptions,
   SnackbarProviderProps,
   SnackbarRecord,
-  SnackbarSeverity,
 } from './snackbar.types.js';
 
 const SnackbarContext = createContext<SnackbarApi | null>(null);
@@ -35,19 +38,6 @@ export function useSnackbar(): SnackbarApi {
   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.
  *
@@ -228,12 +218,24 @@ export function SnackbarProvider(props: SnackbarProviderProps) {
       >
         {visible.map((rec) => {
           const sev = rec.severity ?? defaults?.severity ?? 'info';
+          const variant = rec.variant ?? defaults?.variant ?? 'standard';
           const showClose =
             rec.showClose ?? defaults?.showClose ?? true;
-          const itemClasses = snackbarVariants({
-            position,
-            severity: sev,
-          });
+          const itemClasses = snackbarVariants({ position });
+          // Severity color classes — sourced from the shared 3×4 matrix
+          // (`_shared/severity/`), same as Alert. Keeps the two
+          // components visually in lockstep.
+          const severityClasses = getSeverityClasses(variant, sev);
+          // Icon resolution — same tristate as Alert:
+          //   undefined → default per-severity SVG (shared with Alert)
+          //   ReactNode → consumer's icon
+          //   false     → no icon
+          const renderedIcon =
+            rec.icon === false
+              ? null
+              : rec.icon !== undefined
+                ? rec.icon
+                : getDefaultSeverityIcon(sev);
           return (
             <div
               key={rec.id}
@@ -241,18 +243,22 @@ export function SnackbarProvider(props: SnackbarProviderProps) {
               data-tick={rec.tick}
               className={cn(
                 itemClasses.item(),
+                severityClasses.surface,
+                severityClasses.border,
                 slotProps?.item?.className
               )}
             >
-              <span
-                aria-hidden="true"
-                className={cn(
-                  itemClasses.icon(),
-                  slotProps?.icon?.className
-                )}
-              >
-                {SEVERITY_GLYPH[sev]}
-              </span>
+              {renderedIcon !== null && (
+                <span
+                  className={cn(
+                    itemClasses.icon(),
+                    severityClasses.icon,
+                    slotProps?.icon?.className
+                  )}
+                >
+                  {renderedIcon}
+                </span>
+              )}
               <div
                 className={cn(
                   itemClasses.message(),
@@ -286,7 +292,19 @@ export function SnackbarProvider(props: SnackbarProviderProps) {
                     slotProps?.closeButton?.className
                   )}
                 >
-                  ×
+                  <svg
+                    width="1em"
+                    height="1em"
+                    viewBox="0 0 20 20"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth={1.5}
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    aria-hidden="true"
+                  >
+                    <path d="m6 6 8 8M14 6l-8 8" />
+                  </svg>
                 </button>
               )}
             </div>

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

@@ -1,8 +1,27 @@
 import type { ReactNode } from 'react';
 import type { SnackbarVariants } from './snackbar.variants.js';
+import type {
+  Severity,
+  SeverityVariant,
+} from '../_shared/severity/severity.types.js';
 
-/** Visual severity — drives icon color + accent on the snackbar surface. */
-export type SnackbarSeverity = 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Visual severity — drives icon color + accent on the snackbar surface.
+ *
+ * Re-exported alias of the shared `Severity` type from
+ * `_shared/severity/`. Kept as a distinct local alias for
+ * backwards-compatible name (`SnackbarSeverity`) — pre-1.1.0 consumers
+ * that imported `SnackbarSeverity` keep their imports working.
+ */
+export type SnackbarSeverity = Severity;
+
+/**
+ * Visual variant — `standard` (default, soft tinted surface), `filled`
+ * (solid colored surface), `outlined` (transparent + border + text).
+ * Re-exported alias of the shared `SeverityVariant`. New in 1.1.0:
+ * Snackbar now supports the same 3-way axis as Alert / future Banner.
+ */
+export type SnackbarVariant = SeverityVariant;
 
 /** Corner anchor for the snackbar stack. */
 export type SnackbarPosition =
@@ -19,6 +38,28 @@ export interface SnackbarOptions {
   message: ReactNode;
   /** Visual severity. @default 'info' */
   severity?: SnackbarSeverity;
+  /**
+   * Visual variant — same 3-way axis as Alert. **New in 1.1.0.**
+   *
+   * - `'standard'` (default) — tinted soft surface, severity-toned text
+   * - `'filled'` — solid colored surface, light text (strong weight)
+   * - `'outlined'` — transparent surface, severity border + text
+   *
+   * @default 'standard'
+   */
+  variant?: SnackbarVariant;
+  /**
+   * Icon control — same tristate as Alert. **New in 1.1.0.**
+   *
+   * - omitted / `undefined` → default per-severity icon (inline SVG
+   *   shared with Alert via `_shared/severity/`)
+   * - `ReactNode` → consumer-provided icon
+   * - `false` → no icon (colored surface alone carries the severity)
+   *
+   * The legacy Unicode glyphs (`ⓘ ✓ ⚠ ✕`) shipped in 1.0.x have been
+   * REMOVED — see CHANGELOG for the visual breaking note.
+   */
+  icon?: ReactNode | false;
   /**
    * Auto-dismiss after this many ms. `0` / negative ⇒ persistent
    * (only dismissed by the close button or `dismiss(id)`).
@@ -77,7 +118,10 @@ export interface SnackbarProviderProps extends SnackbarVariants {
    */
   maxVisible?: number;
   /** Defaults merged into every enqueue. */
-  defaults?: Pick<SnackbarOptions, 'severity' | 'autoHideMs' | 'showClose'>;
+  defaults?: Pick<
+    SnackbarOptions,
+    'severity' | 'variant' | 'autoHideMs' | 'showClose'
+  >;
   /** Per-slot className overrides. */
   slotProps?: SnackbarSlotProps;
 }

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

@@ -3,13 +3,22 @@ import { tv, type VariantProps } from 'tailwind-variants';
 /**
  * Tailwind-variants recipe for `<Snackbar>` (stacked toast surface).
  *
+ * **Sprint 4.4 refactor (1.1.0):** the severity color block has been
+ * REMOVED from this recipe. The 3×4 (variant × severity) color matrix
+ * now lives in `_shared/severity/severityVariants` and is consumed by
+ * Snackbar AND Alert (and any future Banner). This recipe owns layout
+ * + spacing + transitions only — the surface / border / icon colors
+ * are merged in at render time via `cn()`.
+ *
  * Slots:
  *   - `container`   — fixed-position outer stack
- *   - `item`        — single snackbar surface
- *   - `icon`        — leading severity icon
+ *   - `item`        — single snackbar surface (layout only; severity
+ *                     colors injected at render via `getSeverityClasses`)
+ *   - `icon`        — leading severity icon (layout only; tone class
+ *                     injected at render)
  *   - `message`     — main text
  *   - `action`      — optional action button
- *   - `closeButton` — trailing `×` button
+ *   - `closeButton` — trailing close `×` button
  */
 export const snackbarVariants = tv({
   slots: {
@@ -21,28 +30,33 @@ export const snackbarVariants = tv({
       '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
+      'text-sm',
+      // Subtle enter transition — opacity-only, 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',
+      // pop in instantly without the fade.
+      'transition-opacity 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',
+    icon: 'shrink-0 mt-0.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',
+      // Action button uses currentColor + a soft hover tint so it
+      // adapts to whatever (variant, severity) surface it's on. The
+      // hover tint relies on a 10% opacity overlay of the current
+      // foreground — works in both light and dark severity surfaces.
+      'opacity-90 hover:opacity-100 hover:bg-current/10',
+      'outline-none focus-visible:ring-2 focus-visible:ring-current',
+      'transition-opacity',
     ],
     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',
+      'rounded-md',
+      'opacity-70 hover:opacity-100',
+      'outline-none focus-visible:ring-2 focus-visible:ring-current',
+      'transition-opacity',
     ],
   },
   variants: {
@@ -58,16 +72,9 @@ export const snackbarVariants = tv({
       },
       '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',
   },
 });
 

package/src/components/Spinner/Spinner.test.tsx

@@ -0,0 +1,199 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { render, screen, cleanup, act } from '@testing-library/react';
+import { Spinner } from './Spinner.js';
+
+void React;
+afterEach(() => cleanup());
+
+/**
+ * Unit tests for `<Spinner>`. Covers:
+ *   - Default rendering (role, label, animate-spin)
+ *   - Size axis (5 enum values → w/h spacing classes)
+ *   - Color → text-{color}-600 class
+ *   - color omitted → no text class (inherits currentColor)
+ *   - Thickness → SVG stroke-width
+ *   - withTrack → second <circle> with low opacity
+ *   - Delay → null for first N ms, then visible
+ *   - visibleWhen → null on false (regardless of delay)
+ *   - className / sx overrides
+ *   - motion-reduce gating (class present)
+ */
+
+describe('<Spinner>', () => {
+  describe('basic rendering', () => {
+    it('renders with role="status"', () => {
+      render(<Spinner />);
+      expect(screen.getByRole('status')).toBeTruthy();
+    });
+
+    it('exposes the default "Loading" label to screen readers', () => {
+      render(<Spinner />);
+      expect(screen.getByText('Loading')).toBeTruthy();
+    });
+
+    it('respects custom label', () => {
+      render(<Spinner label="Saving" />);
+      expect(screen.getByText('Saving')).toBeTruthy();
+    });
+
+    it('applies animate-spin class', () => {
+      const { container } = render(<Spinner />);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('animate-spin');
+    });
+
+    it('applies motion-reduce:animate-none class (WCAG 2.3.3)', () => {
+      const { container } = render(<Spinner />);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('motion-reduce:animate-none');
+    });
+
+    it('renders the spinning arc SVG path', () => {
+      const { container } = render(<Spinner />);
+      const path = container.querySelector('path');
+      expect(path).toBeTruthy();
+    });
+  });
+
+  describe('size axis', () => {
+    it.each([
+      ['xs', 'w-3'],
+      ['sm', 'w-4'],
+      ['md', 'w-5'],
+      ['lg', 'w-6'],
+      ['xl', 'w-8'],
+    ] as const)('size=%s → %s', (size, expected) => {
+      const { container } = render(<Spinner size={size} />);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain(expected);
+    });
+  });
+
+  describe('color resolution', () => {
+    it('omits text-* class when color is undefined (inherits currentColor)', () => {
+      const { container } = render(<Spinner />);
+      const root = container.firstElementChild!;
+      // No text-{color}-600 class — color flows in via currentColor
+      // from the parent.
+      expect(root.className).not.toMatch(/text-(neutral|primary|secondary|success|warning|danger|info)-/);
+    });
+
+    it('applies text-primary-600 when color="primary"', () => {
+      const { container } = render(<Spinner color="primary" />);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('text-primary-600');
+    });
+
+    it('applies text-danger-600 when color="danger"', () => {
+      const { container } = render(<Spinner color="danger" />);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('text-danger-600');
+    });
+  });
+
+  describe('thickness', () => {
+    it('default thickness=md → stroke-width=2.25', () => {
+      const { container } = render(<Spinner />);
+      const path = container.querySelector('path')!;
+      expect(path.getAttribute('stroke-width')).toBe('2.25');
+    });
+
+    it('thickness=thin → stroke-width=1.5', () => {
+      const { container } = render(<Spinner thickness="thin" />);
+      const path = container.querySelector('path')!;
+      expect(path.getAttribute('stroke-width')).toBe('1.5');
+    });
+
+    it('thickness=thick → stroke-width=3', () => {
+      const { container } = render(<Spinner thickness="thick" />);
+      const path = container.querySelector('path')!;
+      expect(path.getAttribute('stroke-width')).toBe('3');
+    });
+  });
+
+  describe('withTrack', () => {
+    it('does NOT render the track circle by default', () => {
+      const { container } = render(<Spinner />);
+      // Only the arc <path> — no <circle>.
+      expect(container.querySelector('circle')).toBeNull();
+    });
+
+    it('renders a track circle when withTrack=true', () => {
+      const { container } = render(<Spinner withTrack />);
+      const circle = container.querySelector('circle');
+      expect(circle).toBeTruthy();
+    });
+
+    it('track has stroke-opacity=0.2', () => {
+      const { container } = render(<Spinner withTrack />);
+      const circle = container.querySelector('circle')!;
+      expect(circle.getAttribute('stroke-opacity')).toBe('0.2');
+    });
+  });
+
+  describe('delay (anti-flash)', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('renders null for the first `delay` ms', () => {
+      const { container } = render(<Spinner delay={150} />);
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('renders the spinner after `delay` ms have elapsed', () => {
+      const { container } = render(<Spinner delay={150} />);
+      expect(container.firstChild).toBeNull();
+      act(() => {
+        vi.advanceTimersByTime(150);
+      });
+      expect(container.firstChild).toBeTruthy();
+    });
+
+    it('renders immediately when delay=0 (synchronous path)', () => {
+      const { container } = render(<Spinner delay={0} />);
+      expect(container.firstChild).toBeTruthy();
+    });
+
+    it('renders immediately when delay is omitted', () => {
+      const { container } = render(<Spinner />);
+      expect(container.firstChild).toBeTruthy();
+    });
+  });
+
+  describe('visibleWhen bridge', () => {
+    it('renders when visibleWhen returns true', () => {
+      render(<Spinner visibleWhen={() => true} />);
+      expect(screen.getByRole('status')).toBeTruthy();
+    });
+
+    it('returns null when visibleWhen returns false', () => {
+      const { container } = render(<Spinner visibleWhen={() => false} />);
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('renders normally when visibleWhen is omitted', () => {
+      render(<Spinner />);
+      expect(screen.getByRole('status')).toBeTruthy();
+    });
+  });
+
+  describe('overrides', () => {
+    it('appends sx', () => {
+      const { container } = render(<Spinner sx="mt-4" />);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('mt-4');
+    });
+
+    it('appends className', () => {
+      const { container } = render(<Spinner className="my-custom-spinner" />);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('my-custom-spinner');
+    });
+  });
+});

package/src/components/Spinner/Spinner.tsx

@@ -0,0 +1,158 @@
+import { forwardRef, useContext, useEffect, useState } from 'react';
+import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
+import { cn } from '../../utils/cn.js';
+import {
+  SPINNER_STROKE_WIDTH,
+  SPINNER_TRACK_OPACITY,
+  spinnerVariants,
+} from './spinner.variants.js';
+import type { SpinnerProps } from './spinner.types.js';
+
+/**
+ * `<Spinner>` — rotating-arc loading indicator.
+ *
+ * Visual: a partial-arc SVG rotating via Tailwind's `animate-spin`
+ * (pure CSS, GPU-accelerated). Optional `withTrack` renders a faint
+ * ghost ring (20% opacity of currentColor) behind the arc — the
+ * standard "premium spinner" pattern used by Stripe / Vercel / Linear.
+ *
+ * Color resolution:
+ *   - `color="primary"` (or any 7 intent) → `text-{color}-600` class
+ *     → SVG `stroke="currentColor"` picks it up
+ *   - `color` omitted → no `text-*` class emitted → SVG inherits
+ *     parent's text color via `currentColor`. **This is the right
+ *     default for nested usage** (inside Button, Alert, Card).
+ *
+ * A11y:
+ *   - `role="status"` on the wrapper
+ *   - `aria-live="polite"` so SR queues the announcement
+ *   - visually-hidden text label inside (`'Loading'` default)
+ *   - `animate-spin` is gated on `motion-reduce` (WCAG 2.3.3)
+ *
+ * Delay (anti-flash):
+ *   - `delay={150}` mounts as `null` for the first 150ms, then swaps
+ *     to the actual SVG. Quick operations that finish before 150ms
+ *     never render the spinner — eliminates the "flash" UX bug.
+ *
+ * @example
+ * ```tsx
+ * // 1. Inside a Button — inherits text color
+ * <button><Spinner size="sm" /> Saving...</button>
+ *
+ * // 2. Standalone with explicit color
+ * <Spinner color="primary" size="lg" label="Loading dashboard data" />
+ *
+ * // 3. Anti-flash on quick submits
+ * <Spinner visibleWhen={() => isSubmitting} delay={150} />
+ *
+ * // 4. With track for busy backgrounds
+ * <Spinner color="primary" withTrack size="xl" />
+ * ```
+ */
+export const Spinner = forwardRef<HTMLSpanElement, SpinnerProps>(function Spinner(
+  props,
+  ref
+) {
+  const {
+    size = 'md',
+    color,
+    thickness = 'md',
+    withTrack = false,
+    label = 'Loading',
+    delay = 0,
+    visibleWhen,
+    sx,
+    className,
+  } = props;
+
+  // Bridge — engine-reactive visibility. Hook called unconditionally
+  // (rules-of-hooks). Outside a `<DashForm>`, predicate evaluated as
+  // a plain closure.
+  const bridge = useContext(DashFormContext);
+  const isBridgeVisible = useEngineVisibility(bridge?.engine, visibleWhen);
+
+  // Anti-flash delay — render `null` for the first `delay` ms after
+  // the spinner becomes visible. Skipping the timer entirely when
+  // delay=0 keeps the synchronous render path for the common case.
+  const [delayElapsed, setDelayElapsed] = useState(delay <= 0);
+  useEffect(() => {
+    if (delay <= 0) {
+      setDelayElapsed(true);
+      return;
+    }
+    setDelayElapsed(false);
+    const handle = setTimeout(() => setDelayElapsed(true), delay);
+    return () => clearTimeout(handle);
+  }, [delay]);
+
+  if (!isBridgeVisible || !delayElapsed) return null;
+
+  const classes = cn(
+    spinnerVariants({ size, color }),
+    sx,
+    className
+  );
+
+  const strokeWidth = SPINNER_STROKE_WIDTH[thickness];
+
+  // Decorative mode — when label is explicitly empty (""), suppress
+  // role="status" and the visually-hidden label entirely. Used when
+  // the Spinner is embedded inside another component that already
+  // announces its loading state via `aria-busy` (e.g., Button) — the
+  // inner spinner is then purely visual chrome.
+  const isDecorative = label === '';
+
+  return (
+    <span
+      ref={ref}
+      className={classes}
+      role={isDecorative ? undefined : 'status'}
+      aria-live={isDecorative ? undefined : 'polite'}
+      aria-hidden={isDecorative ? true : undefined}
+    >
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        width="100%"
+        height="100%"
+      >
+        {/* Track ring — faint full circle behind the arc. Renders
+            only when `withTrack` is true. Uses currentColor with
+            explicit opacity so it follows the parent's text color in
+            BOTH light and dark mode without any `dark:` variant. */}
+        {withTrack && (
+          <circle
+            cx="12"
+            cy="12"
+            r="9"
+            stroke="currentColor"
+            strokeWidth={strokeWidth}
+            strokeOpacity={SPINNER_TRACK_OPACITY}
+            fill="none"
+          />
+        )}
+        {/* Spinning arc — a 90° segment of the circle. The rotation
+            comes from the wrapper's `animate-spin` class, not from
+            transforming the SVG itself. `strokeLinecap="round"` gives
+            the soft, premium-looking ends. */}
+        <path
+          d="M21 12a9 9 0 0 0-9-9"
+          stroke="currentColor"
+          strokeWidth={strokeWidth}
+          strokeLinecap="round"
+          fill="none"
+        />
+      </svg>
+      {/* Visually-hidden label for screen readers. Skipped entirely
+          in decorative mode. */}
+      {!isDecorative && (
+        <span className="absolute -m-px h-px w-px overflow-hidden whitespace-nowrap border-0 p-0 [clip:rect(0,0,0,0)]">
+          {label}
+        </span>
+      )}
+    </span>
+  );
+});
+
+Spinner.displayName = 'Spinner';