@dashforge/tw 1.0.0 → 1.1.1

package/src/components/NumberField/numberField.types.ts

@@ -1,72 +0,0 @@
-import type {
-  ChangeEventHandler,
-  FocusEventHandler,
-  InputHTMLAttributes,
-  ReactNode,
-} from 'react';
-import type { Engine } from '@dashforge/ui-core';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { NumberFieldVariants } from './numberField.variants.js';
-
-export interface NumberFieldSlotProps {
-  root?: { className?: string };
-  label?: { className?: string };
-  requiredMark?: { className?: string };
-  inputWrapper?: { className?: string };
-  input?: { className?: string };
-  stepper?: { className?: string };
-  stepperButton?: { className?: string };
-  helperText?: { className?: string };
-  errorText?: { className?: string };
-}
-
-/**
- * Props for `<NumberField>`.
- *
- * Value contract (mirrors `@dashforge/ui/NumberField`):
- *  - Bridge storage type: `number | null` (NEVER `NaN`).
- *  - UI display: `number → String(number)`, `null/undefined → ""`.
- *  - On user input:
- *      - empty string → `setValue(name, null)`
- *      - parseable number → `setValue(name, parsed)`
- *      - non-numeric input → no bridge write (UI string is kept as-is for UX,
- *        but the bridge stays at the last valid value)
- *  - Parsing uses `Number(...)` + `Number.isFinite(...)`. No locale parsing.
- */
-export interface NumberFieldProps
-  extends Omit<
-      InputHTMLAttributes<HTMLInputElement>,
-      'name' | 'type' | 'size' | 'onChange' | 'onBlur' | 'value' | 'defaultValue'
-    >,
-    NumberFieldVariants {
-  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 (`cn`'d with the variant root class). */
-  sx?: string;
-  /** Per-slot className overrides. */
-  slotProps?: NumberFieldSlotProps;
-  /** Controlled value (form mode reads from the bridge if omitted). */
-  value?: number | string | null;
-  /** Default value (uncontrolled, standalone mode only). */
-  defaultValue?: number | string | null;
-  /** Min allowed value (passed to the input + clamps stepper). */
-  min?: number;
-  /** Max allowed value (passed to the input + clamps stepper). */
-  max?: number;
-  /** Stepper step size. Default 1. */
-  step?: number;
-  /** Show inline +/− stepper buttons inside the input wrapper. Default false. */
-  showStepper?: boolean;
-  /** Change handler — receives the native event; consume value via bridge. */
-  onChange?: ChangeEventHandler<HTMLInputElement>;
-  onBlur?: FocusEventHandler<HTMLInputElement>;
-}

package/src/components/NumberField/numberField.variants.ts

@@ -1,94 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<NumberField>`.
- *
- * Same 7-slot taxonomy as `<TextField>` for visual/override parity, plus
- * a dedicated `stepper` slot for the optional +/- increment buttons.
- */
-export const numberFieldVariants = 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 items-center',
-      // 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',
-      'text-neutral-900 placeholder:text-neutral-400',
-      'disabled:cursor-not-allowed disabled:opacity-60',
-      'read-only:cursor-default',
-      // Suppress the native browser spinner — we ship our own optional stepper
-      '[-moz-appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none',
-      // Right-align numeric values by convention
-      'text-right',
-    ],
-    stepper: [
-      'flex flex-col border-l border-neutral-300',
-      'select-none',
-    ],
-    stepperButton: [
-      'flex items-center justify-center px-2 cursor-pointer',
-      'text-neutral-600 hover:text-neutral-900 hover:bg-neutral-100',
-      'disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent',
-      'transition-colors',
-    ],
-    helperText: 'mt-1 text-sm text-neutral-600',
-    errorText: 'mt-1 text-sm text-danger-600',
-  },
-  variants: {
-    size: {
-      sm: {
-        inputWrapper: 'h-8',
-        input: 'text-sm px-2',
-        stepperButton: 'h-4 text-xs',
-      },
-      md: {
-        inputWrapper: 'h-10',
-        input: 'text-base px-3',
-        stepperButton: 'h-5 text-sm',
-      },
-      lg: {
-        inputWrapper: 'h-12',
-        input: 'text-lg px-4',
-        stepperButton: 'h-6 text-base',
-      },
-    },
-    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',
-      },
-    },
-  },
-  defaultVariants: {
-    size: 'md',
-    layout: 'stacked',
-    error: false,
-    fullWidth: false,
-    disabled: false,
-  },
-});
-
-export type NumberFieldVariants = VariantProps<typeof numberFieldVariants>;

package/src/components/OTPField/OTPField.test.tsx

@@ -1,121 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/react';
-import { DashFormProvider } from '@dashforge/forms';
-import { OTPField } from './OTPField.js';
-
-describe('<OTPField>', () => {
-  describe('standalone (no DashForm)', () => {
-    it('renders the configured number of slots (default 6)', () => {
-      const { container } = render(<OTPField name="otp" label="Code" />);
-      // Slots are `<div data-active>` cells inside the slots row — the
-      // hidden input is the 7th flex child but is the only role=textbox.
-      const slots = container.querySelectorAll('[aria-hidden="true"][class*="rounded-md"]');
-      expect(slots).toHaveLength(6);
-    });
-
-    it('renders the requested number of slots (length=4)', () => {
-      const { container } = render(
-        <OTPField name="otp" label="Code" length={4} />
-      );
-      const slots = container.querySelectorAll('[aria-hidden="true"][class*="rounded-md"]');
-      expect(slots).toHaveLength(4);
-    });
-
-    it('renders a `*` for required fields', () => {
-      render(<OTPField name="otp" label="Code" required />);
-      expect(screen.getByText('*')).toBeTruthy();
-    });
-
-    it('renders helperText when provided', () => {
-      render(
-        <OTPField name="otp" label="Code" helperText="Check your phone" />
-      );
-      expect(screen.getByText('Check your phone')).toBeTruthy();
-    });
-
-    it('displays a controlled value across its slots', () => {
-      const { container } = render(
-        <OTPField name="otp" label="Code" value="1234" length={4} onChange={() => undefined} />
-      );
-      const charSpans = container.querySelectorAll('[class*="font-mono"] span');
-      // First 4 slots are filled with 1234
-      expect(charSpans[0]?.textContent).toBe('1');
-      expect(charSpans[1]?.textContent).toBe('2');
-      expect(charSpans[2]?.textContent).toBe('3');
-      expect(charSpans[3]?.textContent).toBe('4');
-    });
-
-    it('numeric mode sanitises non-digit input', () => {
-      const onChange = vi.fn();
-      render(
-        <OTPField name="otp" label="Code" mode="numeric" length={4} onChange={onChange} />
-      );
-      // The hidden input absorbs keystrokes
-      const input = screen.getByLabelText('Code') as HTMLInputElement;
-      fireEvent.change(input, { target: { value: '12ab34' } });
-      // Only digits survive (and capped at length=4)
-      expect(onChange).toHaveBeenCalledWith('1234');
-    });
-
-    it('alphanumeric mode allows letters + digits', () => {
-      const onChange = vi.fn();
-      render(
-        <OTPField
-          name="otp"
-          label="Code"
-          mode="alphanumeric"
-          length={6}
-          onChange={onChange}
-        />
-      );
-      const input = screen.getByLabelText('Code') as HTMLInputElement;
-      fireEvent.change(input, { target: { value: 'a1B2-c3' } });
-      expect(onChange).toHaveBeenCalledWith('a1B2c3');
-    });
-
-    it('fires onComplete when all slots are filled', () => {
-      const onComplete = vi.fn();
-      render(
-        <OTPField
-          name="otp"
-          label="Code"
-          length={4}
-          onComplete={onComplete}
-        />
-      );
-      const input = screen.getByLabelText('Code') as HTMLInputElement;
-      fireEvent.change(input, { target: { value: '9999' } });
-      expect(onComplete).toHaveBeenCalledWith('9999');
-    });
-
-    it('does NOT fire onComplete on partial input', () => {
-      const onComplete = vi.fn();
-      render(
-        <OTPField name="otp" label="Code" length={6} onComplete={onComplete} />
-      );
-      const input = screen.getByLabelText('Code') as HTMLInputElement;
-      fireEvent.change(input, { target: { value: '123' } });
-      expect(onComplete).not.toHaveBeenCalled();
-    });
-
-    it('respects `disabled` on the underlying input', () => {
-      render(<OTPField name="otp" label="Code" disabled />);
-      const input = screen.getByLabelText('Code') as HTMLInputElement;
-      expect(input.disabled).toBe(true);
-    });
-  });
-
-  describe('inside DashFormProvider', () => {
-    it('mounts cleanly inside a bridge-providing tree', () => {
-      render(
-        <DashFormProvider defaultValues={{ otp: '' }}>
-          <OTPField name="otp" label="Code" length={4} />
-        </DashFormProvider>
-      );
-      // Mount-only assertion. Initial value reflection and round-trip
-      // are timing-sensitive in vitest; verified end-to-end in dash.
-      expect(screen.getByLabelText('Code')).toBeInstanceOf(HTMLInputElement);
-    });
-  });
-});

package/src/components/OTPField/OTPField.tsx

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

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

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