@dashforge/tw 0.1.0-beta

package/src/components/RadioGroup/RadioGroup.tsx

@@ -0,0 +1,261 @@
+import { useContext, useEffect, useId, useRef } from 'react';
+import * as RadixRadioGroup from '@radix-ui/react-radio-group';
+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 { radioGroupVariants } from './radioGroup.variants.js';
+import type { RadioGroupProps } from './radioGroup.types.js';
+
+/**
+ * Dashforge TW RadioGroup — bridge-integrated single-choice group.
+ *
+ * Renders through Radix `RadioGroup.Root` + `Item` + `Indicator`, styled
+ * with the `radioGroupVariants` TV recipe. Behaviour at the bridge level
+ * is a 1:1 port of `@dashforge/ui/RadioGroup` (MUI):
+ *
+ *  - Inside `DashFormProvider`: registers with the bridge, reads
+ *    `useDashFieldMeta` for the selected value (reactive snapshot),
+ *    writes through `bridge.setValue` on change, fires
+ *    `registration.onChange` / `onBlur` for RHF.
+ *  - Outside: behaves as a plain Radix RadioGroup (controlled by `value`
+ *    + `onValueChange`, or uncontrolled via `defaultValue`).
+ *  - `visibleWhen` predicates the engine state.
+ *  - `useAccessState(access)` resolves group-level RBAC; per-option RBAC
+ *    is resolved by calling `useAccessState` for every entry of the
+ *    `options` array (Rules of Hooks: stable as long as `options.length`
+ *    is stable, which is the documented contract — mutating the array
+ *    between renders breaks).
+ *  - Group-level RBAC has precedence over option-level (hide-the-group
+ *    wins even if some options would be visible).
+ *  - Error gating: bridge error shows only after `touched` or after the
+ *    form has been submitted at least once (Form Closure v1).
+ *  - StrictMode-safe unregister-on-unmount, mirrors Checkbox/Switch.
+ *
+ * **A11y**:
+ *   - The group root is a `<div role="radiogroup">` (Radix default).
+ *   - A `<label id="...">` is associated with the group via `aria-labelledby`.
+ *   - The helper/error text is linked via `aria-describedby`.
+ *   - Each option is a Radix `<RadioGroup.Item>` (`<button role="radio">`)
+ *     keyboard-accessible by default (arrow keys move selection).
+ */
+export function RadioGroup(props: RadioGroupProps) {
+  const {
+    name,
+    options,
+    label,
+    rules,
+    helperText,
+    required,
+    error,
+    disabled,
+    size,
+    layout,
+    access,
+    visibleWhen,
+    sx,
+    slotProps,
+    value: explicitValue,
+    defaultValue,
+    onValueChange,
+  } = props;
+
+  // ───── Hooks (unconditional) ─────
+  const bridge = useContext(DashFormContext) as DashFormBridge | null;
+  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
+  // Granular per-field subscription (side-effect: re-render this
+  // component when ITS own bridge state mutates). We DON'T read the
+  // value from this hook because it can return `undefined` on the
+  // first render before the subscription has primed — use
+  // `bridge.getValue(name)` for the actual value (mirrors MUI side).
+  useDashFieldMeta(name);
+  const groupAccessState = useAccessState(access);
+
+  // Per-option RBAC. Hooks-in-loop is safe as long as `options.length` is
+  // stable across renders — documented as the contract for this component.
+  const optionAccessStates = options.map((option) =>
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useAccessState(option.access)
+  );
+
+  const labelId = useId();
+  const helperId = `${labelId}-help`;
+
+  // StrictMode-safe unregister-on-unmount
+  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 (!groupAccessState.visible) return null;
+
+  // ───── Effective group disabled (group-level OR explicit) ─────
+  const groupEffectiveDisabled =
+    Boolean(disabled) || groupAccessState.disabled || groupAccessState.readonly;
+
+  // ───── Form mode vs standalone ─────
+  const isFormMode = Boolean(bridge?.register);
+
+  let resolvedValue: string =
+    explicitValue ?? defaultValue ?? '';
+  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;
+    if (explicitValue === undefined) {
+      const bv = bridge.getValue(name);
+      resolvedValue = bv == null ? '' : String(bv);
+    }
+  }
+
+  // ───── Process per-option visibility / disabled ─────
+  const processedOptions = options
+    .map((option, index) => {
+      const optAccess = optionAccessStates[index];
+      const isSelected = option.value === resolvedValue;
+      // Option is hidden ONLY if access says hide AND it's not the
+      // currently selected value (keep the selected option visible-but-
+      // disabled so the user can see what they picked even if perms changed).
+      const shouldHide = !optAccess.visible && !isSelected;
+      if (shouldHide) return null;
+
+      const optionEffectiveDisabled =
+        groupEffectiveDisabled ||
+        Boolean(option.disabled) ||
+        optAccess.disabled ||
+        optAccess.readonly ||
+        (!optAccess.visible && isSelected);
+
+      return { ...option, effectiveDisabled: optionEffectiveDisabled };
+    })
+    .filter((opt): opt is NonNullable<typeof opt> => opt !== null);
+
+  // ───── Handlers ─────
+  const handleValueChange = (next: string) => {
+    if (isFormMode && bridge) {
+      bridge.setValue?.(name, next);
+      void registration?.onChange?.({
+        target: { name, value: next },
+        type: 'change',
+      });
+    }
+    onValueChange?.(next);
+  };
+
+  const handleBlur = () => {
+    if (!isFormMode || !bridge) return;
+    const current = bridge.getValue(name) as string | undefined;
+    registration?.onBlur?.({
+      target: { name, value: current ?? '' },
+      type: 'blur',
+    });
+  };
+
+  // ───── Render ─────
+  const v = radioGroupVariants({
+    size,
+    layout,
+    error: resolvedError,
+    disabled: groupEffectiveDisabled,
+  });
+
+  return (
+    <div
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+      aria-describedby={resolvedHelperText ? helperId : undefined}
+    >
+      {label && (
+        <div
+          id={labelId}
+          className={cn(v.label(), slotProps?.label?.className)}
+        >
+          {label}
+          {required && (
+            <span
+              aria-hidden="true"
+              className={cn(v.requiredMark(), slotProps?.requiredMark?.className)}
+            >
+              *
+            </span>
+          )}
+        </div>
+      )}
+
+      <RadixRadioGroup.Root
+        name={name}
+        value={resolvedValue}
+        onValueChange={handleValueChange}
+        onBlur={handleBlur}
+        disabled={groupEffectiveDisabled}
+        required={required}
+        aria-labelledby={label ? labelId : undefined}
+        aria-invalid={resolvedError || undefined}
+        className={cn(v.optionList(), slotProps?.optionList?.className)}
+      >
+        {processedOptions.map((option) => {
+          const optionLabelId = `${labelId}-opt-${option.value}`;
+          return (
+            <div
+              key={option.value}
+              className={cn(v.option(), slotProps?.option?.className)}
+            >
+              <RadixRadioGroup.Item
+                value={option.value}
+                id={optionLabelId}
+                disabled={option.effectiveDisabled}
+                className={cn(v.control(), slotProps?.control?.className)}
+              >
+                <RadixRadioGroup.Indicator
+                  className={cn(v.indicator(), slotProps?.indicator?.className)}
+                />
+              </RadixRadioGroup.Item>
+              <label
+                htmlFor={optionLabelId}
+                className={cn(
+                  v.optionLabel(),
+                  option.effectiveDisabled && 'cursor-not-allowed opacity-60',
+                  slotProps?.optionLabel?.className
+                )}
+              >
+                {option.label}
+              </label>
+            </div>
+          );
+        })}
+      </RadixRadioGroup.Root>
+
+      {resolvedHelperText && (
+        <p
+          id={helperId}
+          className={cn(
+            resolvedError ? v.errorText() : v.helperText(),
+            resolvedError
+              ? slotProps?.errorText?.className
+              : slotProps?.helperText?.className
+          )}
+        >
+          {resolvedHelperText}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/RadioGroup/radioGroup.types.ts

@@ -0,0 +1,85 @@
+import type { ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { RadioGroupVariants } from './radioGroup.variants.js';
+
+/**
+ * A single selectable option in a `<RadioGroup>`.
+ */
+export interface RadioGroupOption {
+  /** The string value persisted on the form for this option. */
+  value: string;
+  /** Display label (string or any React node — e.g. with an icon). */
+  label: ReactNode;
+  /** Per-option explicit disable. ORed with group-level disable + RBAC. */
+  disabled?: boolean;
+  /**
+   * RBAC access requirement for this specific option:
+   *  - `onUnauthorized: 'hide'`     → option not rendered (unless it's the currently selected value, kept disabled to expose the choice)
+   *  - `onUnauthorized: 'disable'`  → option visible but not selectable
+   *  - `onUnauthorized: 'readonly'` → falls back to disabled (radios have no true readonly semantics)
+   *
+   * Group-level access has **precedence** over option-level access — if the
+   * whole group is hidden/disabled, that wins for all options regardless of
+   * their own access.
+   */
+  access?: AccessRequirement;
+}
+
+/**
+ * Optional className override for each slot. Use to extend specific parts
+ * of the recipe without losing the default classes. Override semantics
+ * follow the `tailwind-merge` last-wins rule.
+ */
+export interface RadioGroupSlotProps {
+  root?: { className?: string };
+  label?: { className?: string };
+  requiredMark?: { className?: string };
+  optionList?: { className?: string };
+  option?: { className?: string };
+  control?: { className?: string };
+  indicator?: { className?: string };
+  optionLabel?: { className?: string };
+  helperText?: { className?: string };
+  errorText?: { className?: string };
+}
+
+/**
+ * Props for `<RadioGroup>`.
+ *
+ * Mirrors the MUI-side `@dashforge/ui/RadioGroup` at the bridge level —
+ * same `name` / `rules` / `visibleWhen` / `access` semantics, same
+ * Form Closure v1 error gating, same option-level RBAC.
+ */
+export interface RadioGroupProps extends RadioGroupVariants {
+  /** Field name registered with the bridge. */
+  name: string;
+  /** Array of selectable options. Order is render order. */
+  options: RadioGroupOption[];
+  /** Group-level label (rendered above the option list). */
+  label?: ReactNode;
+  /** React Hook Form validation rules — forwarded to `bridge.register`. */
+  rules?: unknown;
+  /** Helper text shown below the option list when not in error state. */
+  helperText?: ReactNode;
+  /** Marks the group as required (renders red `*` after the label). */
+  required?: boolean;
+  /** Explicit error override (otherwise resolved from bridge). */
+  error?: boolean;
+  /** Explicit disable override (ORed with RBAC). */
+  disabled?: boolean;
+  /** Engine predicate — group not rendered when it returns `false`. */
+  visibleWhen?: (engine: Engine) => boolean;
+  /** Group-level RBAC requirement (precedes option-level access). */
+  access?: AccessRequirement;
+  /** Root className shortcut (`cn`'d with the variant root class). */
+  sx?: string;
+  /** Per-slot className overrides. */
+  slotProps?: RadioGroupSlotProps;
+  /** Controlled value (for standalone mode without a form bridge). */
+  value?: string;
+  /** Default value for uncontrolled mode (no-op in form mode — bridge wins). */
+  defaultValue?: string;
+  /** Change handler (called *after* bridge update in form mode). */
+  onValueChange?: (value: string) => void;
+}

package/src/components/RadioGroup/radioGroup.variants.ts

@@ -0,0 +1,87 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<RadioGroup>` with slots.
+ *
+ * Slots:
+ *   - `root`         — outer wrapper (label + option list + helper/error)
+ *   - `label`        — group-level label (rendered above the option list)
+ *   - `requiredMark` — red asterisk for required groups
+ *   - `optionList`   — container for the radio options (flex direction
+ *                      decided by the `layout` variant)
+ *   - `option`       — wrapper for a single option (control + label)
+ *   - `control`      — visible circle (Radix `RadioGroup.Item`)
+ *   - `indicator`    — inner dot (Radix `RadioGroup.Indicator`)
+ *   - `optionLabel`  — text label associated with the control
+ *   - `helperText`   — descriptive line below the option list
+ *   - `errorText`    — semantic counterpart of helperText for error mode
+ *
+ * Variants:
+ *   - `size`   : sm / md / lg — drives control circle + label text size
+ *   - `layout` : stacked (vertical, default) / row (horizontal)
+ *   - `error`  : bool — swaps borders + helperText color to danger tones
+ */
+export const radioGroupVariants = tv({
+  slots: {
+    root: 'flex flex-col gap-1.5',
+    label: 'block text-sm font-medium text-neutral-900',
+    requiredMark: 'text-danger-500 ml-0.5',
+    optionList: 'flex gap-3',
+    option: 'inline-flex items-center gap-2',
+    control: [
+      'inline-flex items-center justify-center shrink-0',
+      // bg-neutral-50 inverts — dark-mode aware via the dashforge preset.
+      'rounded-full border bg-neutral-50',
+      'border-neutral-300',
+      'transition-colors',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-primary-500',
+      'data-[state=checked]:border-primary-500',
+      'data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed',
+    ],
+    indicator: 'block rounded-full bg-primary-500',
+    optionLabel: 'select-none cursor-pointer text-neutral-900',
+    helperText: 'text-sm text-neutral-600',
+    errorText: 'text-sm text-danger-600',
+  },
+  variants: {
+    size: {
+      sm: {
+        control: 'h-4 w-4',
+        indicator: 'h-2 w-2',
+        optionLabel: 'text-sm',
+      },
+      md: {
+        control: 'h-5 w-5',
+        indicator: 'h-2.5 w-2.5',
+        optionLabel: 'text-base',
+      },
+      lg: {
+        control: 'h-6 w-6',
+        indicator: 'h-3 w-3',
+        optionLabel: 'text-lg',
+      },
+    },
+    layout: {
+      stacked: { optionList: 'flex-col' },
+      row: { optionList: 'flex-row flex-wrap' },
+    },
+    error: {
+      true: {
+        control: 'border-danger-500 focus-visible:ring-danger-500',
+      },
+    },
+    disabled: {
+      true: {
+        control: 'opacity-50 cursor-not-allowed',
+      },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+    layout: 'stacked',
+    error: false,
+    disabled: false,
+  },
+});
+
+export type RadioGroupVariants = VariantProps<typeof radioGroupVariants>;

package/src/components/Snackbar/Snackbar.perf.test.tsx

@@ -0,0 +1,144 @@
+// @vitest-environment jsdom
+/**
+ * Performance + re-render budget tests for `<SnackbarProvider>`.
+ *
+ * Guardrails:
+ *
+ *  1. Mount cost stays tiny — provider lives near app root.
+ *  2. Enqueueing N snackbars in quick succession is O(N) total work,
+ *     NOT O(N²) at the React level.
+ *  3. Provider re-renders ONLY when the visible set changes — children
+ *     subtree is untouched per enqueue.
+ *  4. `api` object identity is stable across provider re-renders so
+ *     consumers can put `enqueue` in `useEffect` deps safely.
+ */
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  cleanup,
+  act,
+} from '@testing-library/react';
+import { SnackbarProvider, useSnackbar } from './Snackbar.js';
+
+void React;
+afterEach(() => cleanup());
+
+describe('<SnackbarProvider> performance', () => {
+  it('mounts in under 200ms with empty children (cold-start safe budget)', () => {
+    const t0 = performance.now();
+    render(
+      <SnackbarProvider>
+        <div />
+      </SnackbarProvider>
+    );
+    const t1 = performance.now();
+    // Generous bound for cold-start under workspace-wide test runs;
+    // warm path is sub-10ms.
+    expect(t1 - t0).toBeLessThan(200);
+  });
+
+  it('enqueues 50 snackbars (cap=50) under 200ms', () => {
+    function Adder() {
+      const { enqueue } = useSnackbar();
+      return (
+        <button
+          data-testid="a"
+          onClick={() => {
+            for (let i = 0; i < 50; i++) {
+              enqueue({ message: `msg-${i}`, autoHideMs: 0 });
+            }
+          }}
+        >
+          add
+        </button>
+      );
+    }
+    render(
+      <SnackbarProvider maxVisible={50}>
+        <Adder />
+      </SnackbarProvider>
+    );
+    const t0 = performance.now();
+    act(() => {
+      fireEvent.click(screen.getByTestId('a'));
+    });
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(200);
+  });
+});
+
+describe('<SnackbarProvider> re-render budget', () => {
+  it('children subtree does NOT re-render on enqueue', () => {
+    const childCount = { count: 0 };
+    const Child = () => {
+      childCount.count++;
+      return <div data-testid="child" />;
+    };
+    function Adder() {
+      const { enqueue } = useSnackbar();
+      return (
+        <button
+          data-testid="a"
+          onClick={() => enqueue({ message: 'hi', autoHideMs: 0 })}
+        >
+          add
+        </button>
+      );
+    }
+    render(
+      <SnackbarProvider>
+        <Child />
+        <Adder />
+      </SnackbarProvider>
+    );
+    const baseline = childCount.count;
+    act(() => {
+      fireEvent.click(screen.getByTestId('a'));
+      fireEvent.click(screen.getByTestId('a'));
+      fireEvent.click(screen.getByTestId('a'));
+    });
+    // The provider RE-renders on each enqueue (state change), which
+    // re-renders its direct children — Child is one of them, so it
+    // re-renders too. The contract is "no MORE than one re-render
+    // PER enqueue". Three enqueues ⇒ ≤ 3 extra child renders.
+    expect(childCount.count - baseline).toBeLessThanOrEqual(3);
+  });
+
+  it('useSnackbar() returns a STABLE api identity across re-renders', () => {
+    const captured: Array<unknown> = [];
+    function Capture() {
+      const api = useSnackbar();
+      captured.push(api);
+      return null;
+    }
+    const Outer = ({ x }: { x: number }) => (
+      <SnackbarProvider>
+        <div data-x={x} />
+        <Capture />
+      </SnackbarProvider>
+    );
+    const { rerender } = render(<Outer x={1} />);
+    rerender(<Outer x={2} />);
+    rerender(<Outer x={3} />);
+    expect(captured.length).toBeGreaterThanOrEqual(3);
+    expect(captured[0]).toBe(captured[1]);
+    expect(captured[1]).toBe(captured[2]);
+  });
+
+  it('renders at most 2 times on mount (provider wrapper)', () => {
+    let count = 0;
+    const Counted = (p: React.ComponentProps<typeof SnackbarProvider>) => {
+      count++;
+      return <SnackbarProvider {...p} />;
+    };
+    render(
+      <Counted>
+        <div />
+      </Counted>
+    );
+    expect(count).toBeLessThanOrEqual(2);
+  });
+});