@dashforge/tw 0.1.0-beta → 0.2.0-beta

package/src/components/VisuallyHidden/VisuallyHidden.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { VisuallyHidden } from './VisuallyHidden.js';
+
+describe('<VisuallyHidden>', () => {
+  it('renders a <span> by default', () => {
+    const { container } = render(<VisuallyHidden>label</VisuallyHidden>);
+    expect(container.firstElementChild?.tagName).toBe('SPAN');
+  });
+
+  it('has the sr-only class', () => {
+    const { container } = render(<VisuallyHidden>label</VisuallyHidden>);
+    expect(container.firstElementChild?.className).toContain('sr-only');
+  });
+
+  it('preserves the text content (so screen readers can read it)', () => {
+    const { container } = render(<VisuallyHidden>Close dialog</VisuallyHidden>);
+    expect(container.firstElementChild?.textContent).toBe('Close dialog');
+  });
+
+  it('as="div" renders <div>', () => {
+    const { container } = render(<VisuallyHidden as="div">label</VisuallyHidden>);
+    expect(container.firstElementChild?.tagName).toBe('DIV');
+  });
+
+  it('sx adds utilities (merged with sr-only)', () => {
+    const { container } = render(
+      <VisuallyHidden sx="text-xs">label</VisuallyHidden>,
+    );
+    const cls = container.firstElementChild?.className ?? '';
+    expect(cls).toContain('sr-only');
+    expect(cls).toContain('text-xs');
+  });
+
+  it('forwards data-* + aria-*', () => {
+    const { container } = render(
+      <VisuallyHidden data-testid="vh" aria-live="polite">x</VisuallyHidden>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.getAttribute('data-testid')).toBe('vh');
+    expect(el?.getAttribute('aria-live')).toBe('polite');
+  });
+
+  it('typical pattern — icon button label', () => {
+    const { container } = render(
+      <button type="button">
+        <span aria-hidden="true">✕</span>
+        <VisuallyHidden>Close</VisuallyHidden>
+      </button>,
+    );
+    const btn = container.querySelector('button');
+    // textContent includes the hidden label so AT can read it
+    expect(btn?.textContent).toBe('✕Close');
+    // visually, the Close span has sr-only
+    const hidden = btn?.querySelector('.sr-only');
+    expect(hidden?.textContent).toBe('Close');
+  });
+
+  // ─── F11-bis edge cases ─────────────────────────────────────────────
+  it('empty children renders empty element with sr-only', () => {
+    const { container } = render(<VisuallyHidden>{''}</VisuallyHidden>);
+    const el = container.firstElementChild;
+    expect(el?.className).toContain('sr-only');
+    expect(el?.textContent).toBe('');
+  });
+
+  it('aria-live="polite" pattern for status announcements', () => {
+    const { container } = render(
+      <VisuallyHidden aria-live="polite">Saved successfully</VisuallyHidden>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.getAttribute('aria-live')).toBe('polite');
+    expect(el?.textContent).toBe('Saved successfully');
+  });
+
+  it('as="div" renders block element (consumer choice for block hidden content)', () => {
+    const { container } = render(
+      <VisuallyHidden as="div">
+        Block content hidden from sight but readable by AT
+      </VisuallyHidden>,
+    );
+    expect(container.firstElementChild?.tagName).toBe('DIV');
+    expect(container.firstElementChild?.className).toContain('sr-only');
+  });
+});

package/src/components/VisuallyHidden/VisuallyHidden.tsx

@@ -0,0 +1,59 @@
+import { forwardRef, type ElementType } from 'react';
+import { cn } from '../../utils/cn.js';
+import type { VisuallyHiddenProps } from './visuallyHidden.types.js';
+
+/**
+ * `<VisuallyHidden>` — the accessibility primitive.
+ *
+ * Hides children from sighted users (zero pixels rendered, no layout
+ * impact) while keeping them in the accessibility tree. Screen readers
+ * speak the content; voice control software uses it for click targets;
+ * keyboard users see nothing — same as if it weren't there.
+ *
+ * Implementation: Tailwind's built-in `sr-only` utility, which expands to:
+ *
+ *   .sr-only {
+ *     position: absolute;
+ *     width: 1px;
+ *     height: 1px;
+ *     padding: 0;
+ *     margin: -1px;
+ *     overflow: hidden;
+ *     clip: rect(0,0,0,0);
+ *     white-space: nowrap;
+ *     border-width: 0;
+ *   }
+ *
+ * This is the canonical "visually-hidden but screen-reader-accessible"
+ * pattern, also known as the WebAIM clip technique. Critically:
+ *
+ *   • NOT `display: none` (removes from a11y tree)
+ *   • NOT `visibility: hidden` (also removes from a11y tree)
+ *   • NOT `opacity: 0` (technically still rendered, doesn't help AT)
+ *   • NOT `width/height: 0` (collapses, some AT skips it)
+ *
+ * Default tag is `<span>` (inline) — the 99% case is "label inside a
+ * button or link". For block content, override with `as="div"`, but
+ * be aware nesting block inside inline is invalid HTML.
+ *
+ * The component is intentionally tiny (~30 LoC total): one className,
+ * one tag. The value is the COMPONENT NAME — `<VisuallyHidden>` reads
+ * as an intentional a11y decision in code review, while
+ * `className="sr-only"` looks like a typo or a forgotten utility.
+ */
+export const VisuallyHidden = forwardRef<HTMLElement, VisuallyHiddenProps>(
+  function VisuallyHidden(props, ref) {
+    const { as, sx, children, ...rest } = props;
+
+    const Tag = (as ?? 'span') as ElementType;
+    const classes = cn('sr-only', sx);
+
+    return (
+      <Tag ref={ref as never} className={classes} {...rest}>
+        {children}
+      </Tag>
+    );
+  },
+);
+
+VisuallyHidden.displayName = 'VisuallyHidden';

package/src/components/VisuallyHidden/visuallyHidden.types.ts

@@ -0,0 +1,45 @@
+import type { ElementType, HTMLAttributes, ReactElement } from 'react';
+
+/**
+ * Props for `<VisuallyHidden>` — the a11y primitive.
+ *
+ * Hides content visually (zero pixels rendered) while keeping it
+ * accessible to assistive technology (screen readers, voice control).
+ * The canonical use case: icon-only buttons that need an audible label
+ * for non-visual users.
+ *
+ *   <button>
+ *     <CloseIcon />
+ *     <VisuallyHidden>Close dialog</VisuallyHidden>
+ *   </button>
+ *
+ * Implementation uses Tailwind's `sr-only` utility, which sets
+ * `position: absolute; width: 1px; height: 1px; padding: 0;
+ * margin: -1px; overflow: hidden; clip: rect(0,0,0,0);
+ * white-space: nowrap; border-width: 0;` — the canonical
+ * "visually-hidden but screen-reader-accessible" pattern. Better
+ * than `display: none` (removes from a11y tree) and better than
+ * `visibility: hidden` (also removes from a11y tree).
+ */
+export interface VisuallyHiddenProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'className'> {
+  /**
+   * The text or markup hidden from sighted users but read by AT.
+   * Most often a string label.
+   */
+  children?: ReactElement | string | number;
+
+  /**
+   * Override the rendered HTML tag. Defaults to `'span'` — inline
+   * placement is the most common case (label inside a button or link).
+   * Use `as="div"` when the hidden content is block-level, but be
+   * aware: nesting a block inside an inline parent is invalid HTML.
+   */
+  as?: ElementType;
+
+  /**
+   * Utility classes appended to `sr-only`. RARELY needed for this
+   * primitive (it's just hidden text) — kept for API parity.
+   */
+  sx?: string;
+}

package/src/index.ts

@@ -174,6 +174,55 @@ export type {
 } from './components/Snackbar/snackbar.types.js';
 export { snackbarVariants } from './components/Snackbar/snackbar.variants.js';
 
+// F9 foundation: typography + layout primitives. These sit BENEATH
+// every other component (Button's label, TextField's helper text, the
+// surface of an AppShell card) and are what app-level code reaches for
+// before it reaches for any specific UI atom.
+
+export { Typography } from './components/Typography/Typography.js';
+export type { TypographyProps } from './components/Typography/typography.types.js';
+export { typographyVariants } from './components/Typography/typography.variants.js';
+
+export { Box } from './components/Box/Box.js';
+export type { BoxProps } from './components/Box/box.types.js';
+export { boxVariants } from './components/Box/box.variants.js';
+
+export { Stack } from './components/Stack/Stack.js';
+export type { StackProps } from './components/Stack/stack.types.js';
+export { stackVariants } from './components/Stack/stack.variants.js';
+
+export { Grid } from './components/Grid/Grid.js';
+export type {
+  GridProps,
+  GridContainerProps,
+  GridItemProps,
+  ColSpan,
+  GridSpacingStep,
+} from './components/Grid/grid.types.js';
+export { gridVariants } from './components/Grid/grid.variants.js';
+
+// F10 foundation completions: Container, Divider, AspectRatio, VisuallyHidden.
+// The page-root chrome + visual separators + content-shape primitives +
+// the a11y baseline. With these, the foundation layer matches what
+// Chakra/Mantine/Joy ship for layout-level primitives.
+
+export { Container } from './components/Container/Container.js';
+export type { ContainerProps } from './components/Container/container.types.js';
+export { containerVariants } from './components/Container/container.variants.js';
+
+export { Divider } from './components/Divider/Divider.js';
+export type { DividerProps } from './components/Divider/divider.types.js';
+export {
+  dividerVariants,
+  dividerLineVariants,
+} from './components/Divider/divider.variants.js';
+
+export { AspectRatio } from './components/AspectRatio/AspectRatio.js';
+export type { AspectRatioProps } from './components/AspectRatio/aspectRatio.types.js';
+
+export { VisuallyHidden } from './components/VisuallyHidden/VisuallyHidden.js';
+export type { VisuallyHiddenProps } from './components/VisuallyHidden/visuallyHidden.types.js';
+
 // ───── Hooks ─────
 export { useAccessState } from './hooks/useAccessState.js';
 

package/dist/components/AppShell/AppShell.d.ts

@@ -1,32 +0,0 @@
-import type { AppShellProps } from './appShell.types.js';
-/**
- * Dashforge TW AppShell — top-level layout orchestrator.
- *
- *   ┌──────────────────────────────────────────┐
- *   │              header                      │  ← `header` slot
- *   ├────────┬─────────────────────────────────┤
- *   │        │                                 │
- *   │  nav   │           main                  │  ← `nav` + `children`
- *   │        │                                 │
- *   ├────────┴─────────────────────────────────┤
- *   │              footer                      │  ← `footer` slot
- *   └──────────────────────────────────────────┘
- *
- * **Responsive**:
- *   - `≥ md`: nav stays in the inline slot at the left.
- *   - `< md`: nav becomes a slide-in drawer toggled by `navOpen`.
- *     A backdrop closes the drawer on click (mirrors `<Dialog>` UX).
- *
- * **Body scroll lock**: when the mobile drawer is open we add
- * `overflow-hidden` to `<body>` to prevent dual-scroll wobble. The
- * effect cleans up on close + on unmount.
- *
- * **A11y**:
- *   - `<main>` landmark wraps the content area.
- *   - `<header>` / `<footer>` come for free from their HTML tags.
- *   - The mobile drawer + backdrop participate in the standard
- *     "click outside to close" pattern — `Escape` closes the drawer
- *     too (added via global keydown).
- */
-export declare function AppShell(props: AppShellProps): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=AppShell.d.ts.map

package/dist/components/AppShell/AppShell.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../../src/components/AppShell/AppShell.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,2CA+E5C"}

package/dist/components/AppShell/appShell.types.d.ts

@@ -1,62 +0,0 @@
-import type { ReactNode } from 'react';
-import type { AppShellVariants } from './appShell.variants.js';
-export interface AppShellSlotProps {
-    root?: {
-        className?: string;
-    };
-    header?: {
-        className?: string;
-    };
-    nav?: {
-        className?: string;
-    };
-    navMobile?: {
-        className?: string;
-    };
-    main?: {
-        className?: string;
-    };
-    footer?: {
-        className?: string;
-    };
-    backdrop?: {
-        className?: string;
-    };
-}
-/**
- * Props for `<AppShell>`.
- *
- * Top-level layout orchestrator with 4 named slots:
- *
- *   - `header` (top, sticky)
- *   - `nav`    (left side, fixed-width on desktop, drawer on mobile)
- *   - `footer` (bottom, non-sticky)
- *   - `children` (main content, scrolls independently)
- *
- * Responsive behavior:
- *   - **≥ md (768px)**: nav is rendered inline at the left.
- *   - **< md**:        nav slides in as an overlay drawer when
- *                      `navOpen={true}` (controlled).
- *
- * The shell is router-agnostic — pass any nav/header content. Typical
- * pairing is `<LeftNav>` + `<TopBar>` (with a hamburger button in
- * `TopBar.start` that flips `navOpen`).
- */
-export interface AppShellProps extends AppShellVariants {
-    header?: ReactNode;
-    nav?: ReactNode;
-    footer?: ReactNode;
-    children?: ReactNode;
-    /**
-     * Mobile drawer open state. Controlled — provide
-     * `onNavOpenChange` to update. When `undefined`, the mobile drawer
-     * is always closed (consumer hasn't wired up the toggle yet).
-     */
-    navOpen?: boolean;
-    onNavOpenChange?: (open: boolean) => void;
-    /** Root className shortcut. */
-    sx?: string;
-    /** Per-slot className overrides. */
-    slotProps?: AppShellSlotProps;
-}
-//# sourceMappingURL=appShell.types.d.ts.map

package/dist/components/AppShell/appShell.types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"appShell.types.d.ts","sourceRoot":"","sources":["../../../src/components/AppShell/appShell.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,MAAM,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,GAAG,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,MAAM,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,QAAQ,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,+BAA+B;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B"}

package/dist/components/AppShell/appShell.variants.d.ts

@@ -1,65 +0,0 @@
-import { type VariantProps } from 'tailwind-variants';
-/**
- * Tailwind-variants recipe for `<AppShell>`.
- *
- * Slots:
- *   - `root`      — outer flex column (full viewport)
- *   - `header`    — top region
- *   - `body`      — flex row holding nav + main
- *   - `nav`       — desktop nav rail (md+)
- *   - `navMobile` — mobile drawer (slide-in)
- *   - `main`      — scrollable content area
- *   - `footer`    — bottom region
- *   - `backdrop`  — semi-opaque overlay behind the mobile drawer
- */
-export declare const appShellVariants: import("tailwind-variants").TVReturnType<{
-    navOpen: {
-        true: {
-            navMobile: string;
-            backdrop: string;
-        };
-    };
-}, {
-    root: string;
-    header: string;
-    body: string;
-    nav: string;
-    navMobile: string[];
-    main: string;
-    footer: string;
-    backdrop: string[];
-}, undefined, {
-    navOpen: {
-        true: {
-            navMobile: string;
-            backdrop: string;
-        };
-    };
-}, {
-    root: string;
-    header: string;
-    body: string;
-    nav: string;
-    navMobile: string[];
-    main: string;
-    footer: string;
-    backdrop: string[];
-}, import("tailwind-variants").TVReturnType<{
-    navOpen: {
-        true: {
-            navMobile: string;
-            backdrop: string;
-        };
-    };
-}, {
-    root: string;
-    header: string;
-    body: string;
-    nav: string;
-    navMobile: string[];
-    main: string;
-    footer: string;
-    backdrop: string[];
-}, undefined, unknown, unknown, undefined>>;
-export type AppShellVariants = VariantProps<typeof appShellVariants>;
-//# sourceMappingURL=appShell.variants.d.ts.map

package/dist/components/AppShell/appShell.variants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"appShell.variants.d.ts","sourceRoot":"","sources":["../../../src/components/AppShell/appShell.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CA8B3B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/components/Autocomplete/Autocomplete.d.ts

@@ -1,32 +0,0 @@
-import type { AutocompleteOption, AutocompleteProps } from './autocomplete.types.js';
-/**
- * Dashforge TW Autocomplete — bridge-integrated single-select combobox.
- *
- * **Implementation note (F5-A, rev. 2)**
- *
- * The first revision wrapped `react-aria-components`' `<ComboBox>` to get
- * AAA-grade a11y for free. In practice React Aria's internal state
- * machine fought every controlled-state pattern we tried (the input text
- * would not clear when `selectedKey` went to `null`, even with a forced
- * remount via `key` bumping). To get deterministic behaviour we own all
- * of the state ourselves:
- *
- *   - `inputValue`       — the visible text in the `<input>`
- *   - `isOpen`           — popover visibility
- *   - `highlightedIndex` — keyboard navigation cursor
- *
- * A11y is still solid:
- *   - `role="combobox"` + `aria-autocomplete="list"` on the input
- *   - `aria-expanded`, `aria-controls`, `aria-activedescendant`
- *   - `role="listbox"` / `role="option"` with `aria-selected`
- *   - Full keyboard nav (↑/↓ navigate, Enter selects, Escape closes,
- *     Home/End jump, Tab closes, click-outside closes)
- *   - Required field gets `aria-required="true"`
- *
- * F5-A scope: single-select, static options, contains-substring filter
- * (case-insensitive). Multi-select, free-solo text, generic option
- * shapes, and async runtime options (`optionsFromFieldData`) are
- * deferred to F5-A-bis.
- */
-export declare function Autocomplete<TOption = AutocompleteOption>(props: AutocompleteProps<TOption>): import("react/jsx-runtime").JSX.Element | null;
-//# sourceMappingURL=Autocomplete.d.ts.map

package/dist/components/Autocomplete/Autocomplete.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Autocomplete.d.ts","sourceRoot":"","sources":["../../../src/components/Autocomplete/Autocomplete.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,yBAAyB,CAAC;AAuCjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAG,kBAAkB,EACvD,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,kDAu4BlC"}

package/dist/components/Autocomplete/autocomplete.types.d.ts

@@ -1,214 +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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-}
-//# sourceMappingURL=autocomplete.types.d.ts.map