@minidev.fun/ui 1.0.1

package/llm/components/combobox.llm.md

@@ -0,0 +1,357 @@
+# Combobox
+
+Searchable select component supporting single and multi-select with optional chips UI.
+
+## Import
+
+```tsx
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxEmpty,
+  ComboboxSeparator,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  useComboboxAnchor,
+} from "@minidev.fun/ui/combobox";
+```
+
+## Anatomy
+
+### Single Select
+
+```tsx
+<Combobox>
+  <ComboboxInput />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxEmpty />
+      <ComboboxItem />
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+### Multi-Select with Chips
+
+```tsx
+const anchorRef = useComboboxAnchor()
+
+<Combobox multiple>
+  <ComboboxChips ref={anchorRef}>
+    <ComboboxChip />
+    <ComboboxChipsInput />
+  </ComboboxChips>
+  <ComboboxContent anchor={anchorRef}>
+    <ComboboxList>
+      <ComboboxItem />
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+## Components
+
+| Component          | Description                                                      |
+| ------------------ | ---------------------------------------------------------------- |
+| Combobox           | Root component managing state (doesn't render element)           |
+| ComboboxInput      | Text input with optional trigger/clear buttons for single-select |
+| ComboboxContent    | Popup container with automatic portal and positioning            |
+| ComboboxList       | Scrollable container for items with overflow handling            |
+| ComboboxItem       | Selectable item with check indicator when selected               |
+| ComboboxChips      | Container for selected chips in multi-select mode                |
+| ComboboxChip       | Individual chip with optional remove button                      |
+| ComboboxChipsInput | Text input for multi-select (use inside ComboboxChips)           |
+| ComboboxGroup      | Groups related items together                                    |
+| ComboboxLabel      | Label for item groups                                            |
+| ComboboxEmpty      | Message shown when no results match search                       |
+| ComboboxSeparator  | Visual divider between groups                                    |
+| useComboboxAnchor  | Hook returning ref for anchoring popup to chips                  |
+
+## Props
+
+### Combobox
+
+| Prop               | Type                       | Default | Description                        |
+| ------------------ | -------------------------- | ------- | ---------------------------------- |
+| value              | string \| string[] \| null | -       | Controlled selected value(s)       |
+| onValueChange      | (value) => void            | -       | Called when selection changes      |
+| defaultValue       | string \| string[] \| null | -       | Uncontrolled initial value         |
+| inputValue         | string                     | -       | Controlled input text value        |
+| onInputValueChange | (value) => void            | -       | Called when input text changes     |
+| defaultInputValue  | string                     | -       | Uncontrolled initial input text    |
+| multiple           | boolean                    | false   | Enable multi-select mode           |
+| disabled           | boolean                    | false   | Disable all interactions           |
+| open               | boolean                    | -       | Controlled open state              |
+| onOpenChange       | (open) => void             | -       | Called when popup opens/closes     |
+| openOnInputClick   | boolean                    | true    | Whether clicking input opens popup |
+
+### ComboboxInput
+
+Single-select input wrapped in InputGroup with optional addons.
+
+| Prop        | Type    | Default | Description                           |
+| ----------- | ------- | ------- | ------------------------------------- |
+| showTrigger | boolean | true    | Show dropdown trigger button          |
+| showClear   | boolean | false   | Show clear button when value selected |
+| placeholder | string  | -       | Input placeholder text                |
+| disabled    | boolean | false   | Disable input                         |
+
+### ComboboxContent
+
+| Prop        | Type                                   | Default  | Description                            |
+| ----------- | -------------------------------------- | -------- | -------------------------------------- |
+| side        | 'top' \| 'bottom' \| 'left' \| 'right' | 'bottom' | Popup placement side                   |
+| align       | 'start' \| 'center' \| 'end'           | 'start'  | Popup alignment                        |
+| sideOffset  | number                                 | 6        | Distance from anchor                   |
+| alignOffset | number                                 | 0        | Alignment adjustment                   |
+| anchor      | RefObject                              | -        | Ref to anchor element (for chips mode) |
+
+**Anchoring for Multi-Select:**
+
+```tsx
+const anchorRef = useComboboxAnchor()
+<ComboboxChips ref={anchorRef}>...</ComboboxChips>
+<ComboboxContent anchor={anchorRef}>...</ComboboxContent>
+```
+
+### ComboboxItem
+
+| Prop     | Type              | Default | Description                                      |
+| -------- | ----------------- | ------- | ------------------------------------------------ |
+| value    | any               | -       | **Required**. Unique value identifying this item |
+| disabled | boolean           | false   | Disable item interaction                         |
+| onClick  | MouseEventHandler | -       | Click handler for item selection                 |
+
+### ComboboxChips
+
+Container for chips in multi-select mode. Must be used with `useComboboxAnchor()` hook.
+
+| Prop     | Type      | Default | Description                                  |
+| -------- | --------- | ------- | -------------------------------------------- |
+| ref      | RefObject | -       | Pass ref from useComboboxAnchor()            |
+| children | ReactNode | -       | ComboboxChip and ComboboxChipsInput elements |
+
+### ComboboxChip
+
+| Prop       | Type      | Default | Description                      |
+| ---------- | --------- | ------- | -------------------------------- |
+| showRemove | boolean   | true    | Show X button to remove chip     |
+| children   | ReactNode | -       | Chip content (usually text/icon) |
+
+### ComboboxChipsInput
+
+| Prop        | Type   | Default | Description            |
+| ----------- | ------ | ------- | ---------------------- |
+| placeholder | string | -       | Input placeholder text |
+
+## Data Attributes
+
+### ComboboxInput
+
+- `data-popup-open` - Popup is open
+- `data-disabled` - Input is disabled
+- `data-focused` - Input has focus
+
+### ComboboxContent
+
+- `data-open` - Popup is open (triggers animations)
+- `data-closed` - Popup is closed (triggers animations)
+- `data-side` - Current placement side (top/bottom/left/right)
+- `data-chips` - Anchored to chips container (multi-select)
+
+### ComboboxItem
+
+- `data-selected` - Item is selected
+- `data-highlighted` - Item is keyboard highlighted
+- `data-disabled` - Item is disabled
+
+### ComboboxList
+
+- `data-empty` - List has no items (shows ComboboxEmpty)
+
+## Examples
+
+### Basic Single Select
+
+```tsx
+function FrameworkPicker() {
+  const [value, setValue] = useState<string | null>(null);
+
+  const frameworks = [
+    { value: "next", label: "Next.js" },
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue" },
+  ];
+
+  return (
+    <Combobox value={value} onValueChange={(v) => setValue(v as string)}>
+      <ComboboxInput placeholder="Select framework..." showClear />
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxEmpty>No frameworks found</ComboboxEmpty>
+          {frameworks.map((fw) => (
+            <ComboboxItem key={fw.value} value={fw.value}>
+              {fw.label}
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+### Multi-Select with Chips
+
+```tsx
+function TagPicker() {
+  const [tags, setTags] = useState<string[]>([]);
+  const anchorRef = useComboboxAnchor();
+
+  const availableTags = ["react", "typescript", "nextjs", "tailwind"];
+
+  return (
+    <Combobox
+      multiple
+      value={tags}
+      onValueChange={(v) => setTags(v as string[])}
+    >
+      <ComboboxChips ref={anchorRef}>
+        {tags.map((tag) => (
+          <ComboboxChip key={tag}>{tag}</ComboboxChip>
+        ))}
+        <ComboboxChipsInput placeholder="Add tags..." />
+      </ComboboxChips>
+      <ComboboxContent anchor={anchorRef}>
+        <ComboboxList>
+          <ComboboxEmpty>No tags found</ComboboxEmpty>
+          {availableTags.map((tag) => (
+            <ComboboxItem key={tag} value={tag}>
+              {tag}
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+### Grouped Items with Labels
+
+```tsx
+function FoodPicker() {
+  const [value, setValue] = useState<string | null>(null);
+
+  return (
+    <Combobox value={value} onValueChange={(v) => setValue(v as string)}>
+      <ComboboxInput placeholder="Select food..." showClear />
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxEmpty>No food found</ComboboxEmpty>
+          <ComboboxGroup>
+            <ComboboxLabel>Fruits</ComboboxLabel>
+            <ComboboxItem value="apple">Apple</ComboboxItem>
+            <ComboboxItem value="banana">Banana</ComboboxItem>
+          </ComboboxGroup>
+          <ComboboxSeparator />
+          <ComboboxGroup>
+            <ComboboxLabel>Vegetables</ComboboxLabel>
+            <ComboboxItem value="carrot">Carrot</ComboboxItem>
+            <ComboboxItem value="broccoli">Broccoli</ComboboxItem>
+          </ComboboxGroup>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+### Items with Icons and Metadata
+
+```tsx
+function ChannelPicker() {
+  const [channel, setChannel] = useState<string | null>(null);
+
+  const channels = [
+    { id: "1", name: "farcaster", subscribers: 89450 },
+    { id: "2", name: "base", subscribers: 45230 },
+  ];
+
+  return (
+    <Combobox value={channel} onValueChange={(v) => setChannel(v as string)}>
+      <ComboboxInput placeholder="Search channels..." showClear />
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxEmpty>No channels found</ComboboxEmpty>
+          {channels.map((ch) => (
+            <ComboboxItem key={ch.id} value={ch.id}>
+              <HashIcon className="text-muted-foreground size-4" />
+              <div className="flex-1">
+                <div className="font-medium">/{ch.name}</div>
+                <div className="text-muted-foreground text-xs">
+                  {ch.subscribers.toLocaleString()} subscribers
+                </div>
+              </div>
+            </ComboboxItem>
+          ))}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}
+```
+
+### Without Trigger Button
+
+```tsx
+<Combobox>
+  <ComboboxInput
+    placeholder="Type to search..."
+    showTrigger={false}
+    showClear
+  />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxItem value="item1">Item 1</ComboboxItem>
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+## Keyboard Interactions
+
+| Key       | Action                                            |
+| --------- | ------------------------------------------------- |
+| ArrowDown | Highlight next item (opens popup if closed)       |
+| ArrowUp   | Highlight previous item (opens popup if closed)   |
+| Enter     | Select highlighted item and close popup           |
+| Escape    | Close popup and clear highlight                   |
+| Home      | Highlight first item                              |
+| End       | Highlight last item                               |
+| Tab       | Close popup and move focus                        |
+| Backspace | Remove last chip (multi-select, when input empty) |
+
+## Accessibility
+
+- ARIA combobox pattern with `role="combobox"` on input
+- `aria-expanded` indicates popup state
+- `aria-controls` links input to popup listbox
+- `aria-activedescendant` tracks highlighted item
+- Items use `role="option"` with `aria-selected` state
+- Automatic focus management when opening/closing
+- Screen readers announce selection changes and item counts
+- Keyboard navigation follows ARIA authoring practices
+
+## Related
+
+- [Select](/components/select.llm.md) - Simple dropdown without search
+- [Input](/components/input.llm.md) - Basic text input
+- [Command](/components/command.llm.md) - Command palette pattern

package/llm/components/command.llm.md

@@ -0,0 +1,348 @@
+# Command
+
+Fast, accessible command palette with keyboard navigation and fuzzy search built on cmdk.
+
+## Import
+
+```tsx
+import {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandSeparator,
+  CommandShortcut,
+} from "@minidev.fun/ui/command";
+```
+
+## Anatomy
+
+```tsx
+<CommandDialog open={open} onOpenChange={setOpen}>
+  <Command>
+    <CommandInput placeholder="Search..." />
+    <CommandList>
+      <CommandEmpty>No results found.</CommandEmpty>
+      <CommandGroup heading="Navigation">
+        <CommandItem onSelect={handleSelect}>
+          Dashboard
+          <CommandShortcut>⌘D</CommandShortcut>
+        </CommandItem>
+      </CommandGroup>
+      <CommandSeparator />
+      <CommandGroup heading="Actions">
+        <CommandItem>Create</CommandItem>
+      </CommandGroup>
+    </CommandList>
+  </Command>
+</CommandDialog>
+```
+
+## Components
+
+| Component        | Description                                                   |
+| ---------------- | ------------------------------------------------------------- |
+| Command          | Root container with fuzzy search and keyboard navigation      |
+| CommandDialog    | Command wrapped in modal dialog, typical for ⌘K palettes      |
+| CommandInput     | Search input with integrated search icon                      |
+| CommandList      | Scrollable container for groups/items (max-h-72)              |
+| CommandEmpty     | Displayed when search returns no results                      |
+| CommandGroup     | Groups related items with optional heading                    |
+| CommandItem      | Selectable item, automatically shows check icon when selected |
+| CommandSeparator | Visual divider between groups                                 |
+| CommandShortcut  | Keyboard shortcut label, auto-aligned right                   |
+
+## Props
+
+### Command
+
+Extends cmdk's Command component.
+
+| Prop          | Type                                      | Default | Description                         |
+| ------------- | ----------------------------------------- | ------- | ----------------------------------- |
+| label         | string                                    | -       | Accessible label for screen readers |
+| value         | string                                    | -       | Controlled selected value           |
+| onValueChange | (value: string) => void                   | -       | Called when selection changes       |
+| filter        | (value: string, search: string) => number | -       | Custom filter function (0-1 score)  |
+| className     | string                                    | -       | Additional CSS classes              |
+
+### CommandDialog
+
+Wraps Command in a modal dialog with portal and overlay.
+
+| Prop            | Type                    | Default                   | Description                              |
+| --------------- | ----------------------- | ------------------------- | ---------------------------------------- |
+| open            | boolean                 | -                         | Controlled open state                    |
+| onOpenChange    | (open: boolean) => void | -                         | Called when open state changes           |
+| title           | string                  | "Command Palette"         | Dialog title (screen readers only)       |
+| description     | string                  | "Search for a command..." | Dialog description (screen readers only) |
+| showCloseButton | boolean                 | false                     | Show X button in top-right corner        |
+| className       | string                  | -                         | Additional CSS classes for content       |
+
+Title and description are visually hidden but read by screen readers for accessibility.
+
+### CommandInput
+
+| Prop          | Type                     | Default | Description               |
+| ------------- | ------------------------ | ------- | ------------------------- |
+| placeholder   | string                   | -       | Input placeholder text    |
+| value         | string                   | -       | Controlled input value    |
+| onValueChange | (search: string) => void | -       | Called when input changes |
+| className     | string                   | -       | Additional CSS classes    |
+
+Search icon is automatically included on the right side of the input.
+
+### CommandList
+
+| Prop      | Type   | Default | Description            |
+| --------- | ------ | ------- | ---------------------- |
+| className | string | -       | Additional CSS classes |
+
+Automatically handles scrolling with max height of 18rem (72). Hidden scrollbar for clean appearance.
+
+### CommandEmpty
+
+| Prop      | Type      | Default | Description                   |
+| --------- | --------- | ------- | ----------------------------- |
+| children  | ReactNode | -       | Content shown when no results |
+| className | string    | -       | Additional CSS classes        |
+
+Automatically displayed when search returns no matching items.
+
+### CommandGroup
+
+| Prop      | Type   | Default | Description            |
+| --------- | ------ | ------- | ---------------------- |
+| heading   | string | -       | Optional group label   |
+| className | string | -       | Additional CSS classes |
+
+### CommandItem
+
+| Prop      | Type                    | Default | Description                                              |
+| --------- | ----------------------- | ------- | -------------------------------------------------------- |
+| value     | string                  | -       | Unique value (auto-inferred from textContent if omitted) |
+| keywords  | string[]                | -       | Additional search keywords                               |
+| onSelect  | (value: string) => void | -       | Called when item is selected                             |
+| disabled  | boolean                 | -       | Disable selection                                        |
+| className | string                  | -       | Additional CSS classes                                   |
+
+Check icon automatically appears when item is selected (hidden if CommandShortcut is present).
+
+### CommandShortcut
+
+| Prop      | Type      | Default | Description                |
+| --------- | --------- | ------- | -------------------------- |
+| children  | ReactNode | -       | Shortcut text (e.g., "⌘K") |
+| className | string    | -       | Additional CSS classes     |
+
+Automatically positioned at the end of the command item and hides the check icon.
+
+### CommandSeparator
+
+| Prop      | Type   | Default | Description            |
+| --------- | ------ | ------- | ---------------------- |
+| className | string | -       | Additional CSS classes |
+
+## Data Attributes
+
+### CommandItem
+
+| Attribute     | When Present                         |
+| ------------- | ------------------------------------ |
+| data-selected | Item is currently highlighted/active |
+| data-disabled | Item is disabled (disabled={true})   |
+| data-checked  | Item is marked as checked/selected   |
+
+Use these for custom styling based on item state.
+
+## Examples
+
+### Basic Command Palette
+
+```tsx
+function QuickActions() {
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((open) => !open);
+      }
+    };
+    document.addEventListener("keydown", down);
+    return () => document.removeEventListener("keydown", down);
+  }, []);
+
+  return (
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <Command>
+        <CommandInput placeholder="Type a command or search..." />
+        <CommandList>
+          <CommandEmpty>No results found.</CommandEmpty>
+          <CommandGroup heading="Actions">
+            <CommandItem onSelect={() => console.log("Dashboard")}>
+              <LayoutDashboardIcon />
+              Dashboard
+              <CommandShortcut>⌘D</CommandShortcut>
+            </CommandItem>
+            <CommandItem onSelect={() => console.log("Settings")}>
+              <SettingsIcon />
+              Settings
+              <CommandShortcut>⌘,</CommandShortcut>
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    </CommandDialog>
+  );
+}
+```
+
+### Multiple Groups with Separators
+
+```tsx
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+
+    <CommandGroup heading="Navigation">
+      <CommandItem>
+        <LayoutDashboardIcon />
+        Dashboard
+      </CommandItem>
+      <CommandItem>
+        <BarChart3Icon />
+        Analytics
+      </CommandItem>
+    </CommandGroup>
+
+    <CommandSeparator />
+
+    <CommandGroup heading="Settings">
+      <CommandItem>
+        <UserIcon />
+        Profile
+      </CommandItem>
+      <CommandItem>
+        <SettingsIcon />
+        Preferences
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Controlled with Loading States
+
+```tsx
+function CommandWithLoading() {
+  const [open, setOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [selectedCommand, setSelectedCommand] = useState<string | null>(null);
+
+  const handleSelect = (value: string) => {
+    setSelectedCommand(value);
+    setLoading(true);
+
+    // Simulate async action
+    setTimeout(() => {
+      setLoading(false);
+      setOpen(false);
+      setSelectedCommand(null);
+    }, 1000);
+  };
+
+  return (
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <Command>
+        <CommandInput placeholder="Type a command..." />
+        <CommandList>
+          <CommandEmpty>No results found.</CommandEmpty>
+          <CommandGroup heading="Actions">
+            <CommandItem
+              onSelect={() => handleSelect("create")}
+              disabled={loading && selectedCommand === "create"}
+            >
+              {loading && selectedCommand === "create" ? (
+                <Loader2Icon className="animate-spin" />
+              ) : (
+                <ZapIcon />
+              )}
+              Create API Key
+              <CommandShortcut>⌘N</CommandShortcut>
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    </CommandDialog>
+  );
+}
+```
+
+### Custom Empty State
+
+```tsx
+<Command>
+  <CommandInput placeholder="Search documentation..." />
+  <CommandList>
+    <CommandEmpty>
+      <div className="py-6 text-center">
+        <p className="text-sm">No results found.</p>
+        <p className="text-muted-foreground mt-1 text-xs">
+          Try a different search term or check the docs.
+        </p>
+      </div>
+    </CommandEmpty>
+    <CommandGroup heading="Documentation">
+      <CommandItem>Getting Started</CommandItem>
+      <CommandItem>API Reference</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Without Dialog (Inline)
+
+```tsx
+<Command className="w-full max-w-md rounded-lg border">
+  <CommandInput placeholder="Search commands..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Actions">
+      <CommandItem>
+        <FileTextIcon />
+        New File
+      </CommandItem>
+      <CommandItem>
+        <UserIcon />
+        New User
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+## Keyboard
+
+| Key         | Action                                    |
+| ----------- | ----------------------------------------- |
+| ⌘K / Ctrl+K | Open command palette (app implementation) |
+| ↓ / ↑       | Navigate items                            |
+| Enter       | Select highlighted item                   |
+| Escape      | Close dialog                              |
+| Home / End  | Jump to first/last item                   |
+| Type        | Filter items by fuzzy search              |
+
+## Accessibility
+
+- Full keyboard navigation with arrow keys and Enter
+- ARIA attributes automatically applied to items and groups
+- Screen reader support for search input and results count
+- Focus management when opening/closing dialog
+- DialogTitle and DialogDescription provided for screen readers (visually hidden)
+- Disabled items marked with `aria-disabled` and cannot be selected