@dashforge/tw 0.1.0-beta

package/src/components/NumberField/NumberField.tsx

@@ -0,0 +1,293 @@
+import { useCallback, useContext, useEffect, useId, useRef } 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 { numberFieldVariants } from './numberField.variants.js';
+import type { NumberFieldProps } from './numberField.types.js';
+
+/**
+ * Format a numeric bridge value for the input UI.
+ *
+ * Strict rules (mirror the MUI side):
+ *  - `number` → `String(n)` (no thousands separators, no locale)
+ *  - `null` / `undefined` → empty string (so the input shows blank)
+ *  - non-finite numbers (NaN, ±Infinity) are coerced to `""` and never written
+ *    back to the bridge
+ *
+ * @internal
+ */
+function formatForDisplay(v: unknown): string {
+  if (v == null) return '';
+  if (typeof v === 'number') {
+    return Number.isFinite(v) ? String(v) : '';
+  }
+  if (typeof v === 'string') return v;
+  return '';
+}
+
+/**
+ * Coerce a string from the input back to the bridge storage type.
+ *
+ *  - `""` → `null` (cleared)
+ *  - parseable finite number → that number
+ *  - anything else → `undefined` (caller should NOT write to the bridge)
+ *
+ * @internal
+ */
+function parseFromInput(str: string): number | null | undefined {
+  if (str === '') return null;
+  // Allow the user to type the leading sign or a trailing decimal point without
+  // committing a partial number to the bridge — those parse to NaN here.
+  const n = Number(str);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * Dashforge TW NumberField — bridge-integrated numeric input.
+ *
+ * Mirrors `@dashforge/ui/NumberField` semantics: storage type is
+ * `number | null`, NaN is never written, `Number.isFinite` is the guard.
+ * Renders a native `<input type="number">` with an OPTIONAL +/− stepper
+ * (opt-in via `showStepper`). The native browser spinner is suppressed
+ * in CSS so visual consistency is preserved cross-browser.
+ *
+ * **A11y**:
+ *  - `aria-invalid` from resolved validation state
+ *  - `aria-describedby` links the input to the helper/error text
+ *  - `min` / `max` / `step` forwarded to the native input (which exposes
+ *    `aria-valuemin` / `aria-valuemax` automatically)
+ */
+export function NumberField(props: NumberFieldProps) {
+  const {
+    name,
+    rules,
+    visibleWhen,
+    layout = 'stacked',
+    size,
+    label,
+    helperText,
+    required,
+    error,
+    disabled,
+    fullWidth,
+    access,
+    sx,
+    slotProps,
+    placeholder,
+    min,
+    max,
+    step = 1,
+    showStepper = false,
+    onChange: userOnChange,
+    onBlur: userOnBlur,
+    value: userValue,
+    defaultValue,
+    ...rest
+  } = props;
+
+  // ───── Hooks (unconditional) ─────
+  const bridge = useContext(DashFormContext) as DashFormBridge | null;
+  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
+  // Per-field subscription side-effect. Value read happens via
+  // `bridge.getValue(name)` (mirrors MUI side — avoids first-render
+  // undefined window from `useDashFieldMeta.value`).
+  useDashFieldMeta(name);
+  const accessState = useAccessState(access);
+
+  const inputId = useId();
+  const helperId = `${inputId}-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);
+      });
+    };
+  }, []);
+
+  // ───── Derived (every hook MUST be called above the early returns) ─────
+  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 resolvedDisplayValue: string;
+
+  if (isFormMode && bridge) {
+    registration = bridge.register(name, rules);
+    const validation = resolveValidationState(name, bridge, error, helperText);
+    resolvedError = validation.error;
+    resolvedHelperText = validation.helperText;
+    resolvedDisplayValue =
+      userValue !== undefined
+        ? formatForDisplay(userValue)
+        : formatForDisplay(bridge.getValue(name));
+  } else {
+    resolvedDisplayValue =
+      userValue !== undefined
+        ? formatForDisplay(userValue)
+        : formatForDisplay(defaultValue);
+  }
+
+  const writeToBridge = (parsed: number | null | undefined) => {
+    if (!isFormMode || !bridge) return;
+    if (parsed === undefined) return; // partial/invalid — don't pollute the bridge
+    bridge.setValue?.(name, parsed);
+  };
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const parsed = parseFromInput(e.target.value);
+    writeToBridge(parsed);
+    if (isFormMode && registration?.onChange) {
+      // Forward to RHF — pass through the original event so RHF's
+      // internal logic still sees the raw string change.
+      void registration.onChange(e);
+    }
+    userOnChange?.(e);
+  };
+
+  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+    if (isFormMode && registration?.onBlur) {
+      registration.onBlur(e);
+    }
+    userOnBlur?.(e);
+  };
+
+  const stepBy = (delta: number) => {
+    const current = isFormMode && bridge
+      ? (bridge.getValue(name) as number | null | undefined)
+      : parseFromInput(resolvedDisplayValue);
+    const base = typeof current === 'number' && Number.isFinite(current) ? current : 0;
+    let next = base + delta;
+    if (typeof min === 'number') next = Math.max(min, next);
+    if (typeof max === 'number') next = Math.min(max, next);
+    writeToBridge(next);
+  };
+
+  const canIncrement =
+    !effectiveDisabled && (typeof max !== 'number' || (parseFromInput(resolvedDisplayValue) ?? -Infinity) < max);
+  const canDecrement =
+    !effectiveDisabled && (typeof min !== 'number' || (parseFromInput(resolvedDisplayValue) ?? Infinity) > min);
+
+  const registrationRefFn = registration?.ref;
+  const inputRef = useCallback(
+    (instance: HTMLInputElement | null) => {
+      if (typeof registrationRefFn === 'function') {
+        registrationRefFn(instance);
+      }
+    },
+    [registrationRefFn]
+  );
+
+  // ───── Render-time guards (after all hooks) ─────
+  if (!isVisible) return null;
+  if (!accessState.visible) return null;
+
+  const v = numberFieldVariants({
+    size,
+    layout,
+    error: resolvedError,
+    fullWidth,
+    disabled: effectiveDisabled,
+  });
+
+  return (
+    <div className={cn(v.root(), sx, slotProps?.root?.className)}>
+      {label && (
+        <label
+          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.inputWrapper(), slotProps?.inputWrapper?.className)}>
+        <input
+          {...rest}
+          id={inputId}
+          name={name}
+          type="number"
+          placeholder={placeholder}
+          value={resolvedDisplayValue}
+          min={min}
+          max={max}
+          step={step}
+          disabled={effectiveDisabled}
+          readOnly={effectiveReadOnly}
+          required={required}
+          aria-invalid={resolvedError || undefined}
+          aria-describedby={resolvedHelperText ? helperId : undefined}
+          onChange={handleChange}
+          onBlur={handleBlur}
+          ref={inputRef}
+          className={cn(v.input(), slotProps?.input?.className)}
+        />
+
+        {showStepper && (
+          <div
+            className={cn(v.stepper(), slotProps?.stepper?.className)}
+            aria-hidden="true"
+          >
+            <button
+              type="button"
+              tabIndex={-1}
+              onClick={() => stepBy(step)}
+              disabled={!canIncrement}
+              className={cn(v.stepperButton(), slotProps?.stepperButton?.className)}
+              aria-label="Increment"
+            >
+              ▲
+            </button>
+            <button
+              type="button"
+              tabIndex={-1}
+              onClick={() => stepBy(-step)}
+              disabled={!canDecrement}
+              className={cn(v.stepperButton(), slotProps?.stepperButton?.className)}
+              aria-label="Decrement"
+            >
+              ▼
+            </button>
+          </div>
+        )}
+      </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/NumberField/numberField.types.ts

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

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

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