@dashforge/tw 0.1.0-beta

package/src/components/OTPField/OTPField.tsx

@@ -0,0 +1,250 @@
+import { useContext, useEffect, useId, useRef, useState } from 'react';
+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 { otpFieldVariants } from './otpField.variants.js';
+import type { OTPFieldMode, OTPFieldProps } from './otpField.types.js';
+
+/**
+ * Whitelist allowed characters per mode. Anything else is dropped.
+ *
+ * @internal
+ */
+function sanitize(input: string, mode: OTPFieldMode, max: number): string {
+  const re = mode === 'numeric' ? /[0-9]/ : /[A-Za-z0-9]/;
+  let out = '';
+  for (const ch of input) {
+    if (re.test(ch) && out.length < max) out += ch;
+  }
+  return out;
+}
+
+/**
+ * Dashforge TW OTPField — segmented input for one-time codes.
+ *
+ * Renders N visible "slot" cells over a hidden text input that absorbs
+ * all keystrokes. The visible cells are read-only display surfaces; only
+ * the hidden input takes focus. This pattern works correctly with
+ * password managers + autofill (the hidden input has
+ * `autoComplete="one-time-code"`).
+ *
+ * Bridge contract: the joined string (length ≤ `length`) is what gets
+ * written to the bridge. Use `<DashForm rules={{ minLength: length }} />`
+ * to require a complete code.
+ *
+ * Out of scope for F4-B (deferred to a follow-up sprint):
+ *  - Per-slot click to jump caret
+ *  - Arrow-key navigation between slots
+ *  - Right-to-left input direction
+ *
+ * **A11y**: the hidden `<input>` exposes
+ * `inputMode="numeric" | "text"` per mode + `autoComplete="one-time-code"`
+ * so iOS Safari + Android Chrome trigger SMS autofill correctly.
+ */
+export function OTPField(props: OTPFieldProps) {
+  const {
+    name,
+    rules,
+    visibleWhen,
+    size,
+    label,
+    helperText,
+    required,
+    error,
+    disabled,
+    access,
+    sx,
+    slotProps,
+    length = 6,
+    mode = 'numeric',
+    value: userValue,
+    defaultValue,
+    onChange: userOnChange,
+    onComplete,
+  } = props;
+
+  // ───── Hooks (unconditional) ─────
+  const bridge = useContext(DashFormContext) as DashFormBridge | null;
+  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
+  useDashFieldMeta(name);
+  const accessState = useAccessState(access);
+
+  const inputId = useId();
+  const helperId = `${inputId}-help`;
+  const labelId = `${inputId}-label`;
+
+  const [isFocused, setIsFocused] = useState(false);
+  const [uncontrolledValue, setUncontrolledValue] = useState(() =>
+    sanitize(defaultValue ?? '', mode, length)
+  );
+
+  // 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);
+      });
+    };
+  }, []);
+
+  if (!isVisible) return null;
+  if (!accessState.visible) return null;
+
+  const effectiveDisabled = Boolean(disabled) || accessState.disabled;
+  const effectiveReadOnly = accessState.readonly;
+
+  const isFormMode = Boolean(bridge?.register);
+
+  let resolvedError = error;
+  let resolvedHelperText: typeof helperText = helperText;
+  let registration: FieldRegistration | null = null;
+  let resolvedValue: string;
+
+  if (isFormMode && bridge) {
+    registration = bridge.register(name, rules);
+    const validation = resolveValidationState(name, bridge, error, helperText);
+    resolvedError = validation.error;
+    resolvedHelperText = validation.helperText;
+    if (userValue !== undefined) {
+      resolvedValue = sanitize(userValue, mode, length);
+    } else {
+      const bv = bridge.getValue(name);
+      resolvedValue = sanitize(bv == null ? '' : String(bv), mode, length);
+    }
+  } else if (userValue !== undefined) {
+    resolvedValue = sanitize(userValue, mode, length);
+  } else {
+    resolvedValue = uncontrolledValue;
+  }
+
+  const v = otpFieldVariants({ size, error: resolvedError });
+
+  const commitValue = (next: string) => {
+    const sanitised = sanitize(next, mode, length);
+
+    if (isFormMode && bridge) {
+      bridge.setValue?.(name, sanitised);
+      void registration?.onChange?.({
+        target: { name, value: sanitised },
+        type: 'change',
+      });
+    } else if (userValue === undefined) {
+      setUncontrolledValue(sanitised);
+    }
+
+    userOnChange?.(sanitised);
+
+    if (sanitised.length === length && onComplete) {
+      onComplete(sanitised);
+    }
+  };
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    commitValue(e.target.value);
+  };
+
+  const handlePaste = (e: React.ClipboardEvent<HTMLInputElement>) => {
+    e.preventDefault();
+    const pasted = e.clipboardData.getData('text');
+    commitValue(pasted);
+  };
+
+  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+    setIsFocused(false);
+    if (isFormMode && registration?.onBlur) {
+      registration.onBlur(e);
+    }
+  };
+
+  // Compute the active slot index (cursor position) for the visual
+  // highlight: it's the next empty slot, or the last slot if full.
+  const activeSlotIndex = Math.min(resolvedValue.length, length - 1);
+  const inputMode = mode === 'numeric' ? 'numeric' : 'text';
+
+  return (
+    <div className={cn(v.root(), sx, slotProps?.root?.className)}>
+      {label && (
+        <label
+          id={labelId}
+          htmlFor={inputId}
+          className={cn(v.label(), slotProps?.label?.className)}
+        >
+          {label}
+          {required && (
+            <span
+              aria-hidden="true"
+              className={cn(v.requiredMark(), slotProps?.requiredMark?.className)}
+            >
+              *
+            </span>
+          )}
+        </label>
+      )}
+
+      <div className={cn(v.slotsRow(), slotProps?.slotsRow?.className)}>
+        {Array.from({ length }, (_, i) => {
+          const char = resolvedValue[i] ?? '';
+          const isActive = isFocused && !effectiveDisabled && i === activeSlotIndex;
+          return (
+            <div
+              key={i}
+              data-active={isActive || undefined}
+              data-disabled={effectiveDisabled || undefined}
+              className={cn(v.slot(), slotProps?.slot?.className)}
+              aria-hidden="true"
+            >
+              <span className={cn(v.slotChar(), slotProps?.slotChar?.className)}>
+                {char}
+              </span>
+            </div>
+          );
+        })}
+        <input
+          id={inputId}
+          name={name}
+          type="text"
+          inputMode={inputMode}
+          autoComplete="one-time-code"
+          maxLength={length}
+          value={resolvedValue}
+          disabled={effectiveDisabled}
+          readOnly={effectiveReadOnly}
+          required={required}
+          aria-labelledby={label ? labelId : undefined}
+          aria-invalid={resolvedError || undefined}
+          aria-describedby={resolvedHelperText ? helperId : undefined}
+          onChange={handleChange}
+          onPaste={handlePaste}
+          onFocus={() => setIsFocused(true)}
+          onBlur={handleBlur}
+          ref={registration?.ref as React.Ref<HTMLInputElement> | undefined}
+          className={cn(v.hiddenInput(), slotProps?.hiddenInput?.className)}
+        />
+      </div>
+
+      {resolvedHelperText && (
+        <p
+          id={helperId}
+          className={cn(
+            resolvedError ? v.errorText() : v.helperText(),
+            resolvedError
+              ? slotProps?.errorText?.className
+              : slotProps?.helperText?.className
+          )}
+        >
+          {resolvedHelperText}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/OTPField/otpField.types.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { OTPFieldVariants } from './otpField.variants.js';
+
+export type OTPFieldMode = 'numeric' | 'alphanumeric';
+
+export interface OTPFieldSlotProps {
+  root?: { className?: string };
+  label?: { className?: string };
+  requiredMark?: { className?: string };
+  slotsRow?: { className?: string };
+  slot?: { className?: string };
+  slotChar?: { className?: string };
+  hiddenInput?: { className?: string };
+  helperText?: { className?: string };
+  errorText?: { className?: string };
+}
+
+/**
+ * Props for `<OTPField>`.
+ *
+ * Storage contract: bridge value is a single string (e.g. `"123456"`).
+ * The user types characters that the component sanitises per `mode`:
+ *  - `'numeric'`      → `[0-9]`
+ *  - `'alphanumeric'` → `[A-Za-z0-9]`
+ * Anything else is dropped. Paste content is sanitised the same way and
+ * fills slots sequentially.
+ */
+export interface OTPFieldProps extends OTPFieldVariants {
+  name: string;
+  rules?: unknown;
+  label?: ReactNode;
+  helperText?: ReactNode;
+  required?: boolean;
+  error?: boolean;
+  disabled?: boolean;
+  /** Engine predicate — field not rendered when it returns `false`. */
+  visibleWhen?: (engine: Engine) => boolean;
+  /** RBAC access requirement (combines with explicit `disabled`). */
+  access?: AccessRequirement;
+  /** Root className shortcut. */
+  sx?: string;
+  /** Per-slot className overrides. */
+  slotProps?: OTPFieldSlotProps;
+  /** Number of slots (default 6 — the SMS code convention). */
+  length?: number;
+  /** Character set allowed. Default `'numeric'`. */
+  mode?: OTPFieldMode;
+  /** Controlled value (form mode reads from the bridge if omitted). */
+  value?: string;
+  /** Default value (uncontrolled, standalone mode only). */
+  defaultValue?: string;
+  /** Fires every time the joined value changes (sanitised, ≤ length). */
+  onChange?: (value: string) => void;
+  /** Fires when the user has filled all slots. */
+  onComplete?: (value: string) => void;
+}

package/src/components/OTPField/otpField.variants.ts

@@ -0,0 +1,72 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<OTPField>`.
+ *
+ * Slots:
+ *   - `root`         — outer wrapper (label + slots row + helper/error)
+ *   - `label`        — group-level label
+ *   - `requiredMark` — red `*` for required fields
+ *   - `slotsRow`     — flex row holding the visible slot boxes
+ *   - `slot`         — single slot cell (visual representation of a char)
+ *   - `slotChar`     — the character displayed inside a slot
+ *   - `hiddenInput`  — the actual <input> absorbing keystrokes (visually
+ *                      hidden but focusable + reads as a single
+ *                      one-line text input to AT)
+ *   - `helperText`   — descriptive line below
+ *   - `errorText`    — semantic counterpart of helperText for error mode
+ *
+ * Variants:
+ *   - `size`  : sm / md / lg — drives slot box dimensions + text size
+ *   - `error` : bool — swaps slot border + helperText color to danger tones
+ */
+export const otpFieldVariants = 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',
+    slotsRow: 'relative inline-flex items-center gap-2',
+    slot: [
+      'flex items-center justify-center',
+      // bg-neutral-50 inverts — dark-mode aware via the dashforge preset.
+      'rounded-md border bg-neutral-50',
+      'border-neutral-300',
+      'text-neutral-900 font-mono',
+      'transition-colors',
+      'data-[active=true]:border-primary-500 data-[active=true]:ring-2 data-[active=true]:ring-primary-500/30',
+      'data-[disabled=true]:opacity-60 data-[disabled=true]:cursor-not-allowed',
+    ],
+    slotChar: 'select-none',
+    hiddenInput: [
+      'absolute inset-0 w-full h-full opacity-0',
+      'cursor-text outline-none',
+      'disabled:cursor-not-allowed',
+    ],
+    helperText: 'text-sm text-neutral-600',
+    errorText: 'text-sm text-danger-600',
+  },
+  variants: {
+    size: {
+      sm: {
+        slot: 'h-9 w-7 text-base',
+      },
+      md: {
+        slot: 'h-11 w-9 text-lg',
+      },
+      lg: {
+        slot: 'h-14 w-11 text-2xl',
+      },
+    },
+    error: {
+      true: {
+        slot: 'border-danger-500 data-[active=true]:border-danger-500 data-[active=true]:ring-danger-500/30',
+      },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+    error: false,
+  },
+});
+
+export type OTPFieldVariants = VariantProps<typeof otpFieldVariants>;

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

@@ -0,0 +1,140 @@
+// @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();
+    });
+  });
+});