@bazza-ui/react 0.0.0 → 0.1.0-canary.2

package/dist/use-listbox-item-BIi4eRPI.d.cts

@@ -0,0 +1,182 @@
+import * as React from 'react';
+
+interface ItemContextValue {
+    /** Unique ID for this item (for DOM id attribute) */
+    id: string;
+    /** Whether the item is highlighted */
+    highlighted: boolean;
+    /** Whether the item is disabled */
+    disabled: boolean;
+    /** Keyboard shortcut for this item */
+    shortcut?: string;
+}
+declare const ItemContext: React.Context<ItemContextValue | null>;
+declare function useItemContext(): ItemContextValue;
+declare function useMaybeItemContext(): ItemContextValue | null;
+
+/**
+ * Aim guard refs for submenu navigation.
+ * Optional - only needed for popup menus with submenus.
+ */
+interface AimGuardRefs {
+    /** Whether aim guard is currently active */
+    aimGuardActiveRef: React.RefObject<boolean>;
+    /** The depth at which aim guard is active (null when not guarding) */
+    guardedDepthRef: React.RefObject<number | null>;
+}
+/**
+ * Parameters for the useListboxItem hook.
+ */
+interface UseListboxItemParams {
+    /**
+     * Explicit unique identifier for this item in the store.
+     * Takes highest priority for item registration.
+     * Used by data-first APIs to ensure consistent IDs.
+     */
+    id?: string;
+    /**
+     * Unique value for this item used as identifier and for filtering.
+     * If not provided, will be inferred from textContent.
+     * Used for registration when `id` is not provided.
+     */
+    value?: string;
+    /**
+     * Additional keywords to match against when filtering.
+     * Useful for aliases or synonyms.
+     */
+    keywords?: string[];
+    /**
+     * Whether this item is disabled.
+     * Disabled items are not selectable and are skipped during keyboard navigation.
+     */
+    disabled?: boolean;
+    /**
+     * Whether to force render this item regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Keyboard shortcut to trigger this item.
+     * When the menu is focused and the user presses this key, the item will be selected.
+     * Should be a single character (e.g., "1", "a", etc.).
+     */
+    shortcut?: string;
+    /**
+     * Forces this row's relative order during score-based sorting.
+     * Lower values appear earlier.
+     * @default 0
+     */
+    forceOrder?: number;
+    /**
+     * Overrides this row's computed fuzzy-match score.
+     * Useful for pinning or manually ranking rows in score-based views.
+     */
+    forceScore?: number;
+    /**
+     * Whether this item is a submenu trigger (for store registration).
+     * @default false
+     */
+    isSubmenuTrigger?: boolean;
+    /**
+     * Callback when this item is selected (via click or Enter key).
+     * For simple items, pass this directly. For checkbox/radio items,
+     * use registerSelect() to register a dynamic handler.
+     */
+    onSelect?: () => void;
+    /**
+     * Whether selecting this item should close the menu.
+     * @default true
+     */
+    closeOnClick?: boolean;
+    /**
+     * Callback invoked after selection occurs (via click).
+     * Called with the item's ID. The consumer handles any
+     * post-selection behavior like closing menus.
+     */
+    onAfterSelect?: (itemId: string) => void;
+    /**
+     * Children (used for text content inference when value is not provided).
+     */
+    children?: React.ReactNode;
+    /**
+     * Optional aim guard refs for popup menu navigation.
+     * When provided, pointer move events will respect the aim guard.
+     */
+    aimGuard?: AimGuardRefs;
+}
+/**
+ * Return value from the useListboxItem hook.
+ */
+interface UseListboxItemReturn {
+    /** Unique ID for this item (DOM ID for aria-activedescendant) */
+    id: string;
+    /**
+     * Store identifier for this item.
+     * Use this when calling store methods like setHighlightedId, registerSubmenuOpen, etc.
+     * This is the `value` prop (or inferred from textContent).
+     */
+    storeId: string;
+    /** Ref to attach to the item element */
+    ref: React.RefObject<HTMLDivElement | null>;
+    /** Whether item is currently highlighted */
+    isHighlighted: boolean;
+    /** Whether item should be rendered (passes filter) */
+    isVisible: boolean;
+    /** Context value to provide to children via ItemContext.Provider */
+    contextValue: ItemContextValue;
+    /**
+     * Event handlers to spread on the element.
+     * These handle click, pointer move, and pointer down events.
+     */
+    handlers: {
+        onClick: React.MouseEventHandler<HTMLDivElement>;
+        onPointerMove: React.PointerEventHandler<HTMLDivElement>;
+        onPointerDown: React.PointerEventHandler<HTMLDivElement>;
+    };
+    /**
+     * Register a custom onSelect handler.
+     * This is useful for checkbox/radio items where the select behavior
+     * needs to be customized (e.g., toggle checked state).
+     * Returns an unregister function.
+     */
+    registerSelect: (handler: (() => void) | undefined) => () => void;
+}
+/**
+ * Hook that provides all shared logic for navigatable/highlightable listbox items.
+ *
+ * This hook handles:
+ * - Item registration with the listbox store
+ * - Highlight state management (keyboard and pointer)
+ * - Filter/search visibility
+ * - Scroll into view on keyboard navigation
+ * - Click, pointer move, and pointer down event handlers
+ * - Optional aim guard integration (for submenu navigation)
+ *
+ * @example
+ * ```tsx
+ * function CustomItem(props) {
+ *   const item = useListboxItem({
+ *     value: props.value,
+ *     disabled: props.disabled,
+ *     onSelect: props.onSelect,
+ *   })
+ *
+ *   if (!item.isVisible) return null
+ *
+ *   return (
+ *     <ItemContext.Provider value={item.contextValue}>
+ *       <div
+ *         ref={item.ref}
+ *         {...item.handlers}
+ *         data-highlighted={item.isHighlighted || undefined}
+ *       >
+ *         {props.children}
+ *       </div>
+ *     </ItemContext.Provider>
+ *   )
+ * }
+ * ```
+ */
+declare function useListboxItem(params: UseListboxItemParams): UseListboxItemReturn;
+
+export { type AimGuardRefs as A, type ItemContextValue as I, type UseListboxItemParams as U, useMaybeItemContext as a, ItemContext as b, type UseListboxItemReturn as c, useListboxItem as d, useItemContext as u };

package/dist/use-listbox-item-BIi4eRPI.d.ts

@@ -0,0 +1,182 @@
+import * as React from 'react';
+
+interface ItemContextValue {
+    /** Unique ID for this item (for DOM id attribute) */
+    id: string;
+    /** Whether the item is highlighted */
+    highlighted: boolean;
+    /** Whether the item is disabled */
+    disabled: boolean;
+    /** Keyboard shortcut for this item */
+    shortcut?: string;
+}
+declare const ItemContext: React.Context<ItemContextValue | null>;
+declare function useItemContext(): ItemContextValue;
+declare function useMaybeItemContext(): ItemContextValue | null;
+
+/**
+ * Aim guard refs for submenu navigation.
+ * Optional - only needed for popup menus with submenus.
+ */
+interface AimGuardRefs {
+    /** Whether aim guard is currently active */
+    aimGuardActiveRef: React.RefObject<boolean>;
+    /** The depth at which aim guard is active (null when not guarding) */
+    guardedDepthRef: React.RefObject<number | null>;
+}
+/**
+ * Parameters for the useListboxItem hook.
+ */
+interface UseListboxItemParams {
+    /**
+     * Explicit unique identifier for this item in the store.
+     * Takes highest priority for item registration.
+     * Used by data-first APIs to ensure consistent IDs.
+     */
+    id?: string;
+    /**
+     * Unique value for this item used as identifier and for filtering.
+     * If not provided, will be inferred from textContent.
+     * Used for registration when `id` is not provided.
+     */
+    value?: string;
+    /**
+     * Additional keywords to match against when filtering.
+     * Useful for aliases or synonyms.
+     */
+    keywords?: string[];
+    /**
+     * Whether this item is disabled.
+     * Disabled items are not selectable and are skipped during keyboard navigation.
+     */
+    disabled?: boolean;
+    /**
+     * Whether to force render this item regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Keyboard shortcut to trigger this item.
+     * When the menu is focused and the user presses this key, the item will be selected.
+     * Should be a single character (e.g., "1", "a", etc.).
+     */
+    shortcut?: string;
+    /**
+     * Forces this row's relative order during score-based sorting.
+     * Lower values appear earlier.
+     * @default 0
+     */
+    forceOrder?: number;
+    /**
+     * Overrides this row's computed fuzzy-match score.
+     * Useful for pinning or manually ranking rows in score-based views.
+     */
+    forceScore?: number;
+    /**
+     * Whether this item is a submenu trigger (for store registration).
+     * @default false
+     */
+    isSubmenuTrigger?: boolean;
+    /**
+     * Callback when this item is selected (via click or Enter key).
+     * For simple items, pass this directly. For checkbox/radio items,
+     * use registerSelect() to register a dynamic handler.
+     */
+    onSelect?: () => void;
+    /**
+     * Whether selecting this item should close the menu.
+     * @default true
+     */
+    closeOnClick?: boolean;
+    /**
+     * Callback invoked after selection occurs (via click).
+     * Called with the item's ID. The consumer handles any
+     * post-selection behavior like closing menus.
+     */
+    onAfterSelect?: (itemId: string) => void;
+    /**
+     * Children (used for text content inference when value is not provided).
+     */
+    children?: React.ReactNode;
+    /**
+     * Optional aim guard refs for popup menu navigation.
+     * When provided, pointer move events will respect the aim guard.
+     */
+    aimGuard?: AimGuardRefs;
+}
+/**
+ * Return value from the useListboxItem hook.
+ */
+interface UseListboxItemReturn {
+    /** Unique ID for this item (DOM ID for aria-activedescendant) */
+    id: string;
+    /**
+     * Store identifier for this item.
+     * Use this when calling store methods like setHighlightedId, registerSubmenuOpen, etc.
+     * This is the `value` prop (or inferred from textContent).
+     */
+    storeId: string;
+    /** Ref to attach to the item element */
+    ref: React.RefObject<HTMLDivElement | null>;
+    /** Whether item is currently highlighted */
+    isHighlighted: boolean;
+    /** Whether item should be rendered (passes filter) */
+    isVisible: boolean;
+    /** Context value to provide to children via ItemContext.Provider */
+    contextValue: ItemContextValue;
+    /**
+     * Event handlers to spread on the element.
+     * These handle click, pointer move, and pointer down events.
+     */
+    handlers: {
+        onClick: React.MouseEventHandler<HTMLDivElement>;
+        onPointerMove: React.PointerEventHandler<HTMLDivElement>;
+        onPointerDown: React.PointerEventHandler<HTMLDivElement>;
+    };
+    /**
+     * Register a custom onSelect handler.
+     * This is useful for checkbox/radio items where the select behavior
+     * needs to be customized (e.g., toggle checked state).
+     * Returns an unregister function.
+     */
+    registerSelect: (handler: (() => void) | undefined) => () => void;
+}
+/**
+ * Hook that provides all shared logic for navigatable/highlightable listbox items.
+ *
+ * This hook handles:
+ * - Item registration with the listbox store
+ * - Highlight state management (keyboard and pointer)
+ * - Filter/search visibility
+ * - Scroll into view on keyboard navigation
+ * - Click, pointer move, and pointer down event handlers
+ * - Optional aim guard integration (for submenu navigation)
+ *
+ * @example
+ * ```tsx
+ * function CustomItem(props) {
+ *   const item = useListboxItem({
+ *     value: props.value,
+ *     disabled: props.disabled,
+ *     onSelect: props.onSelect,
+ *   })
+ *
+ *   if (!item.isVisible) return null
+ *
+ *   return (
+ *     <ItemContext.Provider value={item.contextValue}>
+ *       <div
+ *         ref={item.ref}
+ *         {...item.handlers}
+ *         data-highlighted={item.isHighlighted || undefined}
+ *       >
+ *         {props.children}
+ *       </div>
+ *     </ItemContext.Provider>
+ *   )
+ * }
+ * ```
+ */
+declare function useListboxItem(params: UseListboxItemParams): UseListboxItemReturn;
+
+export { type AimGuardRefs as A, type ItemContextValue as I, type UseListboxItemParams as U, useMaybeItemContext as a, ItemContext as b, type UseListboxItemReturn as c, useListboxItem as d, useItemContext as u };

package/package.json

@@ -1,18 +1,46 @@
 {
   "name": "@bazza-ui/react",
-  "version": "0.0.0",
+  "version": "0.1.0-canary.2",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+    "./dropdown-menu": {
+      "types": "./dist/dropdown-menu/index.d.ts",
+      "import": "./dist/dropdown-menu/index.js",
+      "require": "./dist/dropdown-menu/index.cjs"
+    },
+    "./select": {
+      "types": "./dist/select/index.d.ts",
+      "import": "./dist/select/index.js",
+      "require": "./dist/select/index.cjs"
+    },
+    "./combobox": {
+      "types": "./dist/combobox/index.d.ts",
+      "import": "./dist/combobox/index.js",
+      "require": "./dist/combobox/index.cjs"
+    },
+    "./context-menu": {
+      "types": "./dist/context-menu/index.d.ts",
+      "import": "./dist/context-menu/index.js",
+      "require": "./dist/context-menu/index.cjs"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js",
+      "require": "./dist/adapters/index.cjs"
+    },
+    "./internal/listbox": {
+      "types": "./dist/internal/listbox/index.d.ts",
+      "import": "./dist/internal/listbox/index.js",
+      "require": "./dist/internal/listbox/index.cjs"
+    },
+    "./internal/popup-menu": {
+      "types": "./dist/internal/popup-menu/index.d.ts",
+      "import": "./dist/internal/popup-menu/index.js",
+      "require": "./dist/internal/popup-menu/index.cjs"
     }
   },
   "files": [
@@ -21,21 +49,31 @@
   "scripts": {
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
-    "build": "tsup"
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest --watch"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@base-ui/react": "^1.0.0",
-    "@base-ui/utils": "^0.2.3"
+    "@base-ui/react": "1.0.0",
+    "@base-ui/utils": "0.2.3"
   },
   "devDependencies": {
     "@bazza-ui/typescript-config": "0.0.0",
+    "@tanstack/react-form": "^1.27.7",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.1.2",
     "@types/react-dom": "^19.1.2",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3"
+    "@vitejs/plugin-react": "^5.1.2",
+    "jsdom": "^27.4.0",
+    "react-hook-form": "^7.71.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
   }
 }

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-// @bazza-ui/react - placeholder release
-export {};

package/dist/index.js

@@ -1,2 +0,0 @@
-// @bazza-ui/react - placeholder release
-export {};