@acusti/dropdown 0.50.1 → 0.51.0

package/README.md

@@ -13,9 +13,9 @@ of macOS.
 
 The three primary design goals for the existence of this component:
 
-1. Best-in-class UX (inspired by macOS native menus) with excellent
+1. **Best-in-class UX** (inspired by macOS native menus) with excellent
    keyboard support
-2. Best-in-class DX with the simplest possible API:
+2. **Best-in-class DX** with the simplest possible API:
     1. To create a dropdown with a `<button>` trigger, pass in a single
        child element with the body of the dropdown
     2. To create a dropdown with a custom trigger, pass in exactly two
@@ -30,7 +30,7 @@ The three primary design goals for the existence of this component:
        [collection of CSS custom properties](https://github.com/acusti/uikit/blob/main/packages/dropdown/src/styles.ts#L21-L32)
        used internally to style them if that works best for you, or just
        override the minimal default CSS as appropriate
-3. Lightweight bundle size with the bare minimum of dependencies (see
+3. **Lightweight bundle size** with the bare minimum of dependencies (see
    minzipped size above)
 
 See the [storybook docs and demo][] to get a feel for what it can do.
@@ -38,19 +38,49 @@ See the [storybook docs and demo][] to get a feel for what it can do.
 [storybook docs and demo]:
     https://uikit.acusti.ca/?path=/docs/uikit-controls-Dropdown--docs
 
-## Usage
+## Installation
 
-```
+```bash
 npm install @acusti/dropdown
 # or
 yarn add @acusti/dropdown
 ```
 
-### Props
+## Quick Start
+
+```tsx
+import Dropdown from '@acusti/dropdown';
+
+// Simple dropdown with button trigger
+function SimpleDropdown() {
+    return (
+        <Dropdown>
+            <ul>
+                <li>Option 1</li>
+                <li>Option 2</li>
+                <li>Option 3</li>
+            </ul>
+        </Dropdown>
+    );
+}
 
-This is the type signature for the props you can pass to `Dropdown`. The
-unique features provided by the component are called out and explained
-above the corresponding prop via JSDoc comments:
+// Custom trigger
+function CustomTrigger() {
+    return (
+        <Dropdown>
+            <button>My Custom Button</button>
+            <ul>
+                <li>Option 1</li>
+                <li>Option 2</li>
+            </ul>
+        </Dropdown>
+    );
+}
+```
+
+## API Reference
+
+### Props
 
 ```ts
 type Props = {
@@ -66,17 +96,49 @@ type Props = {
     allowEmpty?: boolean;
     /**
      * Can take a single React element or exactly two renderable children.
+     * - Single child: The dropdown body (trigger will be auto-generated button)
+     * - Two children: [trigger, body]
      */
+    children: ReactNode | [ReactNode, ReactNode];
     className?: string;
     disabled?: boolean;
+    /**
+     * Group identifier string links dropdowns together into a menu
+     * (like macOS top menubar).
+     */
+    group?: string;
+    /**
+     * Whether the dropdown contains items that can be selected.
+     * Defaults to true if children contain elements with data-ukt-item or data-ukt-value.
+     */
     hasItems?: boolean;
+    /**
+     * Whether the dropdown should be open when first mounted.
+     */
     isOpenOnMount?: boolean;
+    /**
+     * Whether the dropdown should include a search input for filtering options.
+     */
     isSearchable?: boolean;
+    /**
+     * Whether the dropdown should remain open after selecting an item.
+     * Useful for multi-select scenarios.
+     */
     keepOpenOnSubmit?: boolean;
+    /**
+     * Label text for the trigger button (when using single child syntax).
+     */
     label?: string;
     /**
-     * Only usable in conjunction with {isSearchable: true}.
-     * Used as search input’s name.
+     * Minimum height for the dropdown body in pixels.
+     */
+    minHeightBody?: number;
+    /**
+     * Minimum width for the dropdown body in pixels.
+     */
+    minWidthBody?: number;
+    /**
+     * Name attribute for the search input (requires isSearchable: true).
      */
     name?: string;
     onClick?: (event: React.MouseEvent<HTMLElement>) => unknown;
@@ -84,22 +146,207 @@ type Props = {
     onMouseDown?: (event: React.MouseEvent<HTMLElement>) => unknown;
     onMouseUp?: (event: React.MouseEvent<HTMLElement>) => unknown;
     onOpen?: () => unknown;
+    /**
+     * Called when an item is selected. The payload includes:
+     * - element: The DOM element that was clicked
+     * - event: The click or keyboard event
+     * - label: The visible text of the item
+     * - value: The value attribute or text content
+     */
     onSubmitItem?: (payload: Item) => void;
     /**
-     * Only usable in conjunction with {isSearchable: true}.
-     * Used as search input’s placeholder.
+     * Placeholder text for the search input (requires isSearchable: true).
      */
     placeholder?: string;
     style?: React.CSSProperties;
     /**
-     * Only usable in conjunction with {isSearchable: true}.
-     * Used as search input’s tabIndex.
+     * Tab index for the search input (requires isSearchable: true).
      */
     tabIndex?: number;
     /**
-     * Used as search input’s value if props.isSearchable === true
-     * Used to determine if value has changed to avoid triggering onSubmitItem if not
+     * Current value of the search input (requires isSearchable: true).
+     * Used for controlled components and change detection.
      */
     value?: string;
 };
 ```
+
+### Item Type
+
+```ts
+type Item = {
+    element: HTMLElement | null;
+    event: Event | React.SyntheticEvent<HTMLElement>;
+    label: string;
+    value: string;
+};
+```
+
+## Usage Examples
+
+### Basic List Dropdown
+
+```tsx
+import Dropdown from '@acusti/dropdown';
+
+function StatesDropdown() {
+    const handleSelection = (item) => {
+        console.log('Selected:', item.value);
+    };
+
+    return (
+        <Dropdown onSubmitItem={handleSelection}>
+            <ul>
+                <li>California</li>
+                <li>New York</li>
+                <li>Texas</li>
+                <li>Florida</li>
+            </ul>
+        </Dropdown>
+    );
+}
+```
+
+### Searchable Dropdown
+
+```tsx
+function SearchableDropdown() {
+    return (
+        <Dropdown
+            isSearchable
+            placeholder="Search states…"
+            label="Choose a state"
+        >
+            <ul>
+                <li>Alabama</li>
+                <li>Alaska</li>
+                <li>Arizona</li>
+                {/* ... more states */}
+            </ul>
+        </Dropdown>
+    );
+}
+```
+
+### Custom Values with Data Attributes
+
+```tsx
+function FontWeightDropdown() {
+    return (
+        <Dropdown onSubmitItem={(item) => setFontWeight(item.value)}>
+            <ul>
+                <li data-ukt-value="100">Thin (100)</li>
+                <li data-ukt-value="400">Regular (400)</li>
+                <li data-ukt-value="700">Bold (700)</li>
+                <li data-ukt-value="900">Black (900)</li>
+            </ul>
+        </Dropdown>
+    );
+}
+```
+
+### Allow Creating New Items
+
+```tsx
+function TagsDropdown() {
+    const [tags, setTags] = useState(['react', 'typescript', 'dropdown']);
+
+    const handleNewTag = (item) => {
+        if (!tags.includes(item.value)) {
+            setTags([...tags, item.value]);
+        }
+    };
+
+    return (
+        <Dropdown
+            isSearchable
+            allowCreate
+            placeholder="Add or select a tag…"
+            onSubmitItem={handleNewTag}
+        >
+            <ul>
+                {tags.map((tag) => (
+                    <li key={tag}>{tag}</li>
+                ))}
+            </ul>
+        </Dropdown>
+    );
+}
+```
+
+### Multi-Select with Checkboxes
+
+```tsx
+function MultiSelectDropdown() {
+    return (
+        <Dropdown
+            keepOpenOnSubmit
+            onSubmitItem={({ label }) => {
+                console.log('Selected color:', label);
+            }}
+        >
+            <ul>
+                <li>
+                    <label>
+                        <input type="checkbox" /> Red
+                    </label>
+                </li>
+                <li>
+                    <label>
+                        <input type="checkbox" /> Blue
+                    </label>
+                </li>
+            </ul>
+        </Dropdown>
+    );
+}
+```
+
+### Dropdown with Interactive Content
+
+```tsx
+function InteractiveDropdown() {
+    return (
+        <Dropdown hasItems={false}>
+            <button>Settings</button>
+            <div style={{ padding: '16px' }}>
+                <label>
+                    Full name:{' '}
+                    <input
+                        defaultValue=""
+                        onChange={(value) =>
+                            console.log('Full name:', value)
+                        }
+                        placeholder="Sally Ride"
+                        type="text"
+                    />
+                </label>
+                <label>
+                    Email:{' '}
+                    <input
+                        defaultValue=""
+                        onChange={(value) => console.log('Email:', value)}
+                        placeholder="sally@ride.com"
+                        type="email"
+                    />
+                </label>
+            </div>
+        </Dropdown>
+    );
+}
+```
+
+## Keyboard Navigation & Accessibility
+
+The dropdown implements full keyboard navigation:
+
+- **Enter/Space**: Open dropdown or select highlighted item
+- **Escape**: Close dropdown
+- **Arrow Up/Down**: Navigate between items
+- **Home/End**: Jump to first/last item
+- **Type characters**: Search for items (when searchable)
+
+For accessibility, the component focuses on semantic HTML structure and
+keyboard navigation. It works best when you use appropriate HTML elements
+in your dropdown content (like `<ul>` and `<li>` for lists, `<button>`
+elements for actions, etc.).

package/dist/Dropdown.d.ts

@@ -39,6 +39,7 @@ export type Props = {
      * Used as search input’s name.
      */
     name?: string;
+    onActiveItem?: (payload: Item) => void;
     onClick?: (event: ReactMouseEvent<HTMLElement>) => unknown;
     onClose?: () => unknown;
     onMouseDown?: (event: ReactMouseEvent<HTMLElement>) => unknown;
@@ -64,5 +65,5 @@ export type Props = {
 };
 type ChildrenTuple = [ReactNode, ReactNode] | readonly [ReactNode, ReactNode];
 type MaybeHTMLElement = HTMLElement | null;
-export default function Dropdown({ allowCreate, allowEmpty, children, className, disabled, hasItems, isOpenOnMount, isSearchable, keepOpenOnSubmit, label, minHeightBody, minWidthBody, name, onClick, onClose, onMouseDown, onMouseUp, onOpen, onSubmitItem, placeholder, style: styleFromProps, tabIndex, value, }: Props): import("react/jsx-runtime").JSX.Element;
+export default function Dropdown({ allowCreate, allowEmpty, children, className, disabled, hasItems, isOpenOnMount, isSearchable, keepOpenOnSubmit, label, minHeightBody, minWidthBody, name, onActiveItem, onClick, onClose, onMouseDown, onMouseUp, onOpen, onSubmitItem, placeholder, style: styleFromProps, tabIndex, value, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};