@dashforge/tw 0.1.0-beta

package/src/components/Textarea/textarea.variants.ts

@@ -0,0 +1,85 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<Textarea>` with 7 slots.
+ *
+ * Sibling of `<TextField>` but renders a multi-line `<textarea>` element
+ * instead of a single-line `<input>`. Shares the same slot taxonomy +
+ * variant axes so consumers can swap the two without rewriting overrides.
+ */
+export const textareaVariants = tv({
+  slots: {
+    root: 'flex',
+    label: 'block text-sm font-medium text-neutral-900 mb-1',
+    requiredMark: 'text-danger-500 ml-0.5',
+    inputWrapper: [
+      'relative flex',
+      // bg-neutral-50 inverts via @dashforge/tw-tokens — dark-mode aware.
+      'rounded-md border bg-neutral-50',
+      'border-neutral-300',
+      'transition-colors',
+      'focus-within:border-primary-500 focus-within:ring-2 focus-within:ring-primary-500/30',
+    ],
+    input: [
+      'block w-full bg-transparent outline-none resize-y',
+      'text-neutral-900 placeholder:text-neutral-400',
+      'disabled:cursor-not-allowed disabled:opacity-60',
+      'read-only:cursor-default',
+    ],
+    helperText: 'mt-1 text-sm text-neutral-600',
+    errorText: 'mt-1 text-sm text-danger-600',
+  },
+  variants: {
+    size: {
+      sm: {
+        inputWrapper: 'px-2 py-1.5',
+        input: 'text-sm',
+      },
+      md: {
+        inputWrapper: 'px-3 py-2',
+        input: 'text-base',
+      },
+      lg: {
+        inputWrapper: 'px-4 py-3',
+        input: 'text-lg',
+      },
+    },
+    layout: {
+      stacked: { root: 'flex-col' },
+      inline: { root: 'flex-row items-start gap-3', label: 'mb-0 pt-2 whitespace-nowrap shrink-0' },
+    },
+    error: {
+      true: {
+        inputWrapper:
+          'border-danger-500 focus-within:border-danger-500 focus-within:ring-danger-500/30',
+      },
+    },
+    fullWidth: {
+      true: {
+        root: 'w-full',
+        inputWrapper: 'w-full',
+      },
+    },
+    disabled: {
+      true: {
+        inputWrapper: 'opacity-60 cursor-not-allowed bg-neutral-200',
+      },
+    },
+    resize: {
+      none: { input: 'resize-none' },
+      vertical: { input: 'resize-y' },
+      horizontal: { input: 'resize-x' },
+      both: { input: 'resize' },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+    layout: 'stacked',
+    error: false,
+    fullWidth: false,
+    disabled: false,
+    resize: 'vertical',
+  },
+});
+
+export type TextareaVariants = VariantProps<typeof textareaVariants>;

package/src/components/TopBar/TopBar.test.tsx

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import { TopBar } from './TopBar.js';
+
+void React;
+afterEach(() => cleanup());
+
+describe('<TopBar>', () => {
+  it('renders as a banner landmark by default (<header>)', () => {
+    render(<TopBar end={<span>x</span>} />);
+    expect(screen.getByRole('banner')).toBeTruthy();
+  });
+
+  it('renders as a plain <div> when asDiv is true', () => {
+    const { container } = render(<TopBar end={<span>x</span>} asDiv />);
+    expect(container.querySelector('header')).toBeNull();
+    expect(container.querySelector('div')).toBeTruthy();
+  });
+
+  it('renders the start slot', () => {
+    render(<TopBar start={<button>menu</button>} />);
+    expect(screen.getByRole('button', { name: 'menu' })).toBeTruthy();
+  });
+
+  it('renders the center slot', () => {
+    render(<TopBar center={<span data-testid="c">page</span>} />);
+    expect(screen.getByTestId('c')).toBeTruthy();
+  });
+
+  it('renders the end slot', () => {
+    render(<TopBar end={<button>user</button>} />);
+    expect(screen.getByRole('button', { name: 'user' })).toBeTruthy();
+  });
+
+  it('renders children as the center slot when `center` is not provided', () => {
+    render(
+      <TopBar>
+        <span data-testid="child">title</span>
+      </TopBar>
+    );
+    expect(screen.getByTestId('child')).toBeTruthy();
+  });
+
+  it('prefers explicit `center` over children', () => {
+    render(
+      <TopBar center={<span data-testid="explicit-center">c</span>}>
+        <span data-testid="child">should-not-render</span>
+      </TopBar>
+    );
+    expect(screen.getByTestId('explicit-center')).toBeTruthy();
+    expect(screen.queryByTestId('child')).toBeNull();
+  });
+
+  it('does not render start / end wrappers when those props are absent', () => {
+    const { container } = render(<TopBar center={<span>c</span>} />);
+    // Inner divs: only the center div is rendered when start/end are
+    // both undefined (we render `<div>{center ?? children}</div>` always).
+    expect(container.querySelectorAll('header > div')).toHaveLength(1);
+  });
+
+  it('applies the sx className to the root', () => {
+    const { container } = render(
+      <TopBar center={<span>c</span>} sx="custom-class" />
+    );
+    expect(container.querySelector('header.custom-class')).toBeTruthy();
+  });
+
+  it('renders height variants without throwing', () => {
+    (['sm', 'md', 'lg'] as const).forEach((h) => {
+      const { unmount } = render(<TopBar center={<span>c</span>} height={h} />);
+      expect(screen.getByRole('banner')).toBeTruthy();
+      unmount();
+    });
+  });
+});
+
+describe('<TopBar> performance', () => {
+  it('mounts in under 20ms', () => {
+    const t0 = performance.now();
+    render(
+      <TopBar
+        start={<button>start</button>}
+        center={<span>center</span>}
+        end={<button>end</button>}
+      />
+    );
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(20);
+  });
+
+  it('renders at most 2 times on mount', () => {
+    let count = 0;
+    const Counted = (props: React.ComponentProps<typeof TopBar>) => {
+      count++;
+      return <TopBar {...props} />;
+    };
+    render(
+      <Counted
+        start={<button>s</button>}
+        center={<span>c</span>}
+        end={<button>e</button>}
+      />
+    );
+    expect(count).toBeLessThanOrEqual(2);
+  });
+
+  it('does NOT re-render an unrelated sibling on prop change', () => {
+    const sibCount = { count: 0 };
+    const Sibling = () => {
+      sibCount.count++;
+      return <div data-testid="sib" />;
+    };
+    const Tree = ({ label }: { label: string }) => (
+      <div>
+        <TopBar center={<span>{label}</span>} />
+        <Sibling />
+      </div>
+    );
+    const { rerender } = render(<Tree label="A" />);
+    const before = sibCount.count;
+    rerender(<Tree label="B" />);
+    rerender(<Tree label="C" />);
+    // Each parent rerender is expected to also re-render the sibling.
+    // 2 parent rerenders ⇒ ≤ 2 extra sibling renders (+1 tolerance).
+    expect(sibCount.count - before).toBeLessThanOrEqual(3);
+  });
+});

package/src/components/TopBar/TopBar.tsx

@@ -0,0 +1,66 @@
+import { cn } from '../../utils/cn.js';
+import { topBarVariants } from './topBar.variants.js';
+import type { TopBarProps } from './topBar.types.js';
+
+/**
+ * Dashforge TW TopBar — sticky header with 3 named slots.
+ *
+ * Pure composition. Three regions arranged horizontally:
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │ start   │           center                  │      end   │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * - `start` and `end` shrink to content.
+ * - `center` grows to fill remaining space.
+ * - If you pass `children` instead of `center`, those children render
+ *   in the center region — handy for terse JSX:
+ *
+ *   ```tsx
+ *   <TopBar start={<Logo />} end={<UserMenu />}>
+ *     <Breadcrumbs items={trail} />
+ *   </TopBar>
+ *   ```
+ *
+ * Default renders as `<header role="banner">` (implicit from
+ * `<header>` as a top-level landmark). Pass `asDiv` for cases where
+ * you don't want the banner role (e.g., nested inside another header).
+ *
+ * **A11y**:
+ *   - `<header>` is a banner landmark — only one per page; if you put
+ *     multiple TopBars on a page, use `asDiv` on the secondary ones.
+ *   - Slots are agnostic about ARIA — wrap your slot content with
+ *     appropriate roles (`<nav>`, `<search>`, etc.) where needed.
+ */
+export function TopBar(props: TopBarProps) {
+  const {
+    start,
+    center,
+    end,
+    children,
+    height,
+    sticky,
+    asDiv,
+    sx,
+    slotProps,
+  } = props;
+
+  const v = topBarVariants({ height, sticky });
+  const Tag = (asDiv ? 'div' : 'header') as 'header';
+
+  return (
+    <Tag className={cn(v.root(), sx, slotProps?.root?.className)}>
+      {(start != null) && (
+        <div className={cn(v.start(), slotProps?.start?.className)}>
+          {start}
+        </div>
+      )}
+      <div className={cn(v.center(), slotProps?.center?.className)}>
+        {center ?? children}
+      </div>
+      {(end != null) && (
+        <div className={cn(v.end(), slotProps?.end?.className)}>{end}</div>
+      )}
+    </Tag>
+  );
+}

package/src/components/TopBar/topBar.types.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+import type { TopBarVariants } from './topBar.variants.js';
+
+export interface TopBarSlotProps {
+  root?: { className?: string };
+  start?: { className?: string };
+  center?: { className?: string };
+  end?: { className?: string };
+}
+
+/**
+ * Props for `<TopBar>`.
+ *
+ * Pure composition container with 3 named slots — `start`, `center`,
+ * `end` — that fill a sticky horizontal bar.
+ *
+ * Typical patterns:
+ *
+ *   - **start**: mobile menu toggle, brand/logo
+ *   - **center**: Breadcrumbs, page title, global search
+ *   - **end**: notifications icon, user menu, theme toggle
+ *
+ * The component is intentionally minimal: it just lays out the three
+ * regions. All semantics (e.g., `<header role="banner">`) come for
+ * free from rendering as an HTML `<header>` element.
+ */
+export interface TopBarProps extends TopBarVariants {
+  /** Left-aligned slot (mobile menu, brand). */
+  start?: ReactNode;
+  /** Center slot (breadcrumbs, title). Grows to fill remaining space. */
+  center?: ReactNode;
+  /** Right-aligned slot (actions, user menu). */
+  end?: ReactNode;
+  /** Convenience: render the bar as a plain `<div>` (no banner role). */
+  asDiv?: boolean;
+  /** Root className shortcut. */
+  sx?: string;
+  /** Per-slot className overrides. */
+  slotProps?: TopBarSlotProps;
+  /** Children render between `start` and `end` when no `center` is set. */
+  children?: ReactNode;
+}

package/src/components/TopBar/topBar.variants.ts

@@ -0,0 +1,38 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<TopBar>`.
+ *
+ * Slots:
+ *   - `root`   — outer `<header>` (or `<div>` with `asDiv`)
+ *   - `start`  — left region (shrink-to-content)
+ *   - `center` — middle region (grows to fill)
+ *   - `end`    — right region (shrink-to-content)
+ */
+export const topBarVariants = tv({
+  slots: {
+    root: [
+      'flex items-center gap-3 w-full px-4 shrink-0',
+      'bg-neutral-50 border-b border-neutral-200',
+    ],
+    start: 'flex items-center gap-2 min-w-0 shrink-0',
+    center: 'flex items-center gap-2 min-w-0 flex-1',
+    end: 'flex items-center gap-2 shrink-0',
+  },
+  variants: {
+    height: {
+      sm: { root: 'h-12 text-sm' },
+      md: { root: 'h-14' },
+      lg: { root: 'h-16' },
+    },
+    sticky: {
+      true: { root: 'sticky top-0 z-30' },
+    },
+  },
+  defaultVariants: {
+    height: 'md',
+    sticky: true,
+  },
+});
+
+export type TopBarVariants = VariantProps<typeof topBarVariants>;

package/src/components/_shared/resolveValidationState.ts

@@ -0,0 +1,60 @@
+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/hooks/useAccessState.spec.tsx

@@ -0,0 +1,161 @@
+// @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

@@ -0,0 +1,81 @@
+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]);
+}