@dashforge/tw 0.1.0-beta

package/src/components/Button/button.types.ts

@@ -0,0 +1,74 @@
+import type { ButtonHTMLAttributes } from 'react';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { ButtonVariants } from './button.variants.js';
+
+/**
+ * Props for the Dashforge TW `<Button>` component.
+ *
+ * Extends the native `<button>` attributes (so `onClick`, `type`,
+ * `aria-*`, `data-*` etc. all flow through), narrowed in two places:
+ *
+ *   - `disabled` is kept (combines with RBAC + loading via OR)
+ *   - `className` is omitted — use `sx` instead. This keeps the
+ *     override path **single and explicit**: `sx` is the escape hatch
+ *     for adding utility classes, and `tailwind-merge` (via `cn()`)
+ *     guarantees it wins over any conflicting variant class.
+ *
+ * Plus the variant axes from `tailwind-variants` and Dashforge-specific
+ * additions:
+ *
+ *   - `access` — RBAC requirement (hide / disable / readonly)
+ *   - `asChild` — Radix Slot polymorphism: when `true`, renders the
+ *     immediate child element with the Button's class merged in, so
+ *     `<Button asChild><a href="/x">Go</a></Button>` produces a styled
+ *     `<a>` with no extra wrapper DOM
+ */
+export interface ButtonProps
+  // `color` is omitted from the native `<button>` attributes because
+  // HTML's legacy `color` attribute (string) collides with our variant
+  // axis (`'primary' | 'secondary' | …`). The Picked variant version
+  // is the canonical one.
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className' | 'color'>,
+    Pick<ButtonVariants, 'variant' | 'color' | 'size' | 'fullWidth' | 'loading'> {
+  /**
+   * RBAC access control requirement.
+   *
+   * Controls button visibility and interaction based on user
+   * permissions:
+   *   - `onUnauthorized: 'hide'`     → button does not render
+   *   - `onUnauthorized: 'disable'`  → button renders disabled
+   *   - `onUnauthorized: 'readonly'` → button renders disabled
+   *     (buttons do not support true readonly semantics; disabled is
+   *     used as fallback)
+   *
+   * Combines with `disabled` and `loading` props via OR logic.
+   */
+  access?: AccessRequirement;
+
+  /**
+   * When `true`, the immediate child element is rendered with the
+   * Button's classes merged in (via `@radix-ui/react-slot`). The
+   * Button DOM element is not emitted.
+   *
+   * Common pattern: render a router `Link` with Button styling.
+   *
+   * @example
+   * ```tsx
+   * <Button asChild variant="solid">
+   *   <Link to="/dashboard">Dashboard</Link>
+   * </Button>
+   * ```
+   */
+  asChild?: boolean;
+
+  /**
+   * Tailwind utility classes appended **after** the variant classes,
+   * so they win on any conflict via `tailwind-merge`.
+   *
+   * @example
+   * ```tsx
+   * <Button sx="md:w-1/2 shadow-xl">Save</Button>
+   * ```
+   */
+  sx?: string;
+}

package/src/components/Button/button.variants.ts

@@ -0,0 +1,159 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<Button>`.
+ *
+ * Three independent axes plus two booleans:
+ *   - `variant`: visual treatment (solid / outline / ghost / link)
+ *   - `color`:   semantic intent role (primary / secondary / success /
+ *                warning / danger)
+ *   - `size`:    sm / md / lg
+ *   - `fullWidth`: stretches to container width
+ *   - `loading`:   visually + functionally disabled, used together with
+ *                  an inline spinner rendered by the component
+ *
+ * Color × variant combinations are expressed via `compoundVariants` so
+ * each pair owns its bg / text / border / hover / focus quartet without
+ * a `dark:` variant explosion. Dark mode swap is delegated entirely to
+ * the runtime CSS-vars from `@dashforge/tw-theme` — the same class
+ * resolves to a different value when `data-dash-tw-theme="dark"` flips.
+ *
+ * Token references:
+ *   - Surface bg / border / text   →  `*-primary-*`, `*-danger-*`, etc.
+ *                                     (resolved via `dashforgePreset()`)
+ *   - Hover / focus / active states→  one tone deeper on the same scale
+ *                                     (`primary-600` from `primary-500`)
+ *   - Disabled                     →  opacity drop + no pointer-events
+ */
+export const buttonVariants = tv({
+  base: [
+    'inline-flex items-center justify-center gap-2',
+    'font-medium',
+    'rounded-md',
+    'select-none whitespace-nowrap',
+    'transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
+    'disabled:opacity-50 disabled:pointer-events-none',
+  ],
+  variants: {
+    variant: {
+      solid: 'border border-transparent text-white',
+      outline: 'bg-transparent border',
+      ghost: 'bg-transparent border border-transparent',
+      link: 'bg-transparent border-0 underline-offset-4 hover:underline px-0',
+    },
+    color: {
+      primary: '',
+      secondary: '',
+      success: '',
+      warning: '',
+      danger: '',
+    },
+    size: {
+      sm: 'h-8 px-3 text-sm',
+      md: 'h-10 px-4 text-base',
+      lg: 'h-12 px-6 text-lg',
+    },
+    fullWidth: {
+      true: 'w-full',
+    },
+    loading: {
+      true: 'cursor-wait',
+    },
+  },
+  compoundVariants: [
+    // ───── solid × color ─────
+    {
+      variant: 'solid',
+      color: 'primary',
+      class: 'bg-primary-500 hover:bg-primary-600 active:bg-primary-700 focus-visible:ring-primary-500',
+    },
+    {
+      variant: 'solid',
+      color: 'secondary',
+      class: 'bg-secondary-500 hover:bg-secondary-600 active:bg-secondary-700 focus-visible:ring-secondary-500',
+    },
+    {
+      variant: 'solid',
+      color: 'success',
+      class: 'bg-success-500 hover:bg-success-600 active:bg-success-700 focus-visible:ring-success-500',
+    },
+    {
+      variant: 'solid',
+      color: 'warning',
+      class: 'bg-warning-500 hover:bg-warning-600 active:bg-warning-700 focus-visible:ring-warning-500',
+    },
+    {
+      variant: 'solid',
+      color: 'danger',
+      class: 'bg-danger-500 hover:bg-danger-600 active:bg-danger-700 focus-visible:ring-danger-500',
+    },
+    // ───── outline × color ─────
+    {
+      variant: 'outline',
+      color: 'primary',
+      class: 'border-primary-500 text-primary-700 hover:bg-primary-50 focus-visible:ring-primary-500',
+    },
+    {
+      variant: 'outline',
+      color: 'secondary',
+      class: 'border-secondary-500 text-secondary-700 hover:bg-secondary-50 focus-visible:ring-secondary-500',
+    },
+    {
+      variant: 'outline',
+      color: 'success',
+      class: 'border-success-500 text-success-700 hover:bg-success-50 focus-visible:ring-success-500',
+    },
+    {
+      variant: 'outline',
+      color: 'warning',
+      class: 'border-warning-500 text-warning-700 hover:bg-warning-50 focus-visible:ring-warning-500',
+    },
+    {
+      variant: 'outline',
+      color: 'danger',
+      class: 'border-danger-500 text-danger-700 hover:bg-danger-50 focus-visible:ring-danger-500',
+    },
+    // ───── ghost × color ─────
+    {
+      variant: 'ghost',
+      color: 'primary',
+      class: 'text-primary-700 hover:bg-primary-50 focus-visible:ring-primary-500',
+    },
+    {
+      variant: 'ghost',
+      color: 'secondary',
+      class: 'text-secondary-700 hover:bg-secondary-50 focus-visible:ring-secondary-500',
+    },
+    {
+      variant: 'ghost',
+      color: 'success',
+      class: 'text-success-700 hover:bg-success-50 focus-visible:ring-success-500',
+    },
+    {
+      variant: 'ghost',
+      color: 'warning',
+      class: 'text-warning-700 hover:bg-warning-50 focus-visible:ring-warning-500',
+    },
+    {
+      variant: 'ghost',
+      color: 'danger',
+      class: 'text-danger-700 hover:bg-danger-50 focus-visible:ring-danger-500',
+    },
+    // ───── link × color ─────
+    { variant: 'link', color: 'primary', class: 'text-primary-700 hover:text-primary-800' },
+    { variant: 'link', color: 'secondary', class: 'text-secondary-700 hover:text-secondary-800' },
+    { variant: 'link', color: 'success', class: 'text-success-700 hover:text-success-800' },
+    { variant: 'link', color: 'warning', class: 'text-warning-700 hover:text-warning-800' },
+    { variant: 'link', color: 'danger', class: 'text-danger-700 hover:text-danger-800' },
+  ],
+  defaultVariants: {
+    variant: 'solid',
+    color: 'primary',
+    size: 'md',
+    fullWidth: false,
+    loading: false,
+  },
+});
+
+export type ButtonVariants = VariantProps<typeof buttonVariants>;

package/src/components/Checkbox/Checkbox.test.tsx

@@ -0,0 +1,146 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/react';
+import { RbacProvider } from '@dashforge/rbac';
+import type { RbacPolicy, Subject } from '@dashforge/rbac';
+import { DashFormProvider } from '@dashforge/forms';
+import { Checkbox } from './Checkbox.js';
+
+const READ_ONLY: RbacPolicy = {
+  roles: [
+    {
+      name: 'viewer',
+      permissions: [{ resource: 'doc', action: 'update', effect: 'deny' }],
+    },
+  ],
+};
+const viewer: Subject = { id: 'v', roles: ['viewer'] };
+
+function withForm(children: React.ReactNode, defaultValues: Record<string, unknown> = {}) {
+  return <DashFormProvider defaultValues={defaultValues}>{children}</DashFormProvider>;
+}
+
+describe('Checkbox — standalone (no DashFormProvider)', () => {
+  it('renders the Radix root button + label association', () => {
+    const { getByText, getByRole } = render(<Checkbox name="terms" label="Accept" />);
+    expect(getByText('Accept')).toBeTruthy();
+    expect(getByRole('checkbox')).toBeTruthy();
+  });
+
+  it('fires onCheckedChange callback when toggled', () => {
+    const onCheckedChange = vi.fn();
+    const { getByRole } = render(
+      <Checkbox name="terms" label="Accept" onCheckedChange={onCheckedChange} />
+    );
+    fireEvent.click(getByRole('checkbox'));
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+
+  it('respects defaultChecked', () => {
+    const { getByRole } = render(<Checkbox name="x" defaultChecked label="X" />);
+    expect(getByRole('checkbox').getAttribute('data-state')).toBe('checked');
+  });
+
+  it('applies size variants', () => {
+    const { container, rerender } = render(<Checkbox name="x" size="sm" label="X" />);
+    expect(container.querySelector('button[role="checkbox"]')?.className).toContain('h-4');
+    rerender(<Checkbox name="x" size="lg" label="X" />);
+    expect(container.querySelector('button[role="checkbox"]')?.className).toContain('h-6');
+  });
+
+  it('shows helperText when explicitly supplied', () => {
+    const { getByText } = render(
+      <Checkbox name="x" label="X" helperText="Hint" />
+    );
+    expect(getByText('Hint')).toBeTruthy();
+  });
+
+  it('shows danger styling on error=true', () => {
+    const { container } = render(<Checkbox name="x" label="X" error helperText="bad" />);
+    const control = container.querySelector('button[role="checkbox"]');
+    expect(control?.className).toContain('border-danger-500');
+  });
+});
+
+describe('Checkbox — override (sx + slotProps)', () => {
+  it('sx is applied to the root wrapper', () => {
+    const { container } = render(<Checkbox name="x" label="X" sx="ml-8" />);
+    expect((container.firstChild as HTMLElement).className).toContain('ml-8');
+  });
+
+  it('slotProps.control adds classes to the Radix root', () => {
+    const { container } = render(
+      <Checkbox
+        name="x"
+        label="X"
+        slotProps={{ control: { className: 'ring-4 ring-purple-500' } }}
+      />
+    );
+    expect(container.querySelector('button[role="checkbox"]')?.className).toContain(
+      'ring-purple-500'
+    );
+  });
+
+  it('slotProps.label adds classes to the label element', () => {
+    const { getByText } = render(
+      <Checkbox name="x" label="Hi" slotProps={{ label: { className: 'uppercase' } }} />
+    );
+    expect((getByText('Hi') as HTMLLabelElement).className).toContain('uppercase');
+  });
+});
+
+describe('Checkbox — RBAC', () => {
+  it('hides when access denies with onUnauthorized=hide', () => {
+    const { queryByRole } = render(
+      <RbacProvider policy={READ_ONLY} subject={viewer}>
+        <Checkbox
+          name="x"
+          label="X"
+          access={{ resource: 'doc', action: 'update', onUnauthorized: 'hide' }}
+        />
+      </RbacProvider>
+    );
+    expect(queryByRole('checkbox')).toBeNull();
+  });
+
+  it('disables when access denies with onUnauthorized=disable', () => {
+    const { getByRole } = render(
+      <RbacProvider policy={READ_ONLY} subject={viewer}>
+        <Checkbox
+          name="x"
+          label="X"
+          access={{ resource: 'doc', action: 'update', onUnauthorized: 'disable' }}
+        />
+      </RbacProvider>
+    );
+    expect((getByRole('checkbox') as HTMLButtonElement).disabled).toBe(true);
+  });
+});
+
+describe('Checkbox — DashFormProvider integration', () => {
+  it('renders without crashing inside DashFormProvider', () => {
+    const { getByRole } = render(withForm(<Checkbox name="terms" label="Accept" />));
+    expect(getByRole('checkbox')).toBeTruthy();
+  });
+
+  it('respects explicit `checked` prop (controlled mode wins over bridge)', () => {
+    // The explicit `checked` prop takes precedence over `bridge.getValue`.
+    // Defaults propagation through RHF/Engine is covered by the
+    // @dashforge/forms own test suite (DashFormProvider.* tests); here we
+    // only verify the Checkbox honours the override path correctly.
+    const { getByRole } = render(
+      withForm(<Checkbox name="terms" label="Accept" checked />, { terms: false })
+    );
+    expect(getByRole('checkbox').getAttribute('data-state')).toBe('checked');
+  });
+
+  it('flips checked state on click (bridge.setValue + onChange)', () => {
+    const { getByRole } = render(
+      withForm(<Checkbox name="terms" label="Accept" />, { terms: false })
+    );
+    const cb = getByRole('checkbox');
+    expect(cb.getAttribute('data-state')).toBe('unchecked');
+    fireEvent.click(cb);
+    expect(cb.getAttribute('data-state')).toBe('checked');
+  });
+});

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,228 @@
+import { useContext, useEffect, useId, useRef } from 'react';
+import * as RadixCheckbox from '@radix-ui/react-checkbox';
+import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
+import type { DashFormBridge, FieldRegistration } from '@dashforge/ui-core';
+import { useDashFieldMeta } from '@dashforge/forms';
+import { cn } from '../../utils/cn.js';
+import { useAccessState } from '../../hooks/useAccessState.js';
+import { resolveValidationState } from '../_shared/resolveValidationState.js';
+import { checkboxVariants } from './checkbox.variants.js';
+import type { CheckboxProps } from './checkbox.types.js';
+
+/**
+ * Inline checkmark SVG used by `Radix.Indicator`. Stroke uses
+ * `currentColor` so the parent's `text-white` propagates correctly.
+ *
+ * @internal
+ */
+function CheckIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 16 16"
+      fill="none"
+      className={className}
+    >
+      <path
+        d="M3 8.5l3 3 7-7"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Dashforge TW Checkbox — bridge-integrated form control.
+ *
+ * Renders through Radix `Checkbox.Root` + `Checkbox.Indicator`, styled
+ * with the `checkboxVariants` TV recipe. Behaviour at the bridge level
+ * is a direct port of `@dashforge/ui/Checkbox` (MUI):
+ *
+ *  - When mounted inside `DashFormProvider`, registers with the bridge
+ *    (`bridge.register`), reads `bridge.getValue` for the checked
+ *    state, writes `bridge.setValue` on change, fires
+ *    `registration.onChange` / `onBlur` for RHF.
+ *  - When mounted outside, behaves as a plain uncontrolled checkbox.
+ *  - `visibleWhen` predicates the engine state; `false` → returns null.
+ *  - `useAccessState(access)` resolves RBAC; `visible: false` → null.
+ *  - `unregister`-on-unmount is StrictMode-safe (queueMicrotask +
+ *    `isMountedRef`, mirrors the MUI-side pattern).
+ *  - Error gating: bridge error shows only after `touched` or after
+ *    the form has been submitted (`submitCount > 0`).
+ *
+ * Renderer differences vs MUI:
+ *
+ *  - No `FormControlLabel` wrapper — uses a native `<label htmlFor>`
+ *    bound via `useId()`. The label click toggles via HTML semantics.
+ *  - The Radix root is a `<button>`, so it's keyboard-accessible by
+ *    default (Space toggles).
+ *  - Slot overrides are class-based (`slotProps={{ control: { className } }}`)
+ *    rather than MUI slot components.
+ */
+export function Checkbox(props: CheckboxProps) {
+  const {
+    name,
+    rules,
+    visibleWhen,
+    label,
+    helperText,
+    error,
+    access,
+    size,
+    disabled,
+    checked,
+    defaultChecked,
+    onCheckedChange,
+    sx,
+    slotProps,
+  } = props;
+
+  // ───── Hooks (always called, unconditional) ─────
+  const bridge = useContext(DashFormContext) as DashFormBridge | null;
+  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
+  // Per-field granular subscription. We READ from `fieldMeta.value`
+  // (reactive snapshot) rather than `bridge.getValue(name)` (eager
+  // read with no subscription).
+  const fieldMeta = useDashFieldMeta(name);
+  const accessState = useAccessState(access);
+
+  const controlId = useId();
+
+  // StrictMode-safe unregister-on-unmount — mirrors MUI Checkbox.tsx
+  // (the bridge identity changes on every keystroke, so we MUST NOT
+  // re-run cleanup on deps changes — empty deps + ref pattern).
+  const unregisterRef = useRef({ bridge, name });
+  unregisterRef.current = { bridge, name };
+  const isMountedRef = useRef(false);
+   
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      const { bridge: cap, name: capName } = unregisterRef.current;
+      queueMicrotask(() => {
+        if (!isMountedRef.current) cap?.unregister?.(capName);
+      });
+    };
+  }, []);
+
+  // ───── Early returns ─────
+  if (!isVisible) return null;
+  if (!accessState.visible) return null;
+
+  // ───── Effective disabled (OR logic: explicit OR RBAC) ─────
+  const effectiveDisabled =
+    Boolean(disabled) || accessState.disabled || accessState.readonly;
+
+  // ───── Form mode vs Standalone ─────
+  const isFormMode = Boolean(bridge?.register);
+
+  let resolvedChecked: boolean | 'indeterminate' = checked ?? defaultChecked ?? false;
+  let resolvedError = error;
+  let resolvedHelperText: typeof helperText = helperText;
+  let registration: FieldRegistration | null = null;
+
+  if (isFormMode && bridge) {
+    registration = bridge.register(name, rules);
+    const validation = resolveValidationState(name, bridge, error, helperText);
+    resolvedError = validation.error;
+    resolvedHelperText = validation.helperText;
+    // Reactive snapshot from useDashFieldMeta — re-renders on per-field
+    // state change, unlike bridge.getValue (eager read, no subscription).
+    resolvedChecked =
+      checked !== undefined ? checked : Boolean(fieldMeta.value);
+  }
+
+  // ───── Handlers ─────
+  const handleCheckedChange = (next: boolean | 'indeterminate') => {
+    const nextBool = next === true; // indeterminate treated as unchecked at the bridge level
+
+    if (isFormMode && bridge) {
+      // Update bridge value FIRST so subsequent reads see the new state.
+      bridge.setValue?.(name, nextBool);
+
+      // Synthesise a minimal RHF-compatible event for registration.onChange.
+      const syntheticEvent = {
+        target: { name, checked: nextBool, value: nextBool },
+        type: 'change',
+      };
+      void registration?.onChange?.(syntheticEvent);
+    }
+
+    onCheckedChange?.(nextBool);
+  };
+
+  const handleBlur = () => {
+    if (!isFormMode || !bridge) return;
+    const currentChecked = bridge.getValue(name) === true;
+    const syntheticEvent = {
+      target: { name, checked: currentChecked, value: currentChecked },
+      type: 'blur',
+    };
+    registration?.onBlur?.(syntheticEvent);
+  };
+
+  // ───── Render ─────
+  const v = checkboxVariants({ size, error: resolvedError });
+
+  // Radix Checkbox: pass `checked` (controlled) OR `defaultChecked`
+  // (uncontrolled), never both. In bridge mode the truth lives in the
+  // bridge — always controlled. Standalone: respect whichever prop the
+  // consumer supplied.
+  const radixStateProps: {
+    checked?: boolean | 'indeterminate';
+    defaultChecked?: boolean;
+  } = isFormMode
+    ? { checked: resolvedChecked }
+    : checked !== undefined
+      ? { checked }
+      : { defaultChecked: defaultChecked ?? false };
+
+  return (
+    <div className={cn(v.root(), sx, slotProps?.root?.className)}>
+      <RadixCheckbox.Root
+        id={controlId}
+        name={name}
+        {...radixStateProps}
+        disabled={effectiveDisabled}
+        onCheckedChange={handleCheckedChange}
+        onBlur={handleBlur}
+        ref={registration?.ref as React.Ref<HTMLButtonElement> | undefined}
+        className={cn(v.control(), slotProps?.control?.className)}
+      >
+        <RadixCheckbox.Indicator
+          className={cn(v.indicator(), slotProps?.indicator?.className)}
+          forceMount
+        >
+          {resolvedChecked === true ? <CheckIcon className="h-full w-full" /> : null}
+        </RadixCheckbox.Indicator>
+      </RadixCheckbox.Root>
+
+      <div className="flex flex-col">
+        {label && (
+          <label
+            htmlFor={controlId}
+            className={cn(v.label(), slotProps?.label?.className)}
+          >
+            {label}
+          </label>
+        )}
+        {resolvedHelperText && (
+          <p
+            className={cn(
+              resolvedError ? v.errorText() : v.helperText(),
+              resolvedError
+                ? slotProps?.errorText?.className
+                : slotProps?.helperText?.className
+            )}
+          >
+            {resolvedHelperText}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/Checkbox/checkbox.types.ts

@@ -0,0 +1,88 @@
+import type { ReactNode } from 'react';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { Engine } from '@dashforge/ui-core';
+import type { CheckboxVariants } from './checkbox.variants.js';
+
+/**
+ * Per-slot className overrides for `<Checkbox>`. Shape mirrors the
+ * MUI-side `slotProps` convention: object-per-slot with a `className`
+ * key, so future extensions (style, aria-*, data-*) are additive.
+ */
+export interface CheckboxSlotProps {
+  root?: { className?: string };
+  control?: { className?: string };
+  indicator?: { className?: string };
+  label?: { className?: string };
+  helperText?: { className?: string };
+  errorText?: { className?: string };
+}
+
+/**
+ * Props for the Dashforge TW `<Checkbox>` component.
+ *
+ * Behaves identically to `@dashforge/ui/Checkbox` (MUI) at the bridge
+ * level — same `name` / `rules` / `visibleWhen` / `access` semantics,
+ * same validation gating (touched OR submitCount > 0). The visual
+ * surface is rendered via Radix Checkbox + Tailwind classes.
+ *
+ * Note: the `error` prop here is the **public** form-validation
+ * semaphore (boolean override); it threads into the variant via
+ * `checkboxVariants({ error })` internally. The variant axis name and
+ * the prop name happen to coincide — same meaning.
+ */
+export interface CheckboxProps
+  extends Pick<CheckboxVariants, 'size'> {
+  /** Bridge field name (required when used inside `DashFormProvider`). */
+  name: string;
+
+  /** Visible label rendered next to the control. Click also toggles the box. */
+  label?: ReactNode;
+
+  /** Forwarded to the bridge as RHF rules — opaque to this component. */
+  rules?: unknown;
+
+  /**
+   * Engine predicate. When provided, the component renders only when
+   * the predicate returns truthy against the current engine state.
+   */
+  visibleWhen?: (engine: Engine) => boolean;
+
+  /** Initial / controlled checked state. */
+  checked?: boolean;
+
+  /** Default checked when used uncontrolled. */
+  defaultChecked?: boolean;
+
+  /** Disabled — combined with RBAC disabled via OR. */
+  disabled?: boolean;
+
+  /**
+   * Forces helper text below the control. When the bridge surfaces an
+   * error and `helperText` is undefined, the bridge's error message
+   * shows up here (gated by `touched || submitCount > 0`).
+   */
+  helperText?: ReactNode;
+
+  /**
+   * Explicit error flag. When `true`, the control renders with the
+   * danger ring + the error-text slot is used for `helperText`.
+   * Overrides the bridge's auto-detected error.
+   */
+  error?: boolean;
+
+  /** RBAC requirement. */
+  access?: AccessRequirement;
+
+  /** Root-level Tailwind override. Wins over variant classes via `cn()`. */
+  sx?: string;
+
+  /** Per-slot overrides — see `CheckboxSlotProps`. */
+  slotProps?: CheckboxSlotProps;
+
+  /**
+   * Called when the user toggles the control. When inside a
+   * `DashFormProvider`, the bridge update happens first, then this
+   * callback fires with the new checked state.
+   */
+  onCheckedChange?: (checked: boolean) => void;
+}