@dashforge/tw 1.1.0 → 1.2.0

package/src/components/Autocomplete/autocomplete.types.ts

@@ -1,198 +0,0 @@
-import type { ReactNode } from 'react';
-import type { Engine } from '@dashforge/ui-core';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { AutocompleteVariants } from './autocomplete.variants.js';
-
-/**
- * Default `{ value, label, disabled? }` option shape.
- *
- * The simplest shape and the one used by the component when no
- * `getOptionValue` / `getOptionLabel` props are provided. For richer
- * option shapes (e.g., `{ id, name, country, ... }`) make the component
- * generic by passing `<TOption>` and providing the accessors:
- *
- * ```tsx
- * type User = { id: string; name: string; admin?: boolean };
- *
- * <Autocomplete<User>
- *   name="owner"
- *   options={users}
- *   getOptionValue={(u) => u.id}
- *   getOptionLabel={(u) => u.name}
- *   getOptionDisabled={(u) => !u.admin}
- * />
- * ```
- */
-export interface AutocompleteOption {
-  /** Value persisted on the form. */
-  value: string;
-  /** Display label (string or any React node). */
-  label: ReactNode;
-  /** Per-option explicit disable. */
-  disabled?: boolean;
-}
-
-export interface AutocompleteSlotProps {
-  root?: { className?: string };
-  label?: { className?: string };
-  requiredMark?: { className?: string };
-  inputWrapper?: { className?: string };
-  input?: { className?: string };
-  trigger?: { className?: string };
-  clearButton?: { className?: string };
-  popover?: { className?: string };
-  listBox?: { className?: string };
-  listItem?: { className?: string };
-  emptyState?: { className?: string };
-  helperText?: { className?: string };
-  errorText?: { className?: string };
-  /** Wrapper around the chip list (multi-select only). */
-  chipsList?: { className?: string };
-  /** Individual chip displayed in multi-select. */
-  chip?: { className?: string };
-  /** `×` button on a chip. */
-  chipRemove?: { className?: string };
-}
-
-/**
- * Union of the value shapes `<Autocomplete>` accepts.
- *
- * - **Single-select (default)**: `string | null`
- * - **Multi-select** (`multiple` prop): `string[] | null`
- *
- * `null` means "no selection" in both modes — a multi-select with no
- * picks emits an empty array on first commit, then keeps emitting arrays.
- */
-export type AutocompleteValue = string | string[] | null;
-
-/**
- * Props for `<Autocomplete>`.
- *
- * Bridge-integrated single-select combobox with full ARIA combobox
- * a11y, keyboard navigation, and Form Closure v1 error gating.
- *
- * Mirrors the MUI-side `@dashforge/ui/Autocomplete` at the bridge
- * level — same `name` / `rules` / `visibleWhen` / `access` semantics,
- * same StrictMode-safe unregister-on-unmount.
- *
- * @typeParam TOption  Shape of an option. Defaults to
- *                     `AutocompleteOption` (`{ value, label, disabled? }`).
- *                     Pass `<TOption>` + `getOptionValue` / `getOptionLabel`
- *                     for arbitrary domain types.
- */
-export interface AutocompleteProps<TOption = AutocompleteOption>
-  extends AutocompleteVariants {
-  name: string;
-  rules?: unknown;
-  options: TOption[];
-  label?: ReactNode;
-  helperText?: ReactNode;
-  required?: boolean;
-  error?: boolean;
-  disabled?: boolean;
-  /** Placeholder shown when the input is empty. */
-  placeholder?: string;
-  /** Engine predicate — field not rendered when it returns `false`. */
-  visibleWhen?: (engine: Engine) => boolean;
-  /** RBAC access requirement. */
-  access?: AccessRequirement;
-  /** Root className shortcut. */
-  sx?: string;
-  /** Per-slot className overrides. */
-  slotProps?: AutocompleteSlotProps;
-  /** Controlled value (form mode reads from the bridge if omitted). */
-  value?: AutocompleteValue;
-  /** Default value for uncontrolled mode (no-op in form mode). */
-  defaultValue?: AutocompleteValue;
-  /** Fires when the user picks an option (after bridge update in form mode). */
-  onValueChange?: (value: AutocompleteValue) => void;
-  /** Fallback text when no option matches the typed filter. */
-  emptyMessage?: string;
-
-  // ───── F5-A-bis: multi-select ─────
-
-  /**
-   * Multi-select mode. When `true`:
-   *
-   * - `value` / `defaultValue` accept `string[]` (or `null`).
-   * - Picks are toggled rather than replaced; the popover stays open.
-   * - Selected items render as chips inside the input wrapper.
-   * - Backspace at the start of an empty input removes the last chip.
-   * - The clear button (`×`) clears the entire selection.
-   */
-  multiple?: boolean;
-
-  // ───── F5-A-bis: free-solo ─────
-
-  /**
-   * Allow committing arbitrary strings (not just option values).
-   *
-   * When `true`:
-   *   - **Enter** commits the typed text as the value when no option
-   *     row is highlighted (or no rows match the filter).
-   *   - **Blur** commits the typed text the same way, unless the text
-   *     exactly matches an existing option's label (in which case the
-   *     option's value snaps in).
-   *   - In multi mode, each free-solo commit adds a new chip whose key
-   *     and label are the typed string.
-   *
-   * Free-solo is independent of `multiple` — works in both modes.
-   */
-  freeSolo?: boolean;
-
-  // ───── F5-A-bis: async runtime options ─────
-
-  /**
-   * Async option loader. Called (debounced by `loadDebounceMs`) every
-   * time the user types in the input. Results replace the static
-   * `options` prop while the user is actively filtering.
-   *
-   * Return a promise that resolves with the new option list. Reject /
-   * throw to surface a generic empty state.
-   *
-   * @example
-   * ```tsx
-   * <Autocomplete
-   *   name="user"
-   *   options={[]}
-   *   loadOptions={async (q) => {
-   *     const res = await fetch(`/api/users?q=${q}`);
-   *     return res.ok ? res.json() : [];
-   *   }}
-   * />
-   * ```
-   */
-  loadOptions?: (query: string) => Promise<TOption[]>;
-  /**
-   * Debounce window (ms) for `loadOptions`. The loader fires after the
-   * user stops typing for this long.
-   * @default 250
-   */
-  loadDebounceMs?: number;
-  /** Text displayed in the popover while a fetch is in flight. */
-  loadingMessage?: ReactNode;
-
-  // ───── Generic option accessors (F5-A-bis) ─────
-
-  /**
-   * Extract the persistable value (string) from an option.
-   * @default `(o) => (o as AutocompleteOption).value`
-   */
-  getOptionValue?: (option: TOption) => string;
-  /**
-   * Extract the display label from an option.
-   * @default `(o) => (o as AutocompleteOption).label`
-   */
-  getOptionLabel?: (option: TOption) => ReactNode;
-  /**
-   * Per-option disabled flag.
-   * @default `(o) => Boolean((o as AutocompleteOption).disabled)`
-   */
-  getOptionDisabled?: (option: TOption) => boolean;
-  /**
-   * Unique React key for an option. Defaults to `getOptionValue`.
-   * Override if your `value` strings can collide across distinct
-   * option records (rare).
-   */
-  getOptionKey?: (option: TOption) => string;
-}

package/src/components/Autocomplete/autocomplete.variants.ts

@@ -1,141 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<Autocomplete>` with slots.
- *
- * Slots:
- *   - `root`         — outer wrapper (label + combobox + helper/error)
- *   - `label`        — text label above the input
- *   - `requiredMark` — red `*` for required fields
- *   - `inputWrapper` — surface holding the input + clear/trigger buttons
- *   - `input`        — the typeable text input
- *   - `trigger`      — caret / chevron button that opens the popover
- *   - `clearButton`  — `×` button to clear the current selection
- *   - `popover`      — floating panel containing the option list
- *   - `listBox`      — list element wrapping the options
- *   - `listItem`     — single option row
- *   - `emptyState`   — fallback when no options match the filter
- *   - `helperText`   — descriptive line below the input
- *   - `errorText`    — semantic counterpart for error mode
- *   - `chipsList`    — wrapper around selected chips (multi-select only)
- *   - `chip`         — individual selected chip
- *   - `chipRemove`   — `×` button on a chip
- */
-export const autocompleteVariants = 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',
-      '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',
-    ],
-    trigger: [
-      'flex items-center justify-center shrink-0 px-2',
-      'text-neutral-600 hover:text-neutral-900',
-      'disabled:cursor-not-allowed disabled:opacity-40',
-      'transition-colors',
-      // Chevron flip on open — targets the SVG child via the aria-
-      // expanded state on the button itself (set by React). Smooth
-      // rotate gated on prefers-reduced-motion (WCAG 2.3.3); the
-      // 180° state still applies, just without the animated tween.
-      '[&[aria-expanded=true]>svg]:rotate-180',
-      '[&>svg]:transition-transform [&>svg]:duration-150 motion-reduce:[&>svg]:transition-none',
-    ],
-    clearButton: [
-      'flex items-center justify-center shrink-0 px-2',
-      'text-neutral-500 hover:text-neutral-900',
-      'transition-colors',
-    ],
-    popover: [
-      'z-50 mt-1 max-h-64 overflow-auto',
-      'rounded-md border bg-neutral-50 border-neutral-300 shadow-lg',
-      'min-w-[var(--trigger-width)]',
-    ],
-    listBox: 'outline-none py-1 list-none pl-0 m-0',
-    listItem: [
-      'cursor-pointer select-none px-3 py-2 text-sm text-neutral-900',
-      'outline-none',
-      'data-[focused]:bg-primary-50 data-[focused]:text-primary-900',
-      'data-[selected]:bg-primary-100 data-[selected]:text-primary-900 data-[selected]:font-medium',
-      'data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed',
-    ],
-    emptyState: 'px-3 py-2 text-sm text-neutral-500',
-    helperText: 'mt-1 text-sm text-neutral-600',
-    errorText: 'mt-1 text-sm text-danger-600',
-    chipsList: 'flex flex-wrap items-center gap-1 px-1 py-1',
-    chip: [
-      'inline-flex items-center gap-1 shrink-0',
-      'rounded-md bg-primary-100 text-primary-900',
-      'px-2 py-0.5 text-xs font-medium',
-      'border border-primary-200',
-    ],
-    chipRemove: [
-      'inline-flex items-center justify-center',
-      'rounded-sm w-4 h-4 text-primary-700',
-      'hover:bg-primary-200 hover:text-primary-900',
-      'transition-colors',
-    ],
-  },
-  variants: {
-    size: {
-      sm: {
-        inputWrapper: 'h-8',
-        input: 'text-sm px-2',
-        trigger: 'h-8 text-xs',
-        clearButton: 'h-8',
-      },
-      md: {
-        inputWrapper: 'h-10',
-        input: 'text-base px-3',
-        trigger: 'h-10 text-sm',
-        clearButton: 'h-10',
-      },
-      lg: {
-        inputWrapper: 'h-12',
-        input: 'text-lg px-4',
-        trigger: 'h-12 text-base',
-        clearButton: 'h-12',
-      },
-    },
-    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 AutocompleteVariants = VariantProps<typeof autocompleteVariants>;

package/src/components/Avatar/Avatar.test.tsx

@@ -1,287 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, afterEach } from 'vitest';
-import { fireEvent, render, screen, cleanup } from '@testing-library/react';
-import { Avatar, AvatarGroup } from './Avatar.js';
-
-void React;
-afterEach(() => cleanup());
-
-/**
- * Unit tests for the Avatar family. Covers:
- *   - Image rendering (src + alt)
- *   - Auto-initials from name (1 word, 2 words, edge cases)
- *   - Fallback chain (src fail → initials → custom icon → generic)
- *   - Shape ↔ radius interaction (radius wins when both set)
- *   - Size axis (5 enum values map to spacing classes)
- *   - Color × tone resolution (soft default vs explicit tone)
- *   - AvatarGroup slicing + overflow indicator + size inheritance
- */
-
-describe('<Avatar>', () => {
-  describe('image rendering', () => {
-    it('renders an <img> when src is set', () => {
-      const { container } = render(
-        <Avatar src="/avatar.png" alt="Maya" />
-      );
-      expect(container.querySelector('img')).toBeTruthy();
-    });
-
-    it('applies the alt attribute', () => {
-      render(<Avatar src="/x.png" alt="Maya Rodriguez" />);
-      const img = screen.getByRole('img', { name: /maya rodriguez/i });
-      expect(img).toBeTruthy();
-    });
-
-    it('falls back to initials when the image fails to load', () => {
-      const { container } = render(<Avatar src="/broken.png" name="Maya Rodriguez" />);
-      const img = container.querySelector('img')!;
-      fireEvent.error(img);
-      // After onError the img is gone, initials shown.
-      expect(container.querySelector('img')).toBeNull();
-      expect(screen.getByText('MR')).toBeTruthy();
-    });
-  });
-
-  describe('auto-initials from name', () => {
-    it('extracts MR from "Maya Rodriguez"', () => {
-      render(<Avatar name="Maya Rodriguez" />);
-      expect(screen.getByText('MR')).toBeTruthy();
-    });
-
-    it('extracts C from single-word name "Cher"', () => {
-      render(<Avatar name="Cher" />);
-      expect(screen.getByText('C')).toBeTruthy();
-    });
-
-    it('uppercases the initials', () => {
-      render(<Avatar name="maya rodriguez" />);
-      expect(screen.getByText('MR')).toBeTruthy();
-    });
-
-    it('handles extra whitespace', () => {
-      render(<Avatar name="  Maya   Rodriguez  " />);
-      expect(screen.getByText('MR')).toBeTruthy();
-    });
-
-    it('renders a generic icon when name is empty', () => {
-      const { container } = render(<Avatar name="" />);
-      expect(container.querySelector('svg')).toBeTruthy();
-    });
-
-    it('renders a generic icon when name is omitted entirely', () => {
-      const { container } = render(<Avatar />);
-      expect(container.querySelector('svg')).toBeTruthy();
-    });
-
-    it('renders fallbackIcon over the generic icon when set', () => {
-      render(<Avatar fallbackIcon={<span data-testid="custom-icon">★</span>} />);
-      expect(screen.getByTestId('custom-icon')).toBeTruthy();
-    });
-
-    it('initials win over fallbackIcon when name is present', () => {
-      render(
-        <Avatar
-          name="Maya Rodriguez"
-          fallbackIcon={<span data-testid="custom-icon">★</span>}
-        />
-      );
-      expect(screen.getByText('MR')).toBeTruthy();
-      expect(screen.queryByTestId('custom-icon')).toBeNull();
-    });
-  });
-
-  describe('shape ↔ radius', () => {
-    it('default shape=circle → rounded-full', () => {
-      const { container } = render(<Avatar name="x" />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('rounded-full');
-    });
-
-    it('shape="rounded" → rounded-lg', () => {
-      const { container } = render(<Avatar name="x" shape="rounded" />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('rounded-lg');
-    });
-
-    it('shape="square" → rounded-none', () => {
-      const { container } = render(<Avatar name="x" shape="square" />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('rounded-none');
-    });
-
-    it('explicit radius wins over shape', () => {
-      const { container } = render(
-        <Avatar name="x" shape="circle" radius="md" />
-      );
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('rounded-md');
-      expect(root.className).not.toContain('rounded-full');
-    });
-  });
-
-  describe('size axis', () => {
-    it.each([
-      ['xs', 'w-5'],
-      ['sm', 'w-7'],
-      ['md', 'w-9'],
-      ['lg', 'w-12'],
-      ['xl', 'w-16'],
-    ] as const)('size=%s → %s', (size, expected) => {
-      const { container } = render(<Avatar name="x" size={size} />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain(expected);
-    });
-  });
-
-  describe('color × tone resolution', () => {
-    it('default color=neutral + no tone → bg-neutral-100', () => {
-      const { container } = render(<Avatar name="x" />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('bg-neutral-100');
-    });
-
-    it('color=primary + no tone → soft default bg-primary-100', () => {
-      const { container } = render(<Avatar name="x" color="primary" />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('bg-primary-100');
-    });
-
-    it('color=success + tone=500 → bg-success-500 text-success-50', () => {
-      const { container } = render(<Avatar name="x" color="success" tone={500} />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('bg-success-500');
-      expect(root.className).toContain('text-success-50');
-    });
-
-    it('color=danger + tone=700 → bg-danger-700 text-danger-50', () => {
-      const { container } = render(<Avatar name="x" color="danger" tone={700} />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('bg-danger-700');
-    });
-
-    it('color=warning + tone=50 → bg-warning-50 text-warning-900 (dark text)', () => {
-      const { container } = render(<Avatar name="x" color="warning" tone={50} />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('bg-warning-50');
-      expect(root.className).toContain('text-warning-900');
-    });
-
-    it('color classes are NOT applied when image loads', () => {
-      const { container } = render(<Avatar src="/x.png" alt="x" color="primary" />);
-      const root = container.firstElementChild!;
-      // Image surface — no fallback bg paint underneath (transparent
-      // PNGs would peek through otherwise).
-      expect(root.className).not.toContain('bg-primary-100');
-    });
-  });
-
-  describe('overrides', () => {
-    it('appends sx to the root', () => {
-      const { container } = render(<Avatar name="x" sx="ring-4 ring-purple-500" />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('ring-purple-500');
-    });
-
-    it('appends className to the root', () => {
-      const { container } = render(<Avatar name="x" className="my-custom" />);
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('my-custom');
-    });
-  });
-});
-
-describe('<AvatarGroup>', () => {
-  it('renders all children when total ≤ max', () => {
-    const { container } = render(
-      <AvatarGroup max={5}>
-        <Avatar name="A" />
-        <Avatar name="B" />
-        <Avatar name="C" />
-      </AvatarGroup>
-    );
-    // 3 avatars rendered, no overflow indicator
-    const avatars = container.querySelectorAll('[role="img"]');
-    expect(avatars.length).toBe(3);
-  });
-
-  it('slices to max and renders overflow indicator', () => {
-    const { container } = render(
-      <AvatarGroup max={3}>
-        <Avatar name="A" />
-        <Avatar name="B" />
-        <Avatar name="C" />
-        <Avatar name="D" />
-        <Avatar name="E" />
-      </AvatarGroup>
-    );
-    // 3 visible + 1 overflow indicator
-    const avatars = container.querySelectorAll('[role="img"]');
-    expect(avatars.length).toBe(4);
-    expect(screen.getByText('+2')).toBeTruthy();
-  });
-
-  it('default max=4 — 5th avatar collapses', () => {
-    render(
-      <AvatarGroup>
-        <Avatar name="A" />
-        <Avatar name="B" />
-        <Avatar name="C" />
-        <Avatar name="D" />
-        <Avatar name="E" />
-      </AvatarGroup>
-    );
-    expect(screen.getByText('+1')).toBeTruthy();
-  });
-
-  it('applies negative spacing class to the wrapper', () => {
-    const { container } = render(
-      <AvatarGroup spacing="md">
-        <Avatar name="A" />
-        <Avatar name="B" />
-      </AvatarGroup>
-    );
-    const wrapper = container.firstElementChild!;
-    expect(wrapper.className).toContain('-space-x-3');
-  });
-
-  it('propagates size to children when they do not override', () => {
-    const { container } = render(
-      <AvatarGroup size="xl">
-        <Avatar name="A" />
-        <Avatar name="B" size="sm" />
-      </AvatarGroup>
-    );
-    const avatars = container.querySelectorAll('[role="img"]');
-    // First child inherits xl
-    expect(avatars[0]!.className).toContain('w-16');
-    // Second child preserves sm
-    expect(avatars[1]!.className).toContain('w-7');
-  });
-
-  it('applies ring-2 halo when withRing=true (default)', () => {
-    const { container } = render(
-      <AvatarGroup>
-        <Avatar name="A" />
-        <Avatar name="B" />
-      </AvatarGroup>
-    );
-    const avatars = container.querySelectorAll('[role="img"]');
-    expect(avatars[0]!.className).toContain('ring-2');
-    // Ring uses the auto-inverting neutral-50 token (NOT
-    // `ring-white dark:ring-neutral-N` — that would violate the
-    // theme-identity rule for the neutral palette).
-    expect(avatars[0]!.className).toContain('ring-neutral-50');
-  });
-
-  it('omits ring when withRing=false', () => {
-    const { container } = render(
-      <AvatarGroup withRing={false}>
-        <Avatar name="A" />
-        <Avatar name="B" />
-      </AvatarGroup>
-    );
-    const avatars = container.querySelectorAll('[role="img"]');
-    expect(avatars[0]!.className).not.toContain('ring-2');
-  });
-});