@dashforge/tw 1.0.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/themeIdentity.test.ts

@@ -1,113 +0,0 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { describe, it, expect } from 'vitest';
-
-/**
- * Package-level theme-identity regression test.
- *
- * Enforces the Dashforge rule
- * (memory: `feedback_dashforge_preset_is_identity`):
- * the `@dashforge/tw-theme` default preset auto-inverts the neutral
- * palette via a CSS-variable swap (`bg-neutral-50` is light surface
- * in light mode AND dark surface in dark mode — same class, different
- * physical color). Adding a `dark:` Tailwind variant on a
- * `neutral-*` class creates a DOUBLE inversion that breaks dark mode.
- *
- * The Sprint 4.1 Table fix established the rule; Sprint 4.3 applies
- * it to the whole catalog and adds this test as a regression guard.
- *
- * **Allowed exception** (Category B in `THEME-AUDIT.md`): the pattern
- * `bg-white dark:bg-neutral-N` / `fill-white dark:fill-neutral-N` is
- * LEGITIMATE — `bg-white` is hardcoded (no auto-inversion via CSS
- * vars) so a `dark:` counterpart IS needed to get a dark elevated
- * surface in dark mode. The regex below strips these legitimate
- * patterns before scanning for the anti-pattern.
- *
- * Color palettes (`primary` / `secondary` / `success` / `warning` /
- * `danger` / `info`) are EXEMPT from this rule by design — they
- * do not auto-invert, so `dark:` shifts on them are legitimate
- * design choices (tone refinement across modes).
- */
-const COMPONENTS_DIR = join(__dirname, '..');
-
-// The legitimate Category B patterns we allow:
-//  1. `bg-white dark:bg-neutral-N`
-//  2. `fill-white dark:fill-neutral-N`
-//  3. variant-prefixed versions, e.g.
-//     `data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-N`
-//
-// Strip these from the source before scanning for the anti-pattern.
-const CATEGORY_B_RE =
-  /(?:[\w[\]:-]+:)?(?:bg|fill)-white\s+dark:(?:[\w[\]:-]+:)*(?:bg|fill)-neutral-\d+/g;
-
-// Anti-pattern: any `dark:` variant on a `neutral-N` class.
-// Covers `bg`, `text`, `border`, `ring`, `placeholder:text`,
-// `hover:bg`, `focus-visible:bg`, `data-[state=*]:bg`, etc.
-const NEUTRAL_DARK_RE =
-  /dark:(?:[\w[\]:-]+:)*(?:bg|text|border|ring|fill|placeholder|focus-visible|hover|focus|data)?-?neutral-\d+/;
-
-function walkSourceFiles(dir: string): string[] {
-  const entries = readdirSync(dir, { withFileTypes: true });
-  const out: string[] = [];
-  for (const entry of entries) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      out.push(...walkSourceFiles(full));
-      continue;
-    }
-    if (!entry.isFile()) continue;
-    if (entry.name.endsWith('.test.ts')) continue;
-    if (entry.name.endsWith('.test.tsx')) continue;
-    if (entry.name.endsWith('.spec.ts')) continue;
-    if (entry.name.endsWith('.spec.tsx')) continue;
-    if (!/\.(ts|tsx)$/.test(entry.name)) continue;
-    out.push(full);
-  }
-  return out;
-}
-
-describe('Catalog — theme identity rule (no `dark:` on neutral palette)', () => {
-  const files = walkSourceFiles(COMPONENTS_DIR);
-
-  it('finds the catalog source files', () => {
-    expect(files.length).toBeGreaterThan(20);
-  });
-
-  for (const file of files) {
-    const rel = file.replace(COMPONENTS_DIR + '/', '');
-    it(`${rel} — no \`dark:*-neutral-N\` anti-pattern`, () => {
-      const source = readFileSync(file, 'utf-8');
-      const stripped = source
-        // 1. Strip legitimate Category B patterns (bg-white / fill-white
-        //    paired with a `dark:` neutral target — bg-white doesn't
-        //    auto-invert, so the `dark:` is intentional).
-        .replace(CATEGORY_B_RE, '')
-        // 2. Strip comments — the regex examples in THEME-AUDIT and
-        //    this test source itself contain the anti-pattern as text.
-        .replace(/\/\/.*$/gm, '')
-        .replace(/\/\*[\s\S]*?\*\//g, '');
-
-      const match = stripped.match(NEUTRAL_DARK_RE);
-      if (match) {
-        const idx = stripped.indexOf(match[0]);
-        const context = stripped.slice(
-          Math.max(0, idx - 80),
-          idx + match[0].length + 80,
-        );
-        throw new Error(
-          `Found \`dark:*-neutral-N\` anti-pattern in ${rel}:\n` +
-            `  ...${context.replace(/\s+/g, ' ').trim()}...\n\n` +
-            `Rule: dashforgePreset() auto-inverts neutral palette via CSS-var swap. ` +
-            `Adding \`dark:bg-neutral-N\` (or similar) creates double inversion ` +
-            `and breaks dark mode.\n\n` +
-            `Fix: drop the \`dark:\` variant — the base class auto-inverts.\n\n` +
-            `Exception: \`bg-white dark:bg-neutral-N\` IS allowed (bg-white doesn't ` +
-            `auto-invert, the dark variant is required for proper dark elevation).\n\n` +
-            `See: libs/dashforge/tw/THEME-AUDIT.md, ` +
-            `memory \`feedback_dashforge_preset_is_identity\`.`,
-        );
-      }
-      expect(match).toBeNull();
-    });
-  }
-});

package/src/hooks/useAccessState.spec.tsx

@@ -1,161 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { renderHook } from '@testing-library/react';
-import { RbacProvider } from '@dashforge/rbac';
-import type {
-  RbacPolicy,
-  Subject,
-  AccessRequirement,
-} from '@dashforge/rbac';
-import { useAccessState } from './useAccessState.js';
-
-/**
- * TW-side copy of the MUI useAccessState unit test, kept independent
- * per the isolation contract. The hook contract is identical so the
- * MUI test cases double as the source of truth for behaviour parity.
- */
-
-const FULL_ACCESS_POLICY: RbacPolicy = {
-  roles: [
-    {
-      name: 'admin',
-      permissions: [{ resource: '*', action: '*', effect: 'allow' }],
-    },
-  ],
-};
-
-const READ_ONLY_POLICY: RbacPolicy = {
-  roles: [
-    {
-      name: 'viewer',
-      permissions: [
-        { resource: 'document', action: 'read', effect: 'allow' },
-        { resource: 'document', action: 'update', effect: 'deny' },
-      ],
-    },
-  ],
-};
-
-const adminSubject: Subject = { id: 'admin-user', roles: ['admin'] };
-const viewerSubject: Subject = { id: 'viewer-user', roles: ['viewer'] };
-
-function wrapWithRbac(policy: RbacPolicy, subject: Subject) {
-  return function Wrapper({ children }: { children: React.ReactNode }) {
-    return (
-      <RbacProvider policy={policy} subject={subject}>
-        {children}
-      </RbacProvider>
-    );
-  };
-}
-
-describe('useAccessState (tw)', () => {
-  describe('no access requirement', () => {
-    it('returns default full-access state when access is undefined', () => {
-      const { result } = renderHook(() => useAccessState(undefined));
-      expect(result.current).toEqual({
-        visible: true,
-        disabled: false,
-        readonly: false,
-        granted: true,
-      });
-    });
-
-    it('returns stable identity across re-renders', () => {
-      const { result, rerender } = renderHook(() => useAccessState(undefined));
-      const first = result.current;
-      rerender();
-      expect(result.current).toBe(first);
-    });
-  });
-
-  describe('access requirement WITHOUT RbacProvider (fail-safe)', () => {
-    let warnSpy: ReturnType<typeof vi.spyOn>;
-    beforeEach(() => {
-      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
-    });
-    afterEach(() => {
-      warnSpy.mockRestore();
-    });
-
-    it('returns DEFAULT_ACCESS_STATE (fails open) when no provider mounted', () => {
-      const access: AccessRequirement = { resource: 'doc', action: 'read' };
-      const { result } = renderHook(() => useAccessState(access));
-      expect(result.current.visible).toBe(true);
-      expect(result.current.granted).toBe(true);
-    });
-
-    it('logs a dev-mode warning naming the missing requirement', () => {
-      const access: AccessRequirement = { resource: 'doc', action: 'update' };
-      renderHook(() => useAccessState(access));
-      expect(warnSpy).toHaveBeenCalled();
-      const msg = String(warnSpy.mock.calls[0]?.[0] ?? '');
-      expect(msg).toContain('No RbacProvider');
-      expect(msg).toContain('doc');
-      expect(msg).toContain('update');
-    });
-  });
-
-  describe('access requirement WITH RbacProvider', () => {
-    it('grants when policy allows', () => {
-      const access: AccessRequirement = { resource: 'document', action: 'read' };
-      const { result } = renderHook(() => useAccessState(access), {
-        wrapper: wrapWithRbac(FULL_ACCESS_POLICY, adminSubject),
-      });
-      expect(result.current.granted).toBe(true);
-      expect(result.current.visible).toBe(true);
-    });
-
-    it('denies (hide) when policy forbids and onUnauthorized=hide', () => {
-      const access: AccessRequirement = {
-        resource: 'document',
-        action: 'update',
-        onUnauthorized: 'hide',
-      };
-      const { result } = renderHook(() => useAccessState(access), {
-        wrapper: wrapWithRbac(READ_ONLY_POLICY, viewerSubject),
-      });
-      expect(result.current.granted).toBe(false);
-      expect(result.current.visible).toBe(false);
-    });
-
-    it('denies (disable) when policy forbids and onUnauthorized=disable', () => {
-      const access: AccessRequirement = {
-        resource: 'document',
-        action: 'update',
-        onUnauthorized: 'disable',
-      };
-      const { result } = renderHook(() => useAccessState(access), {
-        wrapper: wrapWithRbac(READ_ONLY_POLICY, viewerSubject),
-      });
-      expect(result.current.granted).toBe(false);
-      expect(result.current.visible).toBe(true);
-      expect(result.current.disabled).toBe(true);
-    });
-
-    it('denies (readonly) when policy forbids and onUnauthorized=readonly', () => {
-      const access: AccessRequirement = {
-        resource: 'document',
-        action: 'update',
-        onUnauthorized: 'readonly',
-      };
-      const { result } = renderHook(() => useAccessState(access), {
-        wrapper: wrapWithRbac(READ_ONLY_POLICY, viewerSubject),
-      });
-      expect(result.current.granted).toBe(false);
-      expect(result.current.readonly).toBe(true);
-    });
-  });
-
-  describe('memoization', () => {
-    it('returns identical reference when access reference stays the same', () => {
-      const access: AccessRequirement = { resource: 'doc', action: 'read' };
-      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
-      const { result, rerender } = renderHook(() => useAccessState(access));
-      const first = result.current;
-      rerender();
-      expect(result.current).toBe(first);
-      warnSpy.mockRestore();
-    });
-  });
-});

package/src/hooks/useAccessState.ts

@@ -1,81 +0,0 @@
-import { useMemo } from 'react';
-import { useRbacOptional, resolveAccessState } from '@dashforge/rbac';
-import type { AccessRequirement, AccessState } from '@dashforge/rbac';
-
-/**
- * Default full-access state. Returned when no access requirement is
- * supplied **or** when no `RbacProvider` is mounted (fail-safe default).
- *
- * @internal
- */
-const DEFAULT_ACCESS_STATE: AccessState = {
-  visible: true,
-  disabled: false,
-  readonly: false,
-  granted: true,
-};
-
-/**
- * Hook to resolve RBAC access state for a UI component.
- *
- * **TW-side copy of the MUI implementation** in `@dashforge/ui/src/hooks/useAccessState.ts`.
- * Per the architecture plan v2 (2026-05-15) the two ecosystems share
- * only the bridge layer (`@dashforge/forms` + `@dashforge/ui-core` +
- * `@dashforge/rbac`); UI-side hooks are duplicated intentionally so
- * the MUI and TW ecosystems remain fully isolated.
- *
- * The behaviour is byte-equivalent to the MUI side:
- *
- *  - If `access` is undefined → returns `DEFAULT_ACCESS_STATE`.
- *  - If `access` is supplied but no `RbacProvider` is mounted → returns
- *    `DEFAULT_ACCESS_STATE` and emits a dev-only `console.warn` so the
- *    developer notices the missing provider. Failing **open** is the
- *    safer default (RBAC silently denying everything would be a hidden
- *    regression in development).
- *  - Otherwise → evaluates the requirement against the active
- *    `rbac.engine` + `rbac.subject` via `resolveAccessState`.
- *
- * The memo dependency list is `[access, rbac]` — a stable RBAC
- * context + identical access requirement re-uses the same result
- * object so downstream `useMemo` / `React.memo` comparisons stay
- * cheap.
- *
- * @example
- * ```tsx
- * function MyComponent({ access }: { access?: AccessRequirement }) {
- *   const accessState = useAccessState(access);
- *   if (!accessState.visible) return null;
- *   return <input disabled={accessState.disabled} readOnly={accessState.readonly} />;
- * }
- * ```
- */
-export function useAccessState(
-  access: AccessRequirement | undefined
-): AccessState {
-  // Hooks are called unconditionally to comply with the rules of hooks.
-  // `useRbacOptional` returns `null` when no provider is mounted
-  // (it does NOT throw — that's intentional, see its doc).
-  const rbac = useRbacOptional();
-
-  return useMemo(() => {
-    if (!access) {
-      return DEFAULT_ACCESS_STATE;
-    }
-
-    if (!rbac) {
-      if (process.env.NODE_ENV !== 'production') {
-         
-        console.warn(
-          '[useAccessState] No RbacProvider found but access requirement was provided. ' +
-            'Defaulting to full access. Wrap your component tree with <RbacProvider> to enable RBAC. ' +
-            `Resource: ${access.resource}, Action: ${access.action}`
-        );
-      }
-      return DEFAULT_ACCESS_STATE;
-    }
-
-    return resolveAccessState(access, (request) =>
-      rbac.engine.can(rbac.subject, request)
-    );
-  }, [access, rbac]);
-}