@dashforge/tw 1.0.0 → 1.1.1

package/src/components/LeftNav/leftNav.types.ts

@@ -1,120 +0,0 @@
-import type {
-  ReactNode,
-  ComponentType,
-  AnchorHTMLAttributes,
-  Ref,
-} from 'react';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { LeftNavVariants } from './leftNav.variants.js';
-
-/**
- * One row in the LeftNav. May be either a clickable item OR a group
- * (a header that owns nested children, optionally collapsible).
- */
-export type LeftNavNode = LeftNavItem | LeftNavGroup;
-
-export interface LeftNavItem {
-  kind?: 'item';
-  /** Stable id used for `activeId` matching + React keys. */
-  id: string;
-  label: ReactNode;
-  icon?: ReactNode;
-  /**
-   * Destination for navigation. Omit for a pure-callback item (use
-   * `onSelect`).
-   */
-  href?: string;
-  /** Fired when the row is clicked (in addition to navigation). */
-  onSelect?: () => void;
-  /** Optional pill / counter rendered to the right of the label. */
-  badge?: ReactNode;
-  /** Per-item disabled flag. */
-  disabled?: boolean;
-  /** RBAC access requirement — hides / disables the row. */
-  access?: AccessRequirement;
-}
-
-export interface LeftNavGroup {
-  kind: 'group';
-  id: string;
-  label: ReactNode;
-  icon?: ReactNode;
-  children: LeftNavItem[];
-  /**
-   * Initial expanded state when used in uncontrolled mode. Default
-   * `true` (groups open by default — most app navs want immediate
-   * visibility).
-   */
-  defaultExpanded?: boolean;
-  /** Controlled expanded state. Provide `onExpandedChange` to update. */
-  expanded?: boolean;
-  /** RBAC access requirement — hides / disables the whole group. */
-  access?: AccessRequirement;
-}
-
-/**
- * Polymorphic link component prop. Defaults to `<a>`. Pass a
- * router-aware component (react-router `Link`, Next `Link`) for SPA
- * navigation.
- */
-export type LeftNavLinkComponent = ComponentType<
-  AnchorHTMLAttributes<HTMLAnchorElement> & {
-    ref?: Ref<HTMLAnchorElement>;
-  }
->;
-
-export interface LeftNavSlotProps {
-  root?: { className?: string };
-  brand?: { className?: string };
-  list?: { className?: string };
-  item?: { className?: string };
-  itemLink?: { className?: string };
-  itemActive?: { className?: string };
-  itemIcon?: { className?: string };
-  itemLabel?: { className?: string };
-  itemBadge?: { className?: string };
-  group?: { className?: string };
-  groupHeader?: { className?: string };
-  groupChildren?: { className?: string };
-  footer?: { className?: string };
-  collapseToggle?: { className?: string };
-}
-
-/**
- * Props for `<LeftNav>`.
- *
- * Router-agnostic sidebar navigation. The consumer drives the active
- * item via `activeId` (typically derived from the current route).
- *
- * Rail / drawer responsive behaviour is handled by `<AppShell>`; this
- * component renders the actual nav content and exposes a `collapsed`
- * prop for the icon-only "rail" rendering.
- */
-export interface LeftNavProps extends LeftNavVariants {
-  items: LeftNavNode[];
-  /** Currently-active item id (highlight + `aria-current="page"`). */
-  activeId?: string;
-  /**
-   * Icon-only rail mode. When `true`, labels and group children are
-   * visually hidden (kept for screen readers via `sr-only`).
-   */
-  collapsed?: boolean;
-  /** Fired when the user clicks the collapse-toggle button. */
-  onCollapseChange?: (collapsed: boolean) => void;
-  /** Fired when a group's expanded state changes (controlled or not). */
-  onGroupExpandedChange?: (groupId: string, expanded: boolean) => void;
-  /** Brand / logo node rendered at the top. */
-  brand?: ReactNode;
-  /** Footer node (e.g., user badge). */
-  footer?: ReactNode;
-  /** Override the link component. @default 'a' */
-  linkComponent?: LeftNavLinkComponent;
-  /** Visible label of the nav landmark. @default 'Main navigation' */
-  ariaLabel?: string;
-  /** Root className shortcut. */
-  sx?: string;
-  /** Per-slot className overrides. */
-  slotProps?: LeftNavSlotProps;
-  /** Show / hide the collapse toggle button. @default true */
-  showCollapseToggle?: boolean;
-}

package/src/components/LeftNav/leftNav.variants.ts

@@ -1,107 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<LeftNav>`.
- *
- * Slots:
- *   - `root`           — `<nav>` landmark
- *   - `brand`          — top brand/logo wrapper
- *   - `list`           — `<ul>` containing items & groups
- *   - `item`           — `<li>` wrapper
- *   - `itemLink`       — clickable row (`<a>` or `<button>`)
- *   - `itemActive`     — active state on the row
- *   - `itemIcon`       — icon slot inside a row
- *   - `itemLabel`      — text label slot
- *   - `itemBadge`      — right-aligned pill
- *   - `group`          — wrapper around a group header + children
- *   - `groupHeader`    — clickable header row (`<button>`)
- *   - `groupChildren`  — `<ul>` containing the group's items
- *   - `footer`         — bottom slot (user badge, etc.)
- *   - `collapseToggle` — rail-mode toggle button
- */
-export const leftNavVariants = tv({
-  slots: {
-    root: [
-      'flex flex-col h-full',
-      'bg-neutral-50 border-r border-neutral-200',
-      // Width transition (rail-mode toggle) — gated on
-      // prefers-reduced-motion (WCAG 2.3.3). The new width still
-      // applies, just without the animated tween.
-      'transition-[width] duration-200 motion-reduce:transition-none motion-reduce:duration-0',
-    ],
-    brand: [
-      'flex items-center gap-2 px-3 h-14 shrink-0',
-      'border-b border-neutral-200 text-neutral-900 font-semibold',
-    ],
-    list: 'flex flex-col gap-0.5 p-2 flex-1 overflow-y-auto',
-    item: 'list-none',
-    itemLink: [
-      'flex items-center gap-2 px-2 py-2 rounded-md',
-      'text-sm text-neutral-700 hover:bg-neutral-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors w-full',
-      'aria-disabled:opacity-50 aria-disabled:cursor-not-allowed',
-      'aria-disabled:hover:bg-transparent',
-      // Defensive `no-underline` — Tailwind's preflight removes the
-      // default browser anchor underline globally, but environments
-      // that DISABLE preflight (e.g. our docs-lab, where the tw
-      // section coexists with MUI's chrome) get raw browser defaults
-      // back. Without this, `<a>` items in the nav render underlined
-      // in those contexts. Explicit `no-underline` + `hover:no-underline`
-      // keeps the appearance consistent regardless of preflight state.
-      'no-underline hover:no-underline',
-    ],
-    itemActive: 'bg-primary-100 text-primary-900 font-medium',
-    itemIcon: 'shrink-0 w-5 h-5 flex items-center justify-center',
-    itemLabel: 'truncate flex-1 min-w-0 text-left',
-    itemBadge: [
-      'shrink-0 inline-flex items-center justify-center',
-      'px-1.5 h-5 rounded-full text-[10px] font-medium',
-      'bg-neutral-200 text-neutral-800',
-    ],
-    group: 'flex flex-col gap-0.5',
-    groupHeader: [
-      'flex items-center gap-2 px-2 py-2 rounded-md',
-      'text-sm font-medium text-neutral-900 hover:bg-neutral-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors w-full',
-    ],
-    groupChildren: 'flex flex-col gap-0.5 pl-6',
-    footer: [
-      'border-t border-neutral-200 p-3 shrink-0',
-      'flex items-center gap-2',
-    ],
-    collapseToggle: [
-      'inline-flex items-center justify-center w-8 h-8 shrink-0',
-      'rounded-md text-neutral-600 hover:bg-neutral-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors',
-    ],
-  },
-  variants: {
-    width: {
-      sm: { root: 'w-48' },
-      md: { root: 'w-60' },
-      lg: { root: 'w-72' },
-    },
-    collapsed: {
-      true: {
-        root: 'w-14',
-        brand: 'justify-center px-0',
-        list: 'p-1 items-center',
-        itemLink: 'justify-center px-0 py-2.5',
-        itemLabel: 'sr-only',
-        itemBadge: 'hidden',
-        groupHeader: 'justify-center px-0',
-        groupChildren: 'hidden',
-        footer: 'justify-center px-0',
-      },
-    },
-  },
-  defaultVariants: {
-    width: 'md',
-    collapsed: false,
-  },
-});
-
-export type LeftNavVariants = VariantProps<typeof leftNavVariants>;

package/src/components/NumberField/NumberField.test.tsx

@@ -1,83 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/react';
-import { DashFormProvider } from '@dashforge/forms';
-import { NumberField } from './NumberField.js';
-
-describe('<NumberField>', () => {
-  describe('standalone (no DashForm)', () => {
-    it('renders a numeric input with the label', () => {
-      render(<NumberField name="age" label="Age" />);
-      const el = screen.getByLabelText('Age') as HTMLInputElement;
-      expect(el).toBeInstanceOf(HTMLInputElement);
-      expect(el.type).toBe('number');
-    });
-
-    it('respects `min` / `max` / `step` attributes', () => {
-      render(
-        <NumberField name="qty" label="Qty" min={1} max={10} step={2} />
-      );
-      const el = screen.getByLabelText('Qty');
-      expect(el.getAttribute('min')).toBe('1');
-      expect(el.getAttribute('max')).toBe('10');
-      expect(el.getAttribute('step')).toBe('2');
-    });
-
-    it('displays a controlled numeric value via `value`', () => {
-      const { rerender } = render(
-        <NumberField name="qty" label="Qty" value={5} onChange={() => undefined} />
-      );
-      expect((screen.getByLabelText('Qty') as HTMLInputElement).value).toBe('5');
-      rerender(
-        <NumberField name="qty" label="Qty" value={null} onChange={() => undefined} />
-      );
-      expect((screen.getByLabelText('Qty') as HTMLInputElement).value).toBe('');
-    });
-
-    it('renders a `*` for required fields', () => {
-      render(<NumberField name="x" label="X" required />);
-      expect(screen.getByText('*')).toBeTruthy();
-    });
-
-    it('does NOT render a stepper unless `showStepper` is set', () => {
-      render(<NumberField name="x" label="X" />);
-      expect(screen.queryByLabelText('Increment')).toBeNull();
-      expect(screen.queryByLabelText('Decrement')).toBeNull();
-    });
-
-    it('renders +/- stepper buttons when `showStepper` is true', () => {
-      render(<NumberField name="x" label="X" showStepper />);
-      expect(screen.getByLabelText('Increment')).toBeTruthy();
-      expect(screen.getByLabelText('Decrement')).toBeTruthy();
-    });
-  });
-
-  describe('inside DashFormProvider', () => {
-    it('mounts cleanly inside a bridge-providing tree', () => {
-      render(
-        <DashFormProvider defaultValues={{ age: 30 }}>
-          <NumberField name="age" label="Age" />
-        </DashFormProvider>
-      );
-      // Bridge mode mounts cleanly with no console errors. Initial-value
-      // reflection in the input is timing-sensitive (RHF's defaultValues
-      // commit happens after the first render); the actual end-to-end
-      // round-trip is verified in the dash smoke page where async
-      // RHF state has time to settle.
-      expect(screen.getByLabelText('Age')).toBeInstanceOf(HTMLInputElement);
-    });
-
-    it('stepper buttons render and are clickable inside the bridge tree', () => {
-      render(
-        <DashFormProvider defaultValues={{ qty: 5 }}>
-          <NumberField name="qty" label="Qty" showStepper step={3} />
-        </DashFormProvider>
-      );
-      // The stepper itself renders correctly; the bridge round-trip on
-      // click is covered by the smoke test in dash.
-      const inc = screen.getByLabelText('Increment') as HTMLButtonElement;
-      expect(inc.disabled).toBe(false);
-      fireEvent.click(inc); // should not throw
-    });
-  });
-});

package/src/components/NumberField/NumberField.tsx

@@ -1,321 +0,0 @@
-import { useCallback, 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 { 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();
-
-  /*
-   * Local state for the STANDALONE UNCONTROLLED case (no bridge, no
-   * `value` prop, only `defaultValue`). Mirrors OTPField. Without this,
-   * `resolvedDisplayValue` would be a snapshot computed ONCE from
-   * `defaultValue` and the controlled `<input value={...}>` would
-   * snap user input back on every keystroke / stepper click — same
-   * trap that hit Checkbox + RadioGroup in this package.
-   *
-   * In form mode the bridge owns state. In standalone CONTROLLED mode
-   * (consumer passes `value`) the consumer owns state. Only this
-   * branch needs the local hook.
-   */
-  const [uncontrolledValue, setUncontrolledValue] = useState<string>(() =>
-    formatForDisplay(defaultValue)
-  );
-  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)
-        : uncontrolledValue;
-  }
-
-  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);
-    }
-    // Standalone uncontrolled mode: mirror the raw input string so the
-    // controlled `<input value={...}>` reflects what the user typed.
-    // Partial states (e.g. "-", "1.") are kept verbatim — `parseFromInput`
-    // returns `undefined` for them so `writeToBridge` is a no-op above.
-    if (!isFormMode && userValue === undefined) {
-      setUncontrolledValue(e.target.value);
-    }
-    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);
-    // Standalone uncontrolled: also persist the new value to local
-    // state so the visible display tracks the stepper click.
-    if (!isFormMode && userValue === undefined) {
-      setUncontrolledValue(formatForDisplay(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>
-  );
-}