@alexgorbatchev/shadcn 0.0.18 → 0.0.20

package/llms/components/forms/Combobox.md

@@ -0,0 +1,594 @@
+# Combobox
+
+Story: @alexgorbatchev/shadcn/components/forms/Combobox
+Source: src/components/stories/forms/Combobox.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/Combobox.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Combobox, ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem, ComboboxGroup, ComboboxLabel, ComboboxCollection, ComboboxEmpty, ComboboxSeparator, ComboboxTrigger, ComboboxValue, ComboboxChips, ComboboxChip, ComboboxChipsInput, Button, DensityProvider, DirectionProvider, Input, InputGroupAddon, Field, FieldError, FieldLabel, FieldGroup, Item, ItemContent, ItemTitle, ItemDescription } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { ComponentProps } from "react";
+import type { ComboboxRootChangeEventDetails } from "@base-ui/react/combobox";
+import { useId, useState } from "react";
+```
+
+## Default component
+
+```tsx
+Combobox
+```
+
+## Default args
+
+```tsx
+{ items: fixture_technologies, onValueChange: fn(), onOpenChange: fn(), onInputValueChange: fn() }
+```
+
+## Default render
+
+```tsx
+({ inputClassName, inputRef, contentClassName, listClassName, groupClassName, labelClassName, itemClassName, separatorClassName, emptyClassName, triggerClassName: _triggerClassName, chipsClassName: _chipsClassName, chipClassName: _chipClassName, chipsInputClassName: _chipsInputClassName, ...args }) => (<Combobox {...args}>
+      <ComboboxInput aria-label="Technology" placeholder="Search technologies" showClear className={inputClassName} ref={inputRef}/>
+      <ComboboxContent className={contentClassName}>
+        <ComboboxEmpty className={emptyClassName}>No technology found.</ComboboxEmpty>
+        <ComboboxList className={listClassName}>
+          <ComboboxGroup className={groupClassName}>
+            <ComboboxLabel className={labelClassName}>Technologies</ComboboxLabel>
+            <ComboboxCollection>
+              {(item: string) => (<ComboboxItem key={item} value={item} className={itemClassName}>
+                  <span>{item}</span>
+                </ComboboxItem>)}
+            </ComboboxCollection>
+          </ComboboxGroup>
+          <ComboboxSeparator className={separatorClassName} data-testid="Combobox--separator"/>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>)
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Default
+
+```tsx
+{}
+```
+
+### Selected
+
+```tsx
+{
+    args: { defaultValue: "Bun" }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true, defaultValue: "Bun" }
+}
+```
+
+### Multiple
+
+```tsx
+{
+    render: (args) => <ComboboxMultipleExample onValueChange={args.onValueChange}/>
+}
+```
+
+### Filtering
+
+```tsx
+{}
+```
+
+### EmptySearch
+
+```tsx
+{}
+```
+
+### Keyboard
+
+```tsx
+{}
+```
+
+### AutoHighlight
+
+```tsx
+{
+    args: { autoHighlight: true }
+}
+```
+
+### CancelledSelection
+
+```tsx
+{
+    args: {
+        defaultValue: "Bun",
+        onValueChange: fn((_value: unknown, details: ComboboxRootChangeEventDetails) => details.cancel()),
+    }
+}
+```
+
+### CancelledOpening
+
+```tsx
+{
+    args: { onOpenChange: fn((_open: boolean, details: ComboboxRootChangeEventDetails) => details.cancel()) }
+}
+```
+
+### InputStateCallback
+
+```tsx
+{
+    args: { inputClassName: fn(() => "min-w-24"), inputRef: fn() }
+}
+```
+
+### NativePartCallbacks
+
+```tsx
+{
+    args: {
+        contentClassName: fn(() => "min-w-64"),
+        listClassName: fn(() => "p-2"),
+        groupClassName: fn(() => "py-1"),
+        labelClassName: fn(() => "py-2"),
+        itemClassName: fn(() => "py-2"),
+        separatorClassName: fn(() => "my-2"),
+        emptyClassName: fn(() => ""),
+    }
+}
+```
+
+### Groups
+
+```tsx
+{
+    render: (args) => (<Combobox items={fixture_technologyGroups} onValueChange={args.onValueChange}>
+      <ComboboxInput aria-label="Grouped technology"/>
+      <ComboboxContent>
+        <ComboboxEmpty>No technology found.</ComboboxEmpty>
+        <ComboboxList>
+          {(group: TechnologyGroup, index: number) => (<ComboboxGroup key={group.label} items={group.items}>
+              <ComboboxLabel>{group.label}</ComboboxLabel>
+              <ComboboxCollection>
+                {(item: string) => (<ComboboxItem key={item} value={item}>
+                    {item}
+                  </ComboboxItem>)}
+              </ComboboxCollection>
+              {index === 0 && <ComboboxSeparator />}
+            </ComboboxGroup>)}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>)
+}
+```
+
+### ObjectItems
+
+```tsx
+{
+    render: (args) => (<Combobox<RuntimeEngine> items={fixture_runtimeEngines} defaultValue={{ id: "bun", name: "Bun" }} itemToStringLabel={(item) => item.name} itemToStringValue={(item) => item.id} isItemEqualToValue={(item, value) => item.id === value.id} onValueChange={args.onValueChange}>
+      <ComboboxInput aria-label="Runtime engine"/>
+      <ComboboxContent>
+        <ComboboxList>
+          {(item: RuntimeEngine) => (<ComboboxGroup key={item.id}>
+              <ComboboxItem value={item}>{item.name}</ComboboxItem>
+            </ComboboxGroup>)}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>)
+}
+```
+
+### PopupInput
+
+```tsx
+{
+    args: { triggerClassName: fn(() => "gap-4") },
+    render: (args) => (<Combobox items={fixture_technologies} onValueChange={args.onValueChange}>
+      <ComboboxTrigger aria-label="Choose technology" className={args.triggerClassName} render={<Button variant="outline"/>}>
+        <ComboboxValue placeholder="Choose technology"/>
+      </ComboboxTrigger>
+      <ComboboxContent>
+        <ComboboxInput aria-label="Filter technologies" showTrigger={false}/>
+        <ComboboxEmpty>No technology found.</ComboboxEmpty>
+        <ComboboxList>
+          <ComboboxGroup>
+            <ComboboxCollection>
+              {(item: string) => (<ComboboxItem key={item} value={item}>
+                  {item}
+                </ComboboxItem>)}
+            </ComboboxCollection>
+          </ComboboxGroup>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>)
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: () => {
+        const [value, setValue] = useState<string | null>("Bun");
+        return (<div className="flex flex-col gap-4">
+        <Combobox items={fixture_technologies} value={value} onValueChange={setValue}>
+          <ComboboxInput aria-label="Controlled technology" showClear/>
+          <ComboboxContent>
+            <ComboboxList>
+              <ComboboxGroup>
+                <ComboboxCollection>
+                  {(item: string) => (<ComboboxItem key={item} value={item}>
+                      {item}
+                    </ComboboxItem>)}
+                </ComboboxCollection>
+              </ComboboxGroup>
+            </ComboboxList>
+          </ComboboxContent>
+        </Combobox>
+        <output aria-label="Selected technology">{value ?? "none"}</output>
+        <Button onClick={() => setValue("React")}>Set React</Button>
+      </div>);
+    }
+}
+```
+
+### InputAddon
+
+```tsx
+{
+    render: () => (<Combobox items={fixture_technologies}>
+      <ComboboxInput aria-label="Technology with addon" showTrigger={false}>
+        <InputGroupAddon align="inline-start">Stack</InputGroupAddon>
+      </ComboboxInput>
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxGroup>
+            <ComboboxCollection>
+              {(item: string) => (<ComboboxItem key={item} value={item}>
+                  {item}
+                </ComboboxItem>)}
+            </ComboboxCollection>
+          </ComboboxGroup>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>)
+}
+```
+
+### DensityAndDirection
+
+```tsx
+{
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <DensityProvider density="compact">
+          <div dir="rtl">
+            <Story />
+          </div>
+        </DensityProvider>
+      </DirectionProvider>),
+    ],
+    args: { defaultValue: "Bun" }
+}
+```
+
+### MultipleStateCallbacks
+
+```tsx
+{
+    args: {
+        chipsClassName: fn(() => "min-w-64"),
+        chipClassName: fn(() => "px-2"),
+        chipsInputClassName: fn(() => "min-w-24"),
+    },
+    render: (args) => (<Combobox<string, true> items={fixture_technologies} multiple defaultValue={["Bun", "React"]} onValueChange={args.onValueChange}>
+      <ComboboxChips className={args.chipsClassName}>
+        <ComboboxValue>
+          {(values: string[]) => values.map((value) => (<ComboboxChip key={value} className={args.chipClassName}>
+                {value}
+              </ComboboxChip>))}
+        </ComboboxValue>
+        <ComboboxChipsInput aria-label="Selected technologies" className={args.chipsInputClassName}/>
+      </ComboboxChips>
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxGroup>
+            <ComboboxCollection>
+              {(item: string) => (<ComboboxItem key={item} value={item}>
+                  {item}
+                </ComboboxItem>)}
+            </ComboboxCollection>
+          </ComboboxGroup>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>)
+}
+```
+
+### CompactMultiple
+
+```tsx
+{
+    decorators: [
+        (Story) => (<DensityProvider density="compact">
+        <div className="w-96">
+          <Story />
+        </div>
+      </DensityProvider>),
+    ],
+    render: () => (<div className="flex flex-col gap-4">
+      <ComboboxMultipleExample density="compact"/>
+      <Input aria-label="Reference control"/>
+    </div>)
+}
+```
+
+### ComfortableMultiple
+
+```tsx
+{
+    decorators: [
+        (Story) => (<DensityProvider density="comfortable">
+        <div className="w-96">
+          <Story />
+        </div>
+      </DensityProvider>),
+    ],
+    render: () => (<div className="flex flex-col gap-4">
+      <ComboboxMultipleExample density="comfortable"/>
+      <Input aria-label="Reference control"/>
+    </div>)
+}
+```
+
+### Invalid
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field data-invalid className="w-80">
+        <FieldLabel htmlFor={id}>Technology</FieldLabel>
+        <Combobox items={fixture_technologies} onValueChange={args.onValueChange}>
+          <ComboboxInput id={id} aria-invalid aria-describedby={`${id}-error`} aria-errormessage={`${id}-error`}/>
+          <ComboboxContent>
+            <ComboboxEmpty>No technology found.</ComboboxEmpty>
+            <ComboboxList>
+              <ComboboxGroup>
+                <ComboboxCollection>
+                  {(item: string) => (<ComboboxItem key={item} value={item}>
+                      {item}
+                    </ComboboxItem>)}
+                </ComboboxCollection>
+              </ComboboxGroup>
+            </ComboboxList>
+          </ComboboxContent>
+        </Combobox>
+        <FieldError id={`${id}-error`}>Choose a technology.</FieldError>
+      </Field>);
+    }
+}
+```
+
+### RightToLeftInvalid
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Field data-invalid className="w-80">
+        <FieldLabel htmlFor={id}>Technology</FieldLabel>
+        <Combobox items={fixture_technologies} onValueChange={args.onValueChange}>
+          <ComboboxInput id={id} aria-invalid aria-describedby={`${id}-error`} aria-errormessage={`${id}-error`}/>
+          <ComboboxContent>
+            <ComboboxEmpty>No technology found.</ComboboxEmpty>
+            <ComboboxList>
+              <ComboboxGroup>
+                <ComboboxCollection>
+                  {(item: string) => (<ComboboxItem key={item} value={item}>
+                      {item}
+                    </ComboboxItem>)}
+                </ComboboxCollection>
+              </ComboboxGroup>
+            </ComboboxList>
+          </ComboboxContent>
+        </Combobox>
+        <FieldError id={`${id}-error`}>Choose a technology.</FieldError>
+      </Field>);
+    },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### CustomItems
+
+```tsx
+{
+    render: (args) => (<Combobox<RuntimeEngine> items={fixture_runtimeEngines} defaultValue={fixture_runtimeEngines[0]} itemToStringLabel={(item) => item.name} itemToStringValue={(item) => item.id} onValueChange={args.onValueChange}>
+      <ComboboxInput aria-label="Runtime engine"/>
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxGroup>
+            <ComboboxCollection>
+              {(item: RuntimeEngine) => (<ComboboxItem key={item.id} value={item} aria-label={item.name}>
+                  <Item size="xs" className="p-0">
+                    <ItemContent>
+                      <ItemTitle>{item.name}</ItemTitle>
+                      <ItemDescription>Engine identifier: {item.id}</ItemDescription>
+                    </ItemContent>
+                  </Item>
+                </ComboboxItem>)}
+            </ComboboxCollection>
+          </ComboboxGroup>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>)
+}
+```
+
+### RightToLeftMultiple
+
+```tsx
+{
+    render: (args) => <ComboboxMultipleExample onValueChange={args.onValueChange}/>,
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl" className="w-96">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### FormSubmissionAndReset
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        const [technology, setTechnology] = useState<string | null>(null);
+        const [technologies, setTechnologies] = useState<string[]>(["Bun"]);
+        const [result, setResult] = useState("");
+        return (<form aria-label="Technology form" onReset={() => {
+                setTechnology(null);
+                setTechnologies(["Bun"]);
+            }} onSubmit={(event) => {
+                event.preventDefault();
+                const data = new FormData(event.currentTarget);
+                setResult(JSON.stringify({
+                    technology: data.get("technology"),
+                    technologies: data.getAll("technologies"),
+                    omitted: data.get("omitted"),
+                }));
+            }}>
+        <FieldGroup className="w-96">
+          <Field>
+            <FieldLabel htmlFor={id}>Required technology</FieldLabel>
+            <Combobox<string> name="technology" required items={fixture_technologies} value={technology} onValueChange={setTechnology}>
+              <ComboboxInput id={id} showClear/>
+              <ComboboxContent>
+                <ComboboxList>
+                  <ComboboxGroup>
+                    <ComboboxCollection>
+                      {(item: string) => (<ComboboxItem key={item} value={item}>
+                          {item}
+                        </ComboboxItem>)}
+                    </ComboboxCollection>
+                  </ComboboxGroup>
+                </ComboboxList>
+              </ComboboxContent>
+            </Combobox>
+          </Field>
+          <Field>
+            <ComboboxMultipleExample name="technologies" defaultValue={undefined} value={technologies} onValueChange={setTechnologies}/>
+          </Field>
+          <Field>
+            <Combobox name="omitted" items={fixture_technologies} defaultValue="Deno" disabled>
+              <ComboboxInput aria-label="Disabled technology"/>
+            </Combobox>
+          </Field>
+          <Field orientation="horizontal">
+            <Button type="submit">Save technologies</Button>
+            <Button type="reset" variant="outline">
+              Reset technologies
+            </Button>
+          </Field>
+          <output aria-label="Saved technologies">{result}</output>
+        </FieldGroup>
+      </form>);
+    }
+}
+```
+
+### RightToLeftForm
+
+```tsx
+{
+    render: function Render() {
+        const id = useId();
+        const [technology, setTechnology] = useState<string | null>(null);
+        const [technologies, setTechnologies] = useState<string[]>(["Bun"]);
+        const [result, setResult] = useState("");
+        return (<form aria-label="Technology form" onReset={() => {
+                setTechnology(null);
+                setTechnologies(["Bun"]);
+            }} onSubmit={(event) => {
+                event.preventDefault();
+                const data = new FormData(event.currentTarget);
+                setResult(JSON.stringify({
+                    technology: data.get("technology"),
+                    technologies: data.getAll("technologies"),
+                    omitted: data.get("omitted"),
+                }));
+            }}>
+        <FieldGroup className="w-96">
+          <Field>
+            <FieldLabel htmlFor={id}>Required technology</FieldLabel>
+            <Combobox<string> name="technology" required items={fixture_technologies} value={technology} onValueChange={setTechnology}>
+              <ComboboxInput id={id} showClear/>
+              <ComboboxContent>
+                <ComboboxList>
+                  <ComboboxGroup>
+                    <ComboboxCollection>
+                      {(item: string) => (<ComboboxItem key={item} value={item}>
+                          {item}
+                        </ComboboxItem>)}
+                    </ComboboxCollection>
+                  </ComboboxGroup>
+                </ComboboxList>
+              </ComboboxContent>
+            </Combobox>
+          </Field>
+          <Field>
+            <ComboboxMultipleExample name="technologies" defaultValue={undefined} value={technologies} onValueChange={setTechnologies}/>
+          </Field>
+          <Field>
+            <Combobox name="omitted" items={fixture_technologies} defaultValue="Deno" disabled>
+              <ComboboxInput aria-label="Disabled technology"/>
+            </Combobox>
+          </Field>
+          <Field orientation="horizontal">
+            <Button type="submit">Save technologies</Button>
+            <Button type="reset" variant="outline">
+              Reset technologies
+            </Button>
+          </Field>
+          <output aria-label="Saved technologies">{result}</output>
+        </FieldGroup>
+      </form>);
+    },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```