@dashforge/tw 1.1.0 → 1.1.1

package/src/components/_shared/data/useVirtualizer.ts

@@ -1,199 +0,0 @@
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
-
-/**
- * Window descriptor — which slice of the row array is currently
- * mounted in DOM, and how much spacer height to render above and
- * below the visible window so the scrollbar size matches the
- * "virtual" total height.
- */
-export interface VirtualizerWindow {
-  /** First row index inside the visible window (inclusive). */
-  startIndex: number;
-  /** Last row index inside the visible window (inclusive). */
-  endIndex: number;
-  /** Pixels to render above the visible rows (spacer top). */
-  paddingTop: number;
-  /** Pixels to render below the visible rows (spacer bottom). */
-  paddingBottom: number;
-}
-
-export interface UseVirtualizerArgs {
-  /** Total number of rows in the underlying data set. */
-  totalCount: number;
-  /** Fixed row height in pixels. */
-  rowHeight: number;
-  /**
-   * Visible viewport height in pixels. Pass the height of the
-   * scroll container.
-   */
-  viewportHeight: number;
-  /** Current scrollTop of the scroll container. */
-  scrollTop: number;
-  /**
-   * How many extra rows to render above / below the visible window
-   * for smoother scrolling (reduces blank-flash on fast scroll).
-   * @default 5
-   */
-  overscan?: number;
-}
-
-/**
- * Compute the visible window of rows + the spacer heights given the
- * current scroll position. Pure function — exported for testability.
- *
- * @example
- * ```ts
- * computeWindow({ totalCount: 1000, rowHeight: 48, viewportHeight: 600,
- *                 scrollTop: 0, overscan: 5 });
- * // → { startIndex: 0, endIndex: 17, paddingTop: 0, paddingBottom: 47136 }
- * ```
- */
-export function computeWindow(args: UseVirtualizerArgs): VirtualizerWindow {
-  const { totalCount, rowHeight, viewportHeight, scrollTop, overscan = 5 } = args;
-
-  if (totalCount <= 0 || rowHeight <= 0 || viewportHeight <= 0) {
-    return { startIndex: 0, endIndex: -1, paddingTop: 0, paddingBottom: 0 };
-  }
-
-  // Raw visible range from scrollTop alone.
-  const rawStart = Math.floor(scrollTop / rowHeight);
-  const rawEnd = Math.ceil((scrollTop + viewportHeight) / rowHeight);
-
-  // Apply overscan + clamp to [0, totalCount - 1].
-  const startIndex = Math.max(0, rawStart - overscan);
-  const endIndex = Math.min(totalCount - 1, rawEnd + overscan);
-
-  const paddingTop = startIndex * rowHeight;
-  const paddingBottom = Math.max(0, (totalCount - 1 - endIndex) * rowHeight);
-
-  return { startIndex, endIndex, paddingTop, paddingBottom };
-}
-
-/**
- * `useVirtualizer` — viewport-based row windowing for `<DataGrid>`.
- *
- * Hand-rolled (no `@tanstack/react-virtual` dep — constraint memorized
- * in `feedback_dashforge_preset_is_identity` companion: "no new
- * external runtime deps"). Uses scroll event + `requestAnimationFrame`
- * debounce + `ResizeObserver` on the container. Fixed row height
- * only in v1 — variable-height with measurement cache deferred to
- * v1-bis.
- *
- * Returns:
- *  - `scrollRef`: attach to the scroll container `<div>`.
- *  - `window`: which row indices to mount + top/bottom spacer heights
- *    to preserve scroll-area size.
- *  - `viewportHeight`: current container height (re-measured on
- *    `ResizeObserver` ticks).
- *
- * The DataGrid renders `rows.slice(window.startIndex, window.endIndex + 1)`
- * between two spacer `<tr style={{ height: paddingTop }} />` elements
- * (above and below). This preserves `<table>` semantics — screen
- * readers see a continuous structure with `aria-hidden` spacers.
- *
- * @example
- * ```tsx
- * const { scrollRef, window } = useVirtualizer({
- *   totalCount: rows.length,
- *   rowHeight: 48,
- *   overscan: 5,
- * });
- *
- * return (
- *   <div ref={scrollRef} style={{ height: 600, overflow: 'auto' }}>
- *     <table>
- *       <tbody>
- *         <tr aria-hidden="true" style={{ height: window.paddingTop }} />
- *         {rows.slice(window.startIndex, window.endIndex + 1).map(...)}
- *         <tr aria-hidden="true" style={{ height: window.paddingBottom }} />
- *       </tbody>
- *     </table>
- *   </div>
- * );
- * ```
- */
-export function useVirtualizer(args: {
-  totalCount: number;
-  rowHeight: number;
-  overscan?: number;
-  /**
-   * Initial viewport height — used before the ResizeObserver
-   * settles on first paint. Pass an explicit `height` prop value
-   * if you have one; otherwise the hook re-measures on layout.
-   * @default 400
-   */
-  initialViewportHeight?: number;
-}): {
-  scrollRef: React.RefObject<HTMLDivElement | null>;
-  window: VirtualizerWindow;
-  viewportHeight: number;
-} {
-  const { totalCount, rowHeight, overscan = 5, initialViewportHeight = 400 } = args;
-
-  const scrollRef = useRef<HTMLDivElement | null>(null);
-  const [scrollTop, setScrollTop] = useState(0);
-  const [viewportHeight, setViewportHeight] = useState(initialViewportHeight);
-
-  // Debounce scroll handler via requestAnimationFrame so we never
-  // re-render more than once per paint frame even when the scroll
-  // event fires rapidly during fast scrolling.
-  const rafIdRef = useRef<number | null>(null);
-  const handleScroll = useCallback(() => {
-    if (rafIdRef.current != null) return;
-    rafIdRef.current = requestAnimationFrame(() => {
-      rafIdRef.current = null;
-      const el = scrollRef.current;
-      if (!el) return;
-      setScrollTop(el.scrollTop);
-    });
-  }, []);
-
-  // Attach scroll listener.
-  useEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
-    el.addEventListener('scroll', handleScroll, { passive: true });
-    return () => {
-      el.removeEventListener('scroll', handleScroll);
-      if (rafIdRef.current != null) {
-        cancelAnimationFrame(rafIdRef.current);
-        rafIdRef.current = null;
-      }
-    };
-  }, [handleScroll]);
-
-  // Track container viewport height via ResizeObserver — re-virtualize
-  // when the container size changes (window resize, sidebar collapse,
-  // etc.). Use `useLayoutEffect` so the first measurement happens
-  // before paint to avoid a flash of stale window.
-  //
-  // **Defensive**: only accept measurements > 0. jsdom (test env)
-  // returns `clientHeight === 0` for unmounted containers, which would
-  // collapse the window to empty. The hook keeps the
-  // `initialViewportHeight` fallback in that case.
-  useLayoutEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
-    if (el.clientHeight > 0) {
-      setViewportHeight(el.clientHeight);
-    }
-    if (typeof ResizeObserver === 'undefined') return;
-    const observer = new ResizeObserver((entries) => {
-      const entry = entries[0];
-      if (!entry || entry.contentRect.height <= 0) return;
-      setViewportHeight(entry.contentRect.height);
-    });
-    observer.observe(el);
-    return () => observer.disconnect();
-  }, []);
-
-  const window = computeWindow({
-    totalCount,
-    rowHeight,
-    viewportHeight,
-    scrollTop,
-    overscan,
-  });
-
-  return { scrollRef, window, viewportHeight };
-}

package/src/components/_shared/resolveValidationState.ts

@@ -1,60 +0,0 @@
-import type { ReactNode } from 'react';
-import type { DashFormBridge } from '@dashforge/ui-core';
-
-/**
- * Resolved validation state for a bridge-managed field.
- *
- * Returned by `resolveValidationState`, this is consumed by all form
- * components that surface error + helper text (TextField, Checkbox,
- * Switch, …) to derive their final render state.
- */
-export interface ValidationState {
-  error: boolean;
-  helperText: ReactNode;
-}
-
-/**
- * Compute `error` + `helperText` for a bridge-managed field.
- *
- * **Renderer-agnostic** — copy of the MUI-side
- * `textField.validation.ts`. Promoted to a `_shared/` directory inside
- * `@dashforge/tw` so all form components (TextField + Checkbox +
- * Switch) reuse the same precedence logic without depending on a
- * specific component folder.
- *
- * Precedence rules (matches MUI side byte-for-byte):
- *
- *  1. **Explicit props win.** If the user passed `error` / `helperText`
- *     explicitly, those values are used as-is.
- *  2. **Auto values are gated by interaction.** The bridge's error is
- *     surfaced only when the field is `touched` OR the form has been
- *     submitted at least once (`submitCount > 0`). This prevents the
- *     "error spam while typing" anti-pattern.
- *  3. **`error === false` explicitly clears the bridge's error message
- *     text.** Useful for forcing a "valid" visual state regardless of
- *     bridge state.
- *
- * @param name         field name registered with the bridge
- * @param bridge       active `DashFormBridge` (guaranteed non-null at
- *                     call sites by the surrounding `if (bridge)`)
- * @param explicitError    `error` prop from the consumer
- * @param explicitHelperText `helperText` prop from the consumer
- */
-export function resolveValidationState(
-  name: string,
-  bridge: DashFormBridge,
-  explicitError: boolean | undefined,
-  explicitHelperText: ReactNode | undefined
-): ValidationState {
-  const autoErr = bridge.getError(name) ?? null;
-  const autoTouched = bridge.isTouched(name) ?? false;
-  const submitCount = bridge.submitCount ?? 0;
-
-  const allowAutoError = autoTouched || submitCount > 0;
-
-  const error = explicitError ?? (Boolean(autoErr) && allowAutoError);
-  const helperText =
-    explicitHelperText ?? (allowAutoError ? autoErr?.message : undefined);
-
-  return { error, helperText };
-}

package/src/components/_shared/severity/index.ts

@@ -1,33 +0,0 @@
-/**
- * `_shared/severity/` — foundation for every severity-aware
- * component in `@dashforge/tw` (Alert, refactored Snackbar, future
- * Banner / status indicators).
- *
- * Centralising:
- *   - the `Severity` and `SeverityVariant` taxonomies (mirror MUI;
- *     `danger` not `error` for token alignment)
- *   - the 3×4 token-driven color matrix (token-resolved, no hardcoded
- *     hex, no `dark:` variants on neutral)
- *   - the default per-severity inline SVG icons (`icon={false}` opt-out
- *     supported on consumer components)
- *   - the ARIA role helper (`alert` vs `status`)
- *
- * Consumers (Alert, Snackbar) import from this barrel — never reach
- * into the individual files.
- */
-
-export type {
-  Severity,
-  SeverityClasses,
-  SeverityVariant,
-} from './severity.types.js';
-
-export {
-  getSeverityClasses,
-  getSeverityRole,
-} from './severityVariants.js';
-
-export {
-  SEVERITY_DEFAULT_ICON,
-  getDefaultSeverityIcon,
-} from './severityIcons.js';

package/src/components/_shared/severity/severity.types.ts

@@ -1,50 +0,0 @@
-/**
- * Shared severity types — consumed by every component that surfaces
- * a "semantic visual tone" (Alert, Snackbar, Banner, Badge, Chip when
- * acting as a status indicator, …).
- *
- * **Naming choice**: we follow MUI's `severity` taxonomy
- * (`info / success / warning / danger`) and `variant` taxonomy
- * (`standard / filled / outlined`) so consumers porting from MUI keep
- * their muscle memory. The single Dashforge-specific divergence is
- * `danger` (not MUI's `error`) — chosen to match the `danger.*` token
- * palette in `@dashforge/tw-tokens`. Semantically identical to MUI's
- * `error`; documented in the migration guide.
- *
- * @module @dashforge/tw/_shared/severity
- */
-
-/**
- * Visual severity — drives the color treatment of a component.
- * `danger` instead of `error` for token-palette alignment.
- */
-export type Severity = 'info' | 'success' | 'warning' | 'danger';
-
-/**
- * Variant of the severity surface. Mirrors MUI's `Alert` variant axis
- * 1:1 so the migration story is trivial.
- *
- * - `standard` (default) — tinted soft background with severity-toned
- *   text. The "all-purpose" reading. Most modern design systems call
- *   this "soft".
- * - `filled` — solid severity background with light text. Strong
- *   visual weight, for high-priority callouts.
- * - `outlined` — transparent background with severity border and
- *   severity-toned text. Minimal weight, for dense layouts.
- */
-export type SeverityVariant = 'standard' | 'filled' | 'outlined';
-
-/**
- * Per-slot Tailwind class strings emitted by the severity matrix for
- * one (variant, severity) pair. Resolved through `dashforgePreset()`
- * to CSS variables → patch-theme friendly.
- */
-export interface SeverityClasses {
-  /** `<root>` surface: background + text + border base. */
-  surface: string;
-  /** Border overrides (kept separate from `surface` so components can
-   *  swap `border-2` etc. without losing the color). */
-  border: string;
-  /** Icon container color (uses `currentColor` on the inner SVG). */
-  icon: string;
-}

package/src/components/_shared/severity/severityIcons.tsx

@@ -1,104 +0,0 @@
-import type { ComponentType, ReactNode, SVGProps } from 'react';
-import type { Severity } from './severity.types.js';
-
-/**
- * Default severity icons — inline stroke SVG, no runtime icon dep.
- *
- * Convention copied from `Calendar` / `Autocomplete` (existing pattern
- * in the lib): icons live INLINE inside the component module, never as
- * imports from an external icon library. The "no icons in the library"
- * principle means **no external icon package** (`lucide-react`,
- * `phosphor-icons`, etc.) — small file-local SVG functions are
- * allowed and already used.
- *
- * All icons:
- *   - 20×20 viewBox (5:1 ratio of intrinsic size to body text-sm)
- *   - `stroke="currentColor"` — colored via the parent's
- *     `text-<severity>-600` class through the severity matrix
- *   - `fill="none"` — outline style, matches Tabler / Heroicons /
- *     Phosphor-outline conventions, low visual weight
- *   - `aria-hidden="true"` — the message text carries the semantic;
- *     the icon is decorative reinforcement, not the announcement
- */
-
-type IconProps = SVGProps<SVGSVGElement>;
-
-const BASE_PROPS: IconProps = {
-  width: '1.25em',
-  height: '1.25em',
-  viewBox: '0 0 20 20',
-  fill: 'none',
-  stroke: 'currentColor',
-  strokeWidth: 1.5,
-  strokeLinecap: 'round',
-  strokeLinejoin: 'round',
-  'aria-hidden': 'true',
-};
-
-function InfoIcon(props: IconProps) {
-  return (
-    <svg {...BASE_PROPS} {...props}>
-      <circle cx="10" cy="10" r="8.25" />
-      <path d="M10 6.5h.01M10 9.5v4" />
-    </svg>
-  );
-}
-
-function SuccessIcon(props: IconProps) {
-  return (
-    <svg {...BASE_PROPS} {...props}>
-      <circle cx="10" cy="10" r="8.25" />
-      <path d="m6.5 10 2.5 2.5 4.5-5" />
-    </svg>
-  );
-}
-
-function WarningIcon(props: IconProps) {
-  return (
-    <svg {...BASE_PROPS} {...props}>
-      <path d="M10 2.5 18 17H2L10 2.5Z" />
-      <path d="M10 8v3.5M10 14.5h.01" />
-    </svg>
-  );
-}
-
-function DangerIcon(props: IconProps) {
-  return (
-    <svg {...BASE_PROPS} {...props}>
-      <circle cx="10" cy="10" r="8.25" />
-      <path d="m7 7 6 6M13 7l-6 6" />
-    </svg>
-  );
-}
-
-/**
- * Map of severity → default Icon component. Used by Alert (and
- * eventually Snackbar / Banner / etc.) to render the per-severity
- * default when the consumer doesn't pass a custom `icon` prop and
- * doesn't opt-out with `icon={false}`.
- */
-export const SEVERITY_DEFAULT_ICON: Record<Severity, ComponentType<IconProps>> = {
-  info: InfoIcon,
-  success: SuccessIcon,
-  warning: WarningIcon,
-  danger: DangerIcon,
-};
-
-/**
- * Convenience helper — render the default icon for a severity as a
- * `ReactNode`, ready to inject into a JSX slot.
- *
- * @example
- * <span className={severityClasses.icon}>
- *   {getDefaultSeverityIcon('warning')}
- * </span>
- */
-export function getDefaultSeverityIcon(severity: Severity): ReactNode {
-  const Icon = SEVERITY_DEFAULT_ICON[severity];
-  return <Icon />;
-}
-
-// Re-export individual icons for cases where a consumer wants the same
-// glyph in a custom context (e.g. inline in a paragraph). Not part of
-// the public `@dashforge/tw` barrel — internal use only.
-export { InfoIcon, SuccessIcon, WarningIcon, DangerIcon };

package/src/components/_shared/severity/severityVariants.test.ts

@@ -1,136 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  getSeverityClasses,
-  getSeverityRole,
-} from './severityVariants.js';
-import { SEVERITY_DEFAULT_ICON } from './severityIcons.js';
-import type { Severity, SeverityVariant } from './severity.types.js';
-
-/**
- * Exhaustive coverage of the 3×4 severity matrix.
- *
- * The matrix is the foundation every severity-aware component reads
- * from. Regressions here ripple through Alert, Snackbar, future
- * Banner, etc. — so we lock down every cell, the role helper, and the
- * default-icon map.
- */
-
-const SEVERITIES: Severity[] = ['info', 'success', 'warning', 'danger'];
-const VARIANTS: SeverityVariant[] = ['standard', 'filled', 'outlined'];
-
-describe('getSeverityClasses', () => {
-  it('returns a SeverityClasses object for every (variant, severity) pair', () => {
-    for (const variant of VARIANTS) {
-      for (const severity of SEVERITIES) {
-        const classes = getSeverityClasses(variant, severity);
-        expect(classes).toBeDefined();
-        expect(typeof classes.surface).toBe('string');
-        expect(typeof classes.border).toBe('string');
-        expect(typeof classes.icon).toBe('string');
-        expect(classes.surface.length).toBeGreaterThan(0);
-        expect(classes.border.length).toBeGreaterThan(0);
-        expect(classes.icon.length).toBeGreaterThan(0);
-      }
-    }
-  });
-
-  it('uses token-driven color utilities (no hardcoded hex, no dark: variants)', () => {
-    for (const variant of VARIANTS) {
-      for (const severity of SEVERITIES) {
-        const classes = getSeverityClasses(variant, severity);
-        const all = `${classes.surface} ${classes.border} ${classes.icon}`;
-        // No hex literals
-        expect(all).not.toMatch(/#[0-9a-fA-F]{3,8}/);
-        // No dark: variants — preset auto-inverts neutral via CSS var swap
-        expect(all).not.toMatch(/\bdark:/);
-        // Severity palette names appear in the utilities
-        if (severity === 'info' || severity === 'success' || severity === 'warning' || severity === 'danger') {
-          expect(all).toContain(severity);
-        }
-      }
-    }
-  });
-
-  describe('standard variant — tinted soft surface', () => {
-    it.each(SEVERITIES)('uses bg-<severity>-50 + text-<severity>-900 for %s', (sev) => {
-      const { surface } = getSeverityClasses('standard', sev);
-      expect(surface).toContain(`bg-${sev}-50`);
-      expect(surface).toContain(`text-${sev}-900`);
-    });
-
-    it.each(SEVERITIES)('uses border-<severity>-100 for %s', (sev) => {
-      const { border } = getSeverityClasses('standard', sev);
-      expect(border).toContain(`border-${sev}-100`);
-    });
-
-    it.each(SEVERITIES)('uses text-<severity>-600 for icon in %s', (sev) => {
-      const { icon } = getSeverityClasses('standard', sev);
-      expect(icon).toContain(`text-${sev}-600`);
-    });
-  });
-
-  describe('filled variant — solid colored surface', () => {
-    it.each(SEVERITIES)('uses bg-<severity>-600 + text-<severity>-50 for %s', (sev) => {
-      const { surface } = getSeverityClasses('filled', sev);
-      expect(surface).toContain(`bg-${sev}-600`);
-      expect(surface).toContain(`text-${sev}-50`);
-    });
-
-    it.each(SEVERITIES)('uses border-<severity>-700 for %s', (sev) => {
-      const { border } = getSeverityClasses('filled', sev);
-      expect(border).toContain(`border-${sev}-700`);
-    });
-
-    it.each(SEVERITIES)('icon inherits the light tone (text-<severity>-50) for %s', (sev) => {
-      const { icon } = getSeverityClasses('filled', sev);
-      expect(icon).toContain(`text-${sev}-50`);
-    });
-  });
-
-  describe('outlined variant — transparent surface', () => {
-    it.each(SEVERITIES)('uses bg-transparent + text-<severity>-700 for %s', (sev) => {
-      const { surface } = getSeverityClasses('outlined', sev);
-      expect(surface).toContain('bg-transparent');
-      expect(surface).toContain(`text-${sev}-700`);
-    });
-
-    it.each(SEVERITIES)('uses border-<severity>-300 for %s', (sev) => {
-      const { border } = getSeverityClasses('outlined', sev);
-      expect(border).toContain(`border-${sev}-300`);
-    });
-  });
-
-  it('never reuses primary-* for info severity (info has its own token scale)', () => {
-    // Regression: Snackbar 1.0.x aliased `info` to `primary-*`. The
-    // shared foundation MUST use the dedicated `info-*` scale so a
-    // patchTheme({ info: … }) call does not bleed into primary.
-    for (const variant of VARIANTS) {
-      const classes = getSeverityClasses(variant, 'info');
-      const all = `${classes.surface} ${classes.border} ${classes.icon}`;
-      expect(all).not.toMatch(/\bprimary-/);
-      expect(all).toContain('info-');
-    }
-  });
-});
-
-describe('getSeverityRole', () => {
-  it('returns "alert" for assertive severities (warning, danger)', () => {
-    expect(getSeverityRole('warning')).toBe('alert');
-    expect(getSeverityRole('danger')).toBe('alert');
-  });
-
-  it('returns "status" for polite severities (info, success)', () => {
-    expect(getSeverityRole('info')).toBe('status');
-    expect(getSeverityRole('success')).toBe('status');
-  });
-});
-
-describe('SEVERITY_DEFAULT_ICON', () => {
-  it('exposes a default icon component for every severity', () => {
-    for (const sev of SEVERITIES) {
-      const Icon = SEVERITY_DEFAULT_ICON[sev];
-      expect(Icon).toBeDefined();
-      expect(typeof Icon).toBe('function');
-    }
-  });
-});