@dashforge/tw 1.1.0 → 1.2.0

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>;

package/src/components/Pagination/Pagination.test.tsx

@@ -1,314 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, afterEach } from 'vitest';
-import { render, screen, fireEvent, cleanup } from '@testing-library/react';
-import { Pagination } from './Pagination.js';
-import { computePageRange } from './pagination.helpers.js';
-
-void React;
-afterEach(() => cleanup());
-
-describe('computePageRange — helper', () => {
-  it('returns empty for totalPages=0', () => {
-    expect(computePageRange(1, 0, 1, 1)).toEqual([]);
-  });
-
-  it('returns [1] for totalPages=1', () => {
-    expect(computePageRange(1, 1, 1, 1)).toEqual([1]);
-  });
-
-  it('lists all pages when totalPages <= window size', () => {
-    expect(computePageRange(1, 5, 1, 1)).toEqual([1, 2, 3, 4, 5]);
-  });
-
-  it('inserts ellipsis on the right when current is near start', () => {
-    const r = computePageRange(2, 20, 1, 1);
-    expect(r).toContain(1);
-    expect(r).toContain(2);
-    expect(r).toContain(3);
-    expect(r).toContain('ellipsis');
-    expect(r).toContain(20);
-    expect(r).not.toContain(10);
-  });
-
-  it('inserts ellipsis on both sides when current is in the middle', () => {
-    const r = computePageRange(10, 20, 1, 1);
-    expect(r.filter((x) => x === 'ellipsis').length).toBeGreaterThanOrEqual(1);
-    expect(r).toContain(1);
-    expect(r).toContain(9);
-    expect(r).toContain(10);
-    expect(r).toContain(11);
-    expect(r).toContain(20);
-  });
-
-  it('inserts ellipsis on the left when current is near end', () => {
-    const r = computePageRange(19, 20, 1, 1);
-    expect(r).toContain(1);
-    expect(r).toContain('ellipsis');
-    expect(r).toContain(18);
-    expect(r).toContain(19);
-    expect(r).toContain(20);
-  });
-
-  it('respects siblingCount=2', () => {
-    const r = computePageRange(10, 20, 2, 1);
-    expect(r).toContain(8);
-    expect(r).toContain(9);
-    expect(r).toContain(10);
-    expect(r).toContain(11);
-    expect(r).toContain(12);
-  });
-
-  it('respects boundaryCount=2', () => {
-    const r = computePageRange(10, 20, 1, 2);
-    expect(r).toContain(1);
-    expect(r).toContain(2);
-    expect(r).toContain(19);
-    expect(r).toContain(20);
-  });
-});
-
-describe('Pagination — rendering (default variant)', () => {
-  it('renders nav landmark with aria-label', () => {
-    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
-    expect(screen.getByRole('navigation', { name: 'Pagination' })).not.toBeNull();
-  });
-
-  it('renders the "Showing X-Y of Z" summary', () => {
-    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
-    expect(screen.getByText(/Showing 1-10 of 50/)).not.toBeNull();
-  });
-
-  it('renders correct summary on last page (partial fill)', () => {
-    render(<Pagination page={5} pageSize={10} totalCount={47} onPageChange={() => {}} />);
-    expect(screen.getByText(/Showing 41-47 of 47/)).not.toBeNull();
-  });
-
-  it('marks active page with aria-current=page', () => {
-    render(<Pagination page={3} pageSize={10} totalCount={50} onPageChange={() => {}} />);
-    const active = screen.getByRole('button', { name: 'Page 3' });
-    expect(active.getAttribute('aria-current')).toBe('page');
-  });
-
-  it('disables Prev + First on page 1', () => {
-    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
-    expect((screen.getByRole('button', { name: 'Previous' }) as HTMLButtonElement).disabled).toBe(true);
-    expect((screen.getByRole('button', { name: 'First' }) as HTMLButtonElement).disabled).toBe(true);
-  });
-
-  it('disables Next + Last on last page', () => {
-    render(<Pagination page={5} pageSize={10} totalCount={50} onPageChange={() => {}} />);
-    expect((screen.getByRole('button', { name: 'Next' }) as HTMLButtonElement).disabled).toBe(true);
-    expect((screen.getByRole('button', { name: 'Last' }) as HTMLButtonElement).disabled).toBe(true);
-  });
-});
-
-describe('Pagination — interactions', () => {
-  it('emits onPageChange when a page button is clicked', () => {
-    let last = 0;
-    render(
-      <Pagination
-        page={1}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={(p) => (last = p)}
-      />,
-    );
-    fireEvent.click(screen.getByRole('button', { name: 'Page 3' }));
-    expect(last).toBe(3);
-  });
-
-  it('Prev decrements page', () => {
-    let last = 0;
-    render(
-      <Pagination
-        page={3}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={(p) => (last = p)}
-      />,
-    );
-    fireEvent.click(screen.getByRole('button', { name: 'Previous' }));
-    expect(last).toBe(2);
-  });
-
-  it('Next increments page', () => {
-    let last = 0;
-    render(
-      <Pagination
-        page={3}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={(p) => (last = p)}
-      />,
-    );
-    fireEvent.click(screen.getByRole('button', { name: 'Next' }));
-    expect(last).toBe(4);
-  });
-
-  it('First/Last jump to extremes', () => {
-    let last = 0;
-    const { rerender } = render(
-      <Pagination
-        page={3}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={(p) => (last = p)}
-      />,
-    );
-    fireEvent.click(screen.getByRole('button', { name: 'First' }));
-    expect(last).toBe(1);
-    rerender(
-      <Pagination
-        page={3}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={(p) => (last = p)}
-      />,
-    );
-    fireEvent.click(screen.getByRole('button', { name: 'Last' }));
-    expect(last).toBe(5);
-  });
-
-  it('emits onPageSizeChange when selector changes', () => {
-    let lastSize = 0;
-    render(
-      <Pagination
-        page={1}
-        pageSize={10}
-        totalCount={100}
-        onPageChange={() => {}}
-        onPageSizeChange={(s) => (lastSize = s)}
-      />,
-    );
-    const selector = screen.getByLabelText('per page') as HTMLSelectElement;
-    fireEvent.change(selector, { target: { value: '50' } });
-    expect(lastSize).toBe(50);
-  });
-
-  it('hides page-size selector if onPageSizeChange not provided', () => {
-    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
-    expect(screen.queryByLabelText('per page')).toBeNull();
-  });
-});
-
-describe('Pagination — variants', () => {
-  it('compact variant hides summary + selector', () => {
-    render(
-      <Pagination
-        variant="compact"
-        page={1}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={() => {}}
-        onPageSizeChange={() => {}}
-      />,
-    );
-    expect(screen.queryByText(/Showing/)).toBeNull();
-    expect(screen.queryByLabelText('per page')).toBeNull();
-  });
-
-  it('minimal variant shows "Page X of Y" + only Prev/Next', () => {
-    render(
-      <Pagination
-        variant="minimal"
-        page={3}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={() => {}}
-      />,
-    );
-    expect(screen.getByText(/Page 3 of 5/)).not.toBeNull();
-    // Page-number buttons should NOT exist
-    expect(screen.queryByRole('button', { name: 'Page 1' })).toBeNull();
-    // Prev / Next remain
-    expect(screen.queryByRole('button', { name: 'Previous' })).not.toBeNull();
-    expect(screen.queryByRole('button', { name: 'Next' })).not.toBeNull();
-  });
-});
-
-describe('Pagination — i18n', () => {
-  it('honors custom labels', () => {
-    render(
-      <Pagination
-        page={1}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={() => {}}
-        labels={{ showing: 'Mostro', of: 'di', prev: 'Indietro', next: 'Avanti' }}
-      />,
-    );
-    expect(screen.getByText(/Mostro 1-10 di 50/)).not.toBeNull();
-    expect(screen.queryByRole('button', { name: 'Indietro' })).not.toBeNull();
-    expect(screen.queryByRole('button', { name: 'Avanti' })).not.toBeNull();
-  });
-});
-
-describe('Pagination — disabled', () => {
-  it('disables all buttons when disabled=true', () => {
-    render(
-      <Pagination
-        page={3}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={() => {}}
-        disabled
-      />,
-    );
-    expect((screen.getByRole('button', { name: 'Previous' }) as HTMLButtonElement).disabled).toBe(true);
-    expect((screen.getByRole('button', { name: 'Next' }) as HTMLButtonElement).disabled).toBe(true);
-    expect((screen.getByRole('button', { name: 'Page 2' }) as HTMLButtonElement).disabled).toBe(true);
-  });
-});
-
-describe('Pagination — sx + slotProps', () => {
-  it('applies sx to root', () => {
-    const { container } = render(
-      <Pagination
-        page={1}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={() => {}}
-        sx="my-custom-root"
-      />,
-    );
-    expect(container.querySelector('nav')!.className).toContain('my-custom-root');
-  });
-
-  it('applies slotProps.pageButton.className', () => {
-    render(
-      <Pagination
-        page={1}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={() => {}}
-        slotProps={{ pageButton: { className: 'slot-page' } }}
-      />,
-    );
-    expect(screen.getByRole('button', { name: 'Page 2' }).className).toContain('slot-page');
-  });
-});
-
-describe('Pagination — edge cases', () => {
-  it('renders correctly with totalCount=0', () => {
-    render(<Pagination page={1} pageSize={10} totalCount={0} onPageChange={() => {}} />);
-    expect(screen.getByText(/Showing 0-0 of 0/)).not.toBeNull();
-    expect((screen.getByRole('button', { name: 'Previous' }) as HTMLButtonElement).disabled).toBe(true);
-    expect((screen.getByRole('button', { name: 'Next' }) as HTMLButtonElement).disabled).toBe(true);
-  });
-
-  it('clamps page > totalPages internally without crashing', () => {
-    let last = 0;
-    render(
-      <Pagination
-        page={99}
-        pageSize={10}
-        totalCount={50}
-        onPageChange={(p) => (last = p)}
-      />,
-    );
-    // Component computes safePage=5 (last valid). User clicks Prev → goes to 4.
-    fireEvent.click(screen.getByRole('button', { name: 'Previous' }));
-    expect(last).toBe(4);
-  });
-});