@dashforge/tw 1.1.0 → 1.2.0

package/src/components/TextField/TextField.test.tsx

@@ -1,198 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect, vi } from 'vitest';
-import { render, fireEvent } from '@testing-library/react';
-import { RbacProvider } from '@dashforge/rbac';
-import type { RbacPolicy, Subject } from '@dashforge/rbac';
-import { DashFormProvider } from '@dashforge/forms';
-import { TextField } from './TextField.js';
-
-const READ_ONLY: RbacPolicy = {
-  roles: [
-    {
-      name: 'viewer',
-      permissions: [{ resource: 'doc', action: 'update', effect: 'deny' }],
-    },
-  ],
-};
-const viewer: Subject = { id: 'v', roles: ['viewer'] };
-
-function withForm(children: React.ReactNode, defaultValues: Record<string, unknown> = {}) {
-  return <DashFormProvider defaultValues={defaultValues}>{children}</DashFormProvider>;
-}
-
-describe('TextField — standalone', () => {
-  it('renders an <input type="text"> by default', () => {
-    const { getByRole } = render(<TextField name="email" label="Email" />);
-    const input = getByRole('textbox') as HTMLInputElement;
-    expect(input.type).toBe('text');
-  });
-
-  it('label is wired via htmlFor to the input id', () => {
-    const { getByText, getByRole } = render(<TextField name="x" label="My label" />);
-    const label = getByText('My label').closest('label') as HTMLLabelElement;
-    expect(label.htmlFor).toBe((getByRole('textbox') as HTMLInputElement).id);
-  });
-
-  it('renders the required asterisk and sets the native required attr', () => {
-    const { getByText, getByRole } = render(
-      <TextField name="x" label="X" required />
-    );
-    expect(getByText('*')).toBeTruthy();
-    expect((getByRole('textbox') as HTMLInputElement).required).toBe(true);
-  });
-
-  it('forwards type="password" / "email" / etc.', () => {
-    const { getByLabelText } = render(<TextField name="p" label="P" type="password" />);
-    expect((getByLabelText('P') as HTMLInputElement).type).toBe('password');
-  });
-
-  it('renders helperText below the input', () => {
-    const { getByText } = render(<TextField name="x" label="X" helperText="Hint" />);
-    expect(getByText('Hint')).toBeTruthy();
-  });
-
-  it('aria-describedby links to the helper text id when present', () => {
-    const { getByRole, getByText } = render(
-      <TextField name="x" label="X" helperText="Hint" />
-    );
-    const input = getByRole('textbox') as HTMLInputElement;
-    const helperId = input.getAttribute('aria-describedby');
-    expect(helperId).toBeTruthy();
-    expect(getByText('Hint').id).toBe(helperId);
-  });
-});
-
-describe('TextField — variants', () => {
-  it('size lg uses h-12 + text-lg', () => {
-    const { container } = render(<TextField name="x" label="X" size="lg" />);
-    const wrap = container.querySelector('div[class*="rounded-md"]');
-    expect(wrap?.className).toContain('h-12');
-    expect(container.querySelector('input')?.className).toContain('text-lg');
-  });
-
-  it('error=true applies danger ring + uses errorText slot for helperText', () => {
-    const { container, getByText } = render(
-      <TextField name="x" label="X" error helperText="Bad" />
-    );
-    expect(container.querySelector('div[class*="rounded-md"]')?.className).toContain(
-      'border-danger-500'
-    );
-    expect(getByText('Bad').className).toContain('text-danger-600');
-  });
-
-  it('aria-invalid is set when error=true', () => {
-    const { getByRole } = render(<TextField name="x" label="X" error />);
-    expect(getByRole('textbox').getAttribute('aria-invalid')).toBe('true');
-  });
-
-  it('fullWidth adds w-full to root + wrapper', () => {
-    const { container } = render(<TextField name="x" label="X" fullWidth />);
-    expect((container.firstChild as HTMLElement).className).toContain('w-full');
-  });
-
-  it('layout=inline puts label and input side by side', () => {
-    const { container } = render(<TextField name="x" label="X" layout="inline" />);
-    expect((container.firstChild as HTMLElement).className).toContain('flex-row');
-  });
-});
-
-describe('TextField — override (sx + slotProps)', () => {
-  it('sx is applied to root', () => {
-    const { container } = render(<TextField name="x" label="X" sx="md:w-1/2" />);
-    expect((container.firstChild as HTMLElement).className).toContain('md:w-1/2');
-  });
-
-  it('slotProps.input applies to the <input>', () => {
-    const { getByRole } = render(
-      <TextField name="x" label="X" slotProps={{ input: { className: 'font-mono' } }} />
-    );
-    expect(getByRole('textbox').className).toContain('font-mono');
-  });
-
-  it('slotProps.label applies to the <label>', () => {
-    const { getByText } = render(
-      <TextField name="x" label="My" slotProps={{ label: { className: 'uppercase' } }} />
-    );
-    const label = getByText('My').closest('label');
-    expect(label?.className).toContain('uppercase');
-  });
-});
-
-describe('TextField — RBAC', () => {
-  it('hides with onUnauthorized=hide', () => {
-    const { queryByRole } = render(
-      <RbacProvider policy={READ_ONLY} subject={viewer}>
-        <TextField
-          name="x"
-          label="X"
-          access={{ resource: 'doc', action: 'update', onUnauthorized: 'hide' }}
-        />
-      </RbacProvider>
-    );
-    expect(queryByRole('textbox')).toBeNull();
-  });
-
-  it('disables with onUnauthorized=disable', () => {
-    const { getByRole } = render(
-      <RbacProvider policy={READ_ONLY} subject={viewer}>
-        <TextField
-          name="x"
-          label="X"
-          access={{ resource: 'doc', action: 'update', onUnauthorized: 'disable' }}
-        />
-      </RbacProvider>
-    );
-    expect((getByRole('textbox') as HTMLInputElement).disabled).toBe(true);
-  });
-
-  it('becomes readonly with onUnauthorized=readonly', () => {
-    const { getByRole } = render(
-      <RbacProvider policy={READ_ONLY} subject={viewer}>
-        <TextField
-          name="x"
-          label="X"
-          access={{ resource: 'doc', action: 'update', onUnauthorized: 'readonly' }}
-        />
-      </RbacProvider>
-    );
-    expect((getByRole('textbox') as HTMLInputElement).readOnly).toBe(true);
-  });
-});
-
-describe('TextField — DashFormProvider integration', () => {
-  it('renders inside DashFormProvider', () => {
-    const { getByRole } = render(withForm(<TextField name="email" label="Email" />));
-    expect(getByRole('textbox')).toBeTruthy();
-  });
-
-  it('updates the input value as the user types', () => {
-    const { getByRole } = render(withForm(<TextField name="email" label="Email" />));
-    const input = getByRole('textbox') as HTMLInputElement;
-    fireEvent.change(input, { target: { value: 'hi@example.com' } });
-    expect(input.value).toBe('hi@example.com');
-  });
-
-  // Skipped pending decision on the bridge ↔ controlled-value contract
-  // (the current implementation lets the bridge value win when both are
-  // present; the test as written asserts the opposite). Behavior to
-  // resolve in 1.0.1 — see TextField.tsx line ~203.
-  it.skip('respects explicit `value` (controlled mode wins over bridge)', () => {
-    const onChange = vi.fn();
-    const { getByRole } = render(
-      withForm(
-        <TextField name="email" label="Email" value="forced" onChange={onChange} />,
-        { email: '' }
-      )
-    );
-    expect((getByRole('textbox') as HTMLInputElement).value).toBe('forced');
-  });
-
-  it('fires user onChange in addition to the bridge update', () => {
-    const onChange = vi.fn();
-    const { getByRole } = render(
-      withForm(<TextField name="email" label="Email" onChange={onChange} />)
-    );
-    fireEvent.change(getByRole('textbox'), { target: { value: 'x' } });
-    expect(onChange).toHaveBeenCalled();
-  });
-});

package/src/components/TextField/TextField.tsx

@@ -1,245 +0,0 @@
-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 { textFieldVariants } from './textField.variants.js';
-import type { TextFieldProps } from './textField.types.js';
-
-/**
- * Dashforge TW TextField — bridge-integrated text input.
- *
- * Implementation mirrors `@dashforge/ui/TextField` (MUI) at the bridge
- * level — same `name` / `rules` / `visibleWhen` / `access` semantics,
- * same validation gating, same StrictMode-safe unregister pattern.
- * Renderer differences:
- *
- *  - Native `<input>` element wrapped in a TV-styled
- *    `<div role-less wrapper>` so the focus ring extends to the entire
- *    field (consistent with shadcn-style inputs).
- *  - Layout modes: `stacked` (default — label above) and `inline`
- *    (label left of input). MUI's `floating` mode is deferred to a
- *    follow-up sprint; consumers needing the visual can layer it via
- *    `slotProps`.
- *  - No Select-integration hook (Select lands in F4 as its own component).
- *
- * **A11y**:
- *   - `aria-invalid` is set from the resolved validation state.
- *   - `aria-describedby` links the input to the helper/error text node.
- *   - Required fields get the native `required` attribute + a visual `*`.
- */
-export function TextField(props: TextFieldProps) {
-  const {
-    name,
-    rules,
-    visibleWhen,
-    layout = 'stacked',
-    size,
-    label,
-    helperText,
-    required,
-    error,
-    disabled,
-    fullWidth,
-    access,
-    sx,
-    slotProps,
-    placeholder,
-    type,
-    onChange: userOnChange,
-    onBlur: userOnBlur,
-    value: userValue,
-    defaultValue,
-    ...rest
-  } = props;
-
-  // ───── Hooks (unconditional) ─────
-  const bridge = useContext(DashFormContext) as DashFormBridge | null;
-  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
-  // Granular per-field subscription. We READ from `fieldMeta.value`
-  // (reactive snapshot) rather than `bridge.getValue(name)` (eager
-  // read with no subscription) so React re-renders this field on its
-  // own state mutations — the canonical pattern, mirrors the MUI side.
-  const fieldMeta = 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 resolvedValue: string | number | readonly string[] | undefined = userValue as
-    | string
-    | number
-    | readonly string[]
-    | undefined;
-
-  if (isFormMode && bridge) {
-    registration = bridge.register(name, rules);
-    const validation = resolveValidationState(name, bridge, error, helperText);
-    resolvedError = validation.error;
-    resolvedHelperText = validation.helperText;
-    if (userValue === undefined) {
-      // Read the reactive snapshot from `useDashFieldMeta` — NOT
-      // `bridge.getValue` — so the component re-renders on every
-      // per-field state change without the unsubscribe trick the
-      // legacy bridge used.
-      const bv = fieldMeta.value;
-      resolvedValue =
-        bv == null ? '' : (bv as string | number);
-    }
-  }
-
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    if (isFormMode && bridge) {
-      bridge.setValue?.(name, e.target.value);
-      void registration?.onChange?.(e);
-    }
-    userOnChange?.(e);
-  };
-
-  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
-    if (isFormMode && bridge) {
-      registration?.onBlur?.(e);
-    }
-    userOnBlur?.(e);
-  };
-
-  // In form mode, RHF supplies its own callback ref via registration.
-  // Wrap it in a stable callback so React 19 unambiguously treats it as
-  // a callback ref (and to give us a single place to extend the ref
-  // chain in the future — e.g. for a user-supplied `ref` prop via
-  // `forwardRef`).
-  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 = textFieldVariants({
-    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)}>
-        {/*
-         * Prefix slot (Sprint 2 P4.1) — inline adornment rendered
-         * BEFORE the input. Mounts only when `slotProps.prefix.children`
-         * is provided so empty configs don't add layout cost. Common
-         * use: currency symbols (`$`, `€`), units (`@`, `#`), status
-         * icons. The slot wrapper carries `pointer-events-none` to
-         * avoid stealing focus from the input on click.
-         */}
-        {slotProps?.prefix?.children !== undefined && (
-          <span
-            aria-hidden="true"
-            className={cn(v.prefix(), slotProps.prefix.className)}
-          >
-            {slotProps.prefix.children}
-          </span>
-        )}
-        <input
-          {...rest}
-          id={inputId}
-          name={name}
-          type={type ?? 'text'}
-          placeholder={placeholder}
-          value={isFormMode ? (resolvedValue as string | number | readonly string[]) ?? '' : userValue}
-          defaultValue={!isFormMode && userValue === undefined ? defaultValue : undefined}
-          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)}
-        />
-        {/*
-         * Suffix slot (Sprint 2 P4.1) — same pattern as prefix,
-         * rendered AFTER the input. Typical use: unit labels (`USD`,
-         * `kg`, `%`), trailing icons, length counters.
-         */}
-        {slotProps?.suffix?.children !== undefined && (
-          <span
-            aria-hidden="true"
-            className={cn(v.suffix(), slotProps.suffix.className)}
-          >
-            {slotProps.suffix.children}
-          </span>
-        )}
-      </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/TextField/textField.types.ts

@@ -1,90 +0,0 @@
-import type { InputHTMLAttributes, ReactNode } from 'react';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { Engine } from '@dashforge/ui-core';
-import type { TextFieldVariants } from './textField.variants.js';
-
-/**
- * Per-slot overrides for `<TextField>`.
- *
- * Each slot accepts `{ className: string }` (and, for `prefix` /
- * `suffix`, a `children` node) so the override path is extensible —
- * extra fields like `style`, `aria-*`, `data-*` can be added without
- * a breaking change. Mirrors the MUI-side `slotProps` shape.
- *
- * **`prefix` / `suffix`** are inline adornments rendered INSIDE the
- * `inputWrapper`, before / after the `<input>` element. Typical use:
- * currency symbols, units, status icons. Passing only `className`
- * (no `children`) is allowed but renders an empty slot — usually
- * you'll always pair the two.
- *
- *   ```tsx
- *   <TextField
- *     name="price"
- *     type="number"
- *     slotProps={{
- *       prefix: { children: '$' },
- *       suffix: { children: 'USD' },
- *     }}
- *   />
- *   ```
- */
-export interface TextFieldSlotProps {
-  root?: { className?: string };
-  label?: { className?: string };
-  requiredMark?: { className?: string };
-  inputWrapper?: { className?: string };
-  input?: { className?: string };
-  helperText?: { className?: string };
-  errorText?: { className?: string };
-  prefix?: { children?: ReactNode; className?: string };
-  suffix?: { children?: ReactNode; className?: string };
-}
-
-/**
- * Props for the Dashforge TW `<TextField>`.
- *
- * Extends the native `<input>` attributes (so `placeholder`, `type`,
- * `autoComplete`, `aria-*` etc. all flow through), narrowed in two
- * places:
- *
- *   - `size` is omitted because HTML's legacy `size` attribute (number)
- *     collides with our variant axis (`'sm' | 'md' | 'lg'`).
- *   - `className` is omitted — use `sx` instead (the canonical override
- *     path that wins over variant classes via `tailwind-merge`).
- *
- * Plus the variant axes and Dashforge form-bridge wiring (`name`,
- * `rules`, `visibleWhen`, `access`).
- */
-export interface TextFieldProps
-  extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'className'>,
-    Pick<TextFieldVariants, 'size' | 'layout' | 'fullWidth'> {
-  /** Bridge field name (required when used inside `DashFormProvider`). */
-  name: string;
-
-  /** Visible label. */
-  label?: ReactNode;
-
-  /** Forwarded to the bridge as RHF rules — opaque to this component. */
-  rules?: unknown;
-
-  /** Engine predicate. Component returns null when false. */
-  visibleWhen?: (engine: Engine) => boolean;
-
-  /** Helper line below the input. */
-  helperText?: ReactNode;
-
-  /** Explicit error semaphore. Overrides bridge auto-error. */
-  error?: boolean;
-
-  /** Render the asterisk + set the native `required` attribute. */
-  required?: boolean;
-
-  /** RBAC requirement. */
-  access?: AccessRequirement;
-
-  /** Root-level Tailwind override — wins over variant classes via `cn()`. */
-  sx?: string;
-
-  /** Per-slot overrides — see `TextFieldSlotProps`. */
-  slotProps?: TextFieldSlotProps;
-}

package/src/components/TextField/textField.variants.ts

@@ -1,105 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<TextField>` with 7 slots.
- *
- * The MUI-side `TextField` supports three layout modes (floating /
- * stacked / inline) plus a Select-integration hook. The TW-side
- * port covers **stacked** + **inline** in F3 (label outside the
- * input wrapper) and ships a CSS-only floating label using
- * Tailwind's `peer` modifier.
- *
- * The Select integration (`__selectAvailableValues` etc.) is
- * deferred to F4 when the dedicated `<Select>` component arrives.
- */
-export const textFieldVariants = 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: #fafafa in light,
-      // #0a0a0a in dark. Same class, dark-mode aware automatically.
-      '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',
-    ],
-    helperText: 'mt-1 text-sm text-neutral-600',
-    errorText: 'mt-1 text-sm text-danger-600',
-    /*
-     * `prefix` / `suffix` slot — inline adornment rendered before /
-     * after the input INSIDE the inputWrapper. `shrink-0` keeps the
-     * adornment width fixed so it doesn't compete for space with the
-     * input; `select-none` + `pointer-events-none` avoids
-     * accidentally stealing focus from the input on click (the
-     * inputWrapper handles focus via `focus-within`).
-     */
-    prefix: [
-      'shrink-0 inline-flex items-center select-none pointer-events-none',
-      'text-neutral-500',
-      'mr-2',
-    ],
-    suffix: [
-      'shrink-0 inline-flex items-center select-none pointer-events-none',
-      'text-neutral-500',
-      'ml-2',
-    ],
-  },
-  variants: {
-    size: {
-      sm: {
-        inputWrapper: 'h-8 px-2',
-        input: 'text-sm',
-      },
-      md: {
-        inputWrapper: 'h-10 px-3',
-        input: 'text-base',
-      },
-      lg: {
-        inputWrapper: 'h-12 px-4',
-        input: 'text-lg',
-      },
-    },
-    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: {
-        // neutral-200 is a darker shade of the default neutral-50 surface
-        // — visually distinguishes the disabled input from the active one
-        // in both light and dark modes.
-        inputWrapper: 'opacity-60 cursor-not-allowed bg-neutral-200',
-      },
-    },
-  },
-  defaultVariants: {
-    size: 'md',
-    layout: 'stacked',
-    error: false,
-    fullWidth: false,
-    disabled: false,
-  },
-});
-
-export type TextFieldVariants = VariantProps<typeof textFieldVariants>;