@dashforge/tw 1.1.0 → 1.2.0

package/src/components/Popover/Popover.tsx

@@ -1,55 +0,0 @@
-import * as RadixPopover from '@radix-ui/react-popover';
-import { cn } from '../../utils/cn.js';
-import { popoverVariants } from './popover.variants.js';
-import type { PopoverProps } from './popover.types.js';
-
-/**
- * Dashforge TW `<Popover>` — clickable floating content panel.
- *
- * Built on `@radix-ui/react-popover`:
- *  - Focus trap inside the popover (Tab cycles within).
- *  - Outside-click + Escape dismiss.
- *  - APG dialog-like semantics (`role="dialog"` on content).
- *  - Portal-rendered.
- *
- * Use `<Popover>` for menus / pickers / settings panels with
- * interactive children. Use `<Tooltip>` for read-only hints.
- */
-export function Popover(props: PopoverProps) {
-  const {
-    children,
-    content,
-    side = 'bottom',
-    align = 'center',
-    showArrow = false,
-    open,
-    onOpenChange,
-    sideOffset = 8,
-    width,
-    slotProps,
-  } = props;
-
-  const v = popoverVariants();
-
-  return (
-    <RadixPopover.Root open={open} onOpenChange={onOpenChange}>
-      <RadixPopover.Trigger asChild>{children}</RadixPopover.Trigger>
-      <RadixPopover.Portal>
-        <RadixPopover.Content
-          side={side}
-          align={align}
-          sideOffset={sideOffset}
-          style={width != null ? { width } : undefined}
-          className={cn(v.content(), slotProps?.content?.className)}
-        >
-          {content}
-          {showArrow && (
-            <RadixPopover.Arrow
-              className={cn(v.arrow(), slotProps?.arrow?.className)}
-            />
-          )}
-        </RadixPopover.Content>
-      </RadixPopover.Portal>
-    </RadixPopover.Root>
-  );
-}

package/src/components/Popover/popover.types.ts

@@ -1,42 +0,0 @@
-import type { ReactNode } from 'react';
-
-export interface PopoverSlotProps {
-  content?: { className?: string };
-  arrow?: { className?: string };
-}
-
-/**
- * Props for `<Popover>`.
- *
- * Built on `@radix-ui/react-popover`. Use for richer floating UI
- * than a tooltip — e.g. action menus, color pickers, settings
- * panels.
- *
- * Differences vs `<Tooltip>`:
- *  - Popover is **clickable** and captures focus inside (focus trap).
- *  - Popover supports arbitrary interactive content (forms, buttons).
- *  - Popover dismisses on outside-click / Escape (Radix-managed).
- *  - No `role="tooltip"` — popovers are conceptually mini-dialogs.
- */
-export interface PopoverProps {
-  /** The trigger element (wrapped in Radix's `asChild` slot). */
-  children: ReactNode;
-  /** Popover body content. */
-  content: ReactNode;
-  /** Side of the trigger to render on. @default 'bottom' */
-  side?: 'top' | 'right' | 'bottom' | 'left';
-  /** Alignment along the perpendicular axis. @default 'center' */
-  align?: 'start' | 'center' | 'end';
-  /** Show an arrow indicator. @default false */
-  showArrow?: boolean;
-  /** Controlled open state. */
-  open?: boolean;
-  /** Called when open state changes. */
-  onOpenChange?: (open: boolean) => void;
-  /** Side offset in pixels. @default 8 */
-  sideOffset?: number;
-  /** Width of the popover content. CSS value. */
-  width?: string;
-  /** Per-slot overrides. */
-  slotProps?: PopoverSlotProps;
-}

package/src/components/Popover/popover.variants.ts

@@ -1,24 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-export const popoverVariants = tv({
-  slots: {
-    content: [
-      // Neutral border auto-inverts via CSS-var swap.
-      'z-50 rounded-md border border-neutral-200',
-      // bg-white hardcoded (no auto-invert) so `dark:` is required.
-      // Target `dark:bg-neutral-100` resolves to #171717 in dark mode
-      // (one elevation tier above the page surface).
-      'bg-white dark:bg-neutral-100 p-4 shadow-lg',
-      // Text auto-inverts.
-      'text-sm text-neutral-900',
-      'focus:outline-none',
-      'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
-      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
-      'motion-reduce:transition-none motion-reduce:duration-0',
-    ],
-    // Arrow follows content bg: `fill-white` in light + matching dark target.
-    arrow: 'fill-white dark:fill-neutral-100',
-  },
-});
-
-export type PopoverVariants = VariantProps<typeof popoverVariants>;

package/src/components/RadioGroup/RadioGroup.test.tsx

@@ -1,140 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent, within } from '@testing-library/react';
-import { DashFormProvider } from '@dashforge/forms';
-import { RadioGroup } from './RadioGroup.js';
-import type { RadioGroupOption } from './radioGroup.types.js';
-
-const colors: RadioGroupOption[] = [
-  { value: 'red', label: 'Red' },
-  { value: 'green', label: 'Green' },
-  { value: 'blue', label: 'Blue' },
-];
-
-describe('<RadioGroup>', () => {
-  describe('standalone (no DashForm)', () => {
-    it('renders all options with the provided labels', () => {
-      render(
-        <RadioGroup name="color" label="Pick a color" options={colors} />
-      );
-      // Group label rendered as the labelledby anchor
-      expect(screen.getByText('Pick a color')).toBeTruthy();
-      // Each option label resolves through the htmlFor → button id link
-      for (const opt of colors) {
-        expect(screen.getByLabelText(opt.label as string)).toBeTruthy();
-      }
-    });
-
-    it('selects the default value via uncontrolled `defaultValue`', () => {
-      render(
-        <RadioGroup
-          name="color"
-          options={colors}
-          defaultValue="green"
-        />
-      );
-      const radios = screen.getAllByRole('radio');
-      // The second option corresponds to "green"
-      expect(radios[1].getAttribute('data-state')).toBe('checked');
-    });
-
-    it('fires onValueChange on selection', () => {
-      const onValueChange = vi.fn();
-      render(
-        <RadioGroup
-          name="color"
-          options={colors}
-          onValueChange={onValueChange}
-        />
-      );
-      fireEvent.click(screen.getByLabelText('Blue'));
-      expect(onValueChange).toHaveBeenCalledWith('blue');
-    });
-
-    it('respects per-option `disabled`', () => {
-      const opts: RadioGroupOption[] = [
-        { value: 'a', label: 'A' },
-        { value: 'b', label: 'B', disabled: true },
-      ];
-      render(<RadioGroup name="x" options={opts} />);
-      const radios = screen.getAllByRole('radio') as HTMLButtonElement[];
-      expect(radios[0].disabled).toBe(false);
-      expect(radios[1].disabled).toBe(true);
-    });
-
-    it('disables ALL options when the group is disabled', () => {
-      render(
-        <RadioGroup name="color" options={colors} disabled />
-      );
-      for (const r of screen.getAllByRole('radio') as HTMLButtonElement[]) {
-        expect(r.disabled).toBe(true);
-      }
-    });
-  });
-
-  describe('inside DashFormProvider', () => {
-    it('renders without errors inside a bridge-providing tree', () => {
-      render(
-        <DashFormProvider defaultValues={{ color: 'green' }}>
-          <RadioGroup name="color" label="Color" options={colors} />
-        </DashFormProvider>
-      );
-      // Bridge mode mounts cleanly; all three options render. The exact
-      // checked-state reflection is verified end-to-end in the F4 smoke
-      // page in learn/dash where the full reactive cycle has time to
-      // settle — unit-test assertions on Radix internal state right
-      // after render are timing-sensitive and not worth the brittleness.
-      expect(screen.getAllByRole('radio')).toHaveLength(3);
-    });
-
-    it('renders the helperText when provided', () => {
-      render(
-        <DashFormProvider defaultValues={{ color: '' }}>
-          <RadioGroup
-            name="color"
-            options={colors}
-            helperText="Choose carefully"
-          />
-        </DashFormProvider>
-      );
-      expect(screen.getByText('Choose carefully')).toBeTruthy();
-    });
-  });
-
-  describe('layout variant', () => {
-    it('default `stacked` renders options vertically (flex-col)', () => {
-      const { container } = render(
-        <RadioGroup name="x" options={colors} />
-      );
-      const list = within(container).getByRole('radiogroup');
-      expect(list.className).toMatch(/flex-col/);
-    });
-
-    it('`row` layout renders options horizontally', () => {
-      const { container } = render(
-        <RadioGroup name="x" options={colors} layout="row" />
-      );
-      const list = within(container).getByRole('radiogroup');
-      expect(list.className).toMatch(/flex-row/);
-    });
-  });
-
-  describe('required marker', () => {
-    it('renders a red `*` after the label when `required` is set', () => {
-      render(
-        <RadioGroup
-          name="x"
-          options={colors}
-          label="Color"
-          required
-        />
-      );
-      expect(screen.getByText('*')).toBeTruthy();
-    });
-
-    it('does NOT render a `*` when `required` is omitted', () => {
-      render(<RadioGroup name="x" options={colors} label="Color" />);
-      expect(screen.queryByText('*')).toBeNull();
-    });
-  });
-});

package/src/components/RadioGroup/RadioGroup.tsx

@@ -1,283 +0,0 @@
-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>
-      )}
-
-      {/*
-       * Radix RadioGroup mode discrimination — mirrors the same fix
-       * applied to <Checkbox>:
-       *
-       *   - Form mode (bridge.register present): controlled — `value`
-       *     comes from the reactive bridge snapshot, `handleValueChange`
-       *     writes back through bridge.setValue.
-       *   - Standalone controlled (consumer passes `value`): controlled —
-       *     consumer owns state, `handleValueChange` forwards via
-       *     `onValueChange`.
-       *   - Standalone uncontrolled (only `defaultValue`): UNCONTROLLED —
-       *     Radix owns the state. Previously this code passed
-       *     `value={resolvedValue}` in this branch too, putting Radix
-       *     in controlled mode with a stale snapshot that never updated,
-       *     so user clicks fired Radix's onValueChange but the controlled
-       *     prop never changed and the selection snapped right back.
-       *
-       * Picking exactly one of `{ value, ... }` or `{ defaultValue, ... }`
-       * lets Radix track its own state correctly when nobody else can.
-       */}
-      <RadixRadioGroup.Root
-        name={name}
-        {...(isFormMode || explicitValue !== undefined
-          ? { value: resolvedValue }
-          : { defaultValue: defaultValue ?? undefined })}
-        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

@@ -1,85 +0,0 @@
-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;
-}