@dashforge/tw 1.1.0 → 1.2.0

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

@@ -1,115 +0,0 @@
-import type { Severity, SeverityClasses, SeverityVariant } from './severity.types.js';
-
-/**
- * The 3×4 severity color matrix.
- *
- * Every class is a Tailwind utility that resolves through
- * `dashforgePreset()` to a CSS variable on the host — patchable at
- * runtime via `patchTheme({ <severity>: { …scale } })` without
- * recompiling. **Zero hardcoded hex values, zero `dark:` variants**:
- * the dashforge preset auto-inverts the neutral surface ladder via CSS
- * variable swap; the severity scales themselves do NOT auto-invert
- * (they read the same scale in light + dark, which is the desired
- * behaviour for semantic colors).
- *
- * The matrix is indexed `[variant][severity]` so a consumer-facing
- * `<Alert variant="filled" severity="warning">` resolves with a single
- * lookup.
- */
-const SEVERITY_MATRIX: Record<SeverityVariant, Record<Severity, SeverityClasses>> = {
-  standard: {
-    info: {
-      surface: 'bg-info-50 text-info-900',
-      border: 'border-info-100',
-      icon: 'text-info-600',
-    },
-    success: {
-      surface: 'bg-success-50 text-success-900',
-      border: 'border-success-100',
-      icon: 'text-success-600',
-    },
-    warning: {
-      surface: 'bg-warning-50 text-warning-900',
-      border: 'border-warning-100',
-      icon: 'text-warning-600',
-    },
-    danger: {
-      surface: 'bg-danger-50 text-danger-900',
-      border: 'border-danger-100',
-      icon: 'text-danger-600',
-    },
-  },
-  filled: {
-    info: {
-      surface: 'bg-info-600 text-info-50',
-      border: 'border-info-700',
-      icon: 'text-info-50',
-    },
-    success: {
-      surface: 'bg-success-600 text-success-50',
-      border: 'border-success-700',
-      icon: 'text-success-50',
-    },
-    warning: {
-      surface: 'bg-warning-600 text-warning-50',
-      border: 'border-warning-700',
-      icon: 'text-warning-50',
-    },
-    danger: {
-      surface: 'bg-danger-600 text-danger-50',
-      border: 'border-danger-700',
-      icon: 'text-danger-50',
-    },
-  },
-  outlined: {
-    info: {
-      surface: 'bg-transparent text-info-700',
-      border: 'border-info-300',
-      icon: 'text-info-600',
-    },
-    success: {
-      surface: 'bg-transparent text-success-700',
-      border: 'border-success-300',
-      icon: 'text-success-600',
-    },
-    warning: {
-      surface: 'bg-transparent text-warning-700',
-      border: 'border-warning-300',
-      icon: 'text-warning-600',
-    },
-    danger: {
-      surface: 'bg-transparent text-danger-700',
-      border: 'border-danger-300',
-      icon: 'text-danger-600',
-    },
-  },
-};
-
-/**
- * Resolve the Tailwind classes for one (variant, severity) pair.
- *
- * @example
- * const { surface, border, icon } = getSeverityClasses('standard', 'warning');
- * // surface: 'bg-warning-50 text-warning-900'
- * // border:  'border-warning-100'
- * // icon:    'text-warning-600'
- */
-export function getSeverityClasses(
-  variant: SeverityVariant,
-  severity: Severity
-): SeverityClasses {
-  return SEVERITY_MATRIX[variant][severity];
-}
-
-/**
- * ARIA role for a severity. Follows the W3C WAI-ARIA spec:
- * - `alert` for assertive states (warning / danger) — interrupts the
- *   screen-reader announcement queue.
- * - `status` for polite states (info / success) — queued behind other
- *   announcements.
- *
- * Consumers can override via an explicit `role` prop.
- */
-export function getSeverityRole(severity: Severity): 'alert' | 'status' {
-  return severity === 'warning' || severity === 'danger' ? 'alert' : 'status';
-}

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]);
-}