polymorph-ui-components-mcp 0.0.1

package/build/docs/ColorPicker.md

@@ -0,0 +1,83 @@
+# ColorPicker
+
+A color picker component that lets the user select a color using a saturation/brightness panel, a hue slider, and direct input fields. The `value` prop is bindable and holds the selected color as a HEX string (e.g. `#ff0000`). A trigger button displays the current color as a swatch, and optionally a text input shows the HEX value inline. Clicking the swatch opens a popover with a 2D saturation/brightness panel, a hue gradient slider (powered by the Slider component), a live preview swatch, and switchable input fields supporting HEX, RGB, and HSL modes. Supports `disabled` to prevent interaction.
+
+## Usage
+
+```svelte
+<script>
+  import { ColorPicker } from 'polymorph-ui-components';
+</script>
+
+<ColorPicker value="#3b82f6" />
+```
+
+## Props
+
+| Prop      | Type      | Required | Default     | Description                                                                                                                                                                      |
+| --------- | --------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value     | `string`  | Yes      | `'#000000'` | Bindable. The current color as a 7-character HEX string (e.g. `#3b82f6`). Two-way bound so parent components can read and write the selected color.                              |
+| label     | `string`  | No       | `-`         | Optional text label rendered above the trigger row. When provided, a `<span>` with the label text appears above the swatch button.                                               |
+| disabled  | `boolean` | No       | `false`     | Whether the color picker is disabled. When true, the trigger button cannot be clicked, the popover cannot open, and the component is visually dimmed.                            |
+| showValue | `boolean` | No       | `false`     | Whether to display a text input beside the swatch showing the current HEX value. When true, the user can type a HEX value directly into the inline input.                        |
+| testId    | `string`  | No       | `-`         | Value for the `data-pw` attribute on the container element, used for end-to-end testing selectors.                                                                               |
+| classes   | `string`  | No       | `-`         | CSS class string applied to the component's top-level container element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
+
+## Events
+
+| Event    | Type                      | Description                                                                                                                                                                                                           |
+| -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| oninput  | `(value: string) => void` | Fires when the color changes during interaction — as the user drags on the saturation panel, moves the hue slider, or types into an input field. Receives the new HEX string. Use this for live preview updates.      |
+| onchange | `(value: string) => void` | Fires alongside `oninput` whenever the color value is committed — after a saturation panel drag, hue slider adjustment, or valid input field entry. Receives the final HEX string. Use this for persisting the value. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                                     | Default                                                            | CSS Property   | Description                                                                             |
+| -------------------------------------------- | ------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------- |
+| `--color-picker-gap`                         | `8px`                                                              | gap            | Vertical gap between the label and the trigger row.                                     |
+| `--color-picker-width`                       | `fit-content`                                                      | width          | Width of the top-level container element.                                               |
+| `--color-picker-disabled-opacity`            | `0.5`                                                              | opacity        | Opacity of the entire component when disabled.                                          |
+| `--color-picker-label-font-size`             | `14px`                                                             | font-size      | Font size of the label text above the trigger.                                          |
+| `--color-picker-label-font-weight`           | `500`                                                              | font-weight    | Font weight of the label text.                                                          |
+| `--color-picker-label-color`                 | `currentColor`                                                     | color          | Text color of the label.                                                                |
+| `--color-picker-label-letter-spacing`        | `0.01em`                                                           | letter-spacing | Letter spacing of the label text.                                                       |
+| `--color-picker-row-gap`                     | `0px`                                                              | gap            | Horizontal gap between the swatch button and the inline hex input in the trigger row.   |
+| `--color-picker-swatch-btn-background`       | `transparent`                                                      | background     | Background color of the swatch trigger button.                                          |
+| `--color-picker-swatch-btn-border`           | `1px solid #18181b`                                                | border         | Border of the swatch trigger button.                                                    |
+| `--color-picker-swatch-btn-border-radius`    | `6px 0 0 6px` (or `6px` when `showValue` is false)                 | border-radius  | Border radius of the swatch trigger button. Rounded on all sides when standalone.       |
+| `--color-picker-swatch-btn-hover-background` | `transparent`                                                      | background     | Background color of the swatch trigger button on hover.                                 |
+| `--color-picker-swatch-padding`              | `5px`                                                              | padding        | Padding inside the swatch trigger button around the color swatch.                       |
+| `--color-picker-swatch-size`                 | `26px`                                                             | width, height  | Width and height of the color swatch square inside the trigger button.                  |
+| `--color-picker-swatch-border-radius`        | `6px`                                                              | border-radius  | Border radius of the color swatch square.                                               |
+| `--color-picker-swatch-inner-shadow`         | `inset 0 0 0 1px rgba(0, 0, 0, 0.08)`                              | box-shadow     | Inner shadow on the color swatch to provide contrast against similar background colors. |
+| `--color-picker-mono-font`                   | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace` | font-family    | Monospace font family used for the inline hex input and popover input fields.           |
+| `--color-picker-popover-z-index`             | `50`                                                               | z-index        | Z-index of the popover panel, controlling its stacking order.                           |
+| `--color-picker-popover-width`               | `280px`                                                            | width          | Width of the popover panel.                                                             |
+| `--color-picker-popover-padding`             | `12px`                                                             | padding        | Padding inside the popover panel.                                                       |
+| `--color-picker-popover-background`          | `#ffffff`                                                          | background     | Background color of the popover panel.                                                  |
+| `--color-picker-popover-border`              | `1px solid currentColor`                                           | border         | Border of the popover panel.                                                            |
+| `--color-picker-popover-border-radius`       | `8px`                                                              | border-radius  | Border radius of the popover panel.                                                     |
+| `--color-picker-popover-shadow`              | `0 4px 24px rgba(0, 0, 0, 0.12), 0 1px 4px rgba(0, 0, 0, 0.06)`    | box-shadow     | Box shadow of the popover panel for elevation effect.                                   |
+| `--color-picker-panel-border-radius`         | `8px`                                                              | border-radius  | Border radius of the saturation/brightness panel inside the popover.                    |
+| `--color-picker-field-border`                | `currentColor`                                                     | border-color   | Border color of the HEX/RGB/HSL input fields in the popover.                            |
+| `--color-picker-field-color`                 | `currentColor`                                                     | color          | Text color inside the popover input fields.                                             |
+| `--color-picker-field-background`            | `#ffffff`                                                          | background     | Background color of the popover input fields and the mode toggle button.                |
+| `--color-picker-field-focus-border`          | `currentColor`                                                     | border-color   | Border color of the popover input fields when focused.                                  |
+| `--color-picker-field-label-color`           | `currentColor`                                                     | color          | Text color of the field labels (HEX, R, G, B, H, S, L) and the mode toggle button icon. |
+
+## Internal Dependencies
+
+- **Button** — used for the swatch trigger button and the color mode toggle button.
+- **Input** — used for the inline HEX text input (when `showValue` is true) and the HEX/RGB/HSL input fields in the popover.
+- **Slider** — used for the hue gradient slider in the popover.
+- **swap-vertical.svg** — SVG icon used inside the mode toggle button to indicate cycling between HEX, RGB, and HSL input modes.
+
+## Web Component
+
+Tag: `<pui-color-picker>`
+
+```html
+<pui-color-picker value="#3b82f6" label="Brand color" show-value></pui-color-picker>
+```

package/build/docs/Combobox.md

@@ -0,0 +1,336 @@
+# Combobox
+
+A text input with an attached dropdown list that filters options as the user types. Built on the library's Input component internally, so it inherits Input's validation, text transformers, and formatting capabilities via the `inputProperties` pass-through. Implements the WAI-ARIA combobox pattern with full keyboard navigation (ArrowUp/Down to highlight, Enter to select, Escape to close, Tab to close and move focus). The dropdown opens on focus or typing and closes on outside click, Escape, or item selection. Supports disabled items, custom item rendering via a Snippet, custom filter logic, a custom empty-state Snippet, input prefix/suffix slots, dropdown header/footer slots, and bindable `value`, `inputValue`, `open`, and `highlightedIndex` state.
+
+## Usage
+
+```svelte
+<script>
+  import { Combobox } from 'polymorph-ui-components';
+
+  const fruits = [
+    { id: 'apple', label: 'Apple' },
+    { id: 'banana', label: 'Banana' },
+    { id: 'cherry', label: 'Cherry' }
+  ];
+
+  let selected = $state('');
+</script>
+
+<Combobox items={fruits} bind:value={selected} placeholder="Search fruits..." />
+```
+
+### With Custom Item Rendering
+
+```svelte
+<Combobox items={fruits} bind:value={selected}>
+  {#snippet itemSnippet(item, isHighlighted)}
+    <div class:highlighted={isHighlighted}>
+      <strong>{item.label}</strong>
+      <span>({item.id})</span>
+    </div>
+  {/snippet}
+</Combobox>
+```
+
+### With Custom Filter
+
+```svelte
+<Combobox
+  items={fruits}
+  bind:value={selected}
+  filterFn={(item, query) => item.label.toLowerCase().startsWith(query.toLowerCase())}
+/>
+```
+
+### With Custom Empty State
+
+```svelte
+<Combobox items={fruits} bind:value={selected}>
+  {#snippet emptySnippet()}
+    <div style="padding: 12px; text-align: center;">
+      <p>No matches found</p>
+      <button onclick={handleCreateNew}>Create new item</button>
+    </div>
+  {/snippet}
+</Combobox>
+```
+
+### With Extra Item Data
+
+TypeScript's structural typing lets you pass items with extra properties. Cast inside the snippet to access them.
+
+```svelte
+<script>
+  import type { ComboboxItem } from 'polymorph-ui-components';
+
+  type UserItem = ComboboxItem & { avatar: string; role: string };
+
+  const users: UserItem[] = [
+    { id: '1', label: 'Alice', avatar: '/alice.png', role: 'Admin' },
+    { id: '2', label: 'Bob', avatar: '/bob.png', role: 'User' }
+  ];
+</script>
+
+<Combobox items={users} bind:value={selected}>
+  {#snippet itemSnippet(item, isHighlighted)}
+    {@const user = item as UserItem}
+    <div style="display: flex; align-items: center; gap: 8px;">
+      <img src={user.avatar} alt="" width="24" height="24" />
+      <div>
+        <div>{user.label}</div>
+        <div style="font-size: 12px; color: #666;">{user.role}</div>
+      </div>
+    </div>
+  {/snippet}
+</Combobox>
+```
+
+### With Search Icon and Clear Button
+
+```svelte
+<Combobox items={fruits} bind:value={selected} bind:inputValue>
+  {#snippet inputPrefix()}
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <circle cx="11" cy="11" r="8" /><path d="m21 21-4.35-4.35" />
+    </svg>
+  {/snippet}
+  {#snippet inputSuffix()}
+    {#if inputValue.length > 0}
+      <button onclick={() => (inputValue = '')} style="border: none; background: none; cursor: pointer;">
+        &times;
+      </button>
+    {/if}
+  {/snippet}
+</Combobox>
+```
+
+### With Dropdown Header and Footer
+
+```svelte
+<Combobox items={fruits} bind:value={selected}>
+  {#snippet dropdownHeader()}
+    <div style="padding: 8px 12px; font-size: 12px; color: #999; border-bottom: 1px solid #eee;">
+      Suggestions
+    </div>
+  {/snippet}
+  {#snippet dropdownFooter()}
+    <div style="padding: 8px 12px; border-top: 1px solid #eee;">
+      <button onclick={handleShowAll} style="width: 100%; border: none; background: none; color: #2563eb; cursor: pointer;">
+        Show all results
+      </button>
+    </div>
+  {/snippet}
+</Combobox>
+```
+
+### Server-Side Filtering
+
+```svelte
+<script>
+  let results = $state([]);
+  let loading = $state(false);
+
+  async function handleInput(query) {
+    loading = true;
+    const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
+    results = await res.json();
+    loading = false;
+  }
+</script>
+
+<Combobox
+  items={results}
+  filterFn={() => true}
+  oninput={handleInput}
+  placeholder="Search..."
+>
+  {#snippet inputSuffix()}
+    {#if loading}
+      <span class="spinner" />
+    {/if}
+  {/snippet}
+  {#snippet emptySnippet()}
+    <div style="padding: 12px; text-align: center; color: #999;">
+      {loading ? 'Searching...' : 'No results found'}
+    </div>
+  {/snippet}
+</Combobox>
+```
+
+### Accessing the Input Element
+
+```svelte
+<script>
+  let comboboxRef = $state(null);
+
+  function focusInput() {
+    comboboxRef?.getInputRef()?.focus();
+  }
+</script>
+
+<Combobox items={fruits} bind:this={comboboxRef} />
+<button onclick={focusInput}>Focus the combobox</button>
+```
+
+### With Input Validation
+
+Pass Input props via `inputProperties` to enable validation, text formatting, and more.
+
+```svelte
+<Combobox
+  items={fruits}
+  bind:value={selected}
+  inputProperties={{
+    validationPattern: /^[a-zA-Z]+$/,
+    onErrorMessage: 'Letters only',
+    maxLength: 20
+  }}
+  inputEventProperties={{
+    onstatechange: (state) => console.log('Validation:', state)
+  }}
+/>
+```
+
+## Props
+
+| Prop             | Type                                                        | Required | Default          | Description                                                                                                                                                            |
+| ---------------- | ----------------------------------------------------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| items            | `ComboboxItem[]`                                            | Yes      | `-`              | Array of selectable items. Each item has an `id`, `label`, optional `disabled` flag, and any extra properties. See ComboboxItem type below.                            |
+| value            | `string`                                                    | No       | `''`             | Bindable. The `id` of the currently selected item. Updated when the user selects an item from the dropdown.                                                            |
+| inputValue       | `string`                                                    | No       | `''`             | Bindable. The current text in the input field. Used for filtering items. Updated on every keystroke and when an item is selected (set to the item's label).             |
+| open             | `boolean`                                                   | No       | `false`          | Bindable. Controls whether the dropdown is visible. Opens on focus or typing; closes on selection, Escape, outside click, or Tab.                                      |
+| highlightedIndex | `number`                                                    | No       | `-1`             | Bindable. Index of the currently highlighted item within selectable (non-disabled) items. Set to -1 when nothing is highlighted. Useful for external highlight control. |
+| placeholder      | `string`                                                    | No       | `''`             | Placeholder text shown when the input is empty.                                                                                                                        |
+| disabled         | `boolean`                                                   | No       | `false`          | When true, the input is non-interactive and the dropdown cannot open. The component appears dimmed (opacity 0.5).                                                      |
+| name             | `string`                                                    | No       | `-`              | HTML `name` attribute on the input. Use for form submission.                                                                                                           |
+| testId           | `string`                                                    | No       | `-`              | Value for the `data-pw` attribute on the container. The input gets `{testId}-input` and each option gets `{testId}-option-{id}`.                                       |
+| classes          | `string`                                                    | No       | `-`              | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
+| noResultsText    | `string`                                                    | No       | `'No results'`   | Text shown in the dropdown when no items match the current input value. Ignored when `emptySnippet` is provided.                                                       |
+| ariaLabel        | `string`                                                    | No       | `-`              | Sets `aria-label` on the listbox dropdown. Provides an accessible name for screen readers (e.g., `"Search results"`).                                                  |
+| inputProperties  | `OptionalInputProperties`                                   | No       | `-`              | Pass-through props for the internal Input component. Use for validation (`validators`, `validationPattern`, `inProgressPattern`), text formatting (`textTransformers`, `textViewPresentation`), `dataType`, `maxLength`, `minLength`, `useTextArea`, `label`, `onErrorMessage`, `infoMessage`, etc. See Input component docs for the full list. |
+| inputEventProperties | `InputEventProperties`                                  | No       | `-`              | Pass-through event handlers for the internal Input component. Use for `onpaste`, `onstatechange`, `onclick`, etc. Note: `oninput`, `onfocus`, `onblur`, and `onkeydown` are managed by Combobox and forwarded — use Combobox's own events for these. |
+| filterFn         | `(item: ComboboxItem, query: string) => boolean`            | No       | case-insensitive `includes` | Custom filter function called for each item when `inputValue` is non-empty. Return `true` to include the item. Use for startsWith, fuzzy matching, or server-side filtering (always return `true` and update `items` externally). |
+
+## Snippets
+
+Svelte 5 Snippet props — pass content blocks to the component.
+
+| Snippet        | Type                               | Description                                                                                                                                                                                 |
+| -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| itemSnippet    | `Snippet<[ComboboxItem, boolean]>` | Custom rendering for each dropdown item. Receives the `ComboboxItem` and a `boolean` indicating whether the item is currently highlighted. Cast the item to your extended type to access extra properties. |
+| emptySnippet   | `Snippet`                          | Custom content shown when the filter matches no items. Use for "create new" buttons, loading indicators, or styled empty states. When provided, overrides `noResultsText`.                  |
+| inputPrefix    | `Snippet`                          | Content rendered before the input inside the input wrapper (e.g., a search icon). Sits inside the border/focus ring.                                                                        |
+| inputSuffix    | `Snippet`                          | Content rendered after the input inside the input wrapper (e.g., a clear button, spinner, or chevron). Sits inside the border/focus ring.                                                   |
+| dropdownHeader | `Snippet`                          | Content rendered at the top of the dropdown, before the options list (e.g., a category label or pinned items).                                                                              |
+| dropdownFooter | `Snippet`                          | Content rendered at the bottom of the dropdown, after the options list (e.g., a "Show all results" link or action buttons).                                                                 |
+
+## Events
+
+| Event     | Type                             | Description                                                                                                                                                       |
+| --------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| onselect  | `(item: ComboboxItem) => void`   | Fires when an item is selected from the dropdown (via click or Enter). Receives the full item object. Cast to your extended type to access extra properties.       |
+| oninput   | `(value: string) => void`        | Fires on every input change. Receives the current input text. Use for server-side filtering or analytics.                                                          |
+| onopen    | `() => void`                     | Fires when the dropdown opens (on focus, typing, or ArrowDown).                                                                                                    |
+| onclose   | `() => void`                     | Fires when the dropdown closes (on selection, Escape, outside click, or Tab).                                                                                      |
+| onkeydown | `(event: KeyboardEvent) => void` | Fires when a key is pressed in the input, before the component's built-in handling. Call `event.preventDefault()` to suppress the default behavior for that key.   |
+| onfocus   | `(event: FocusEvent) => void`    | Fires when the input element gains focus.                                                                                                                          |
+| onblur    | `(event: FocusEvent) => void`    | Fires when the input element loses focus.                                                                                                                          |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                                       | Default                                                             | CSS Property     | Description                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `--combobox-width`                             | `100%`                                                              | width            | Width of the combobox container.                                               |
+| `--combobox-font-family`                       | `inherit`                                                           | font-family      | Font family for the input and dropdown text.                                   |
+| `--combobox-font-size`                         | `14px`                                                              | font-size        | Font size for the input and dropdown text.                                     |
+| `--combobox-color`                             | `currentColor`                                                      | color            | Text color for the input and dropdown.                                         |
+| `--combobox-disabled-opacity`                  | `0.5`                                                               | opacity          | Opacity when the combobox is disabled.                                         |
+| `--combobox-disabled-cursor`                   | `not-allowed`                                                       | cursor           | Cursor when the combobox is disabled.                                          |
+| `--combobox-input-padding`                     | `8px 12px`                                                          | padding          | Inner padding of the input field.                                              |
+| `--combobox-input-background`                  | `#ffffff`                                                           | background       | Background color of the input field.                                           |
+| `--combobox-input-border`                      | `1px solid currentColor`                                            | border           | Border of the input field in its default state.                                |
+| `--combobox-input-border-radius`               | `6px`                                                               | border-radius    | Corner rounding of the input field.                                            |
+| `--combobox-input-transition`                  | `border-color 0.15s, box-shadow 0.15s`                              | transition       | Transition animation for input border and shadow changes.                      |
+| `--combobox-input-hover-border-color`          | `currentColor`                                                      | border-color     | Border color of the input on hover.                                            |
+| `--combobox-input-focus-border-color`          | `currentColor`                                                      | border-color     | Border color of the input when focused.                                        |
+| `--combobox-input-focus-shadow`                | `0 0 0 2px currentColor`                                            | box-shadow       | Focus ring shadow around the input.                                            |
+| `--combobox-placeholder-color`                 | `currentColor`                                                      | color            | Color of the placeholder text.                                                 |
+| `--combobox-input-prefix-padding`              | `8px`                                                               | padding-left     | Left padding of the input prefix container.                                    |
+| `--combobox-input-suffix-padding`              | `8px`                                                               | padding-right    | Right padding of the input suffix container.                                   |
+| `--combobox-dropdown-top`                      | `100%`                                                              | top              | Top position of the dropdown relative to the container. Change to open upward. |
+| `--combobox-dropdown-left`                     | `0`                                                                 | left             | Left position of the dropdown relative to the container.                       |
+| `--combobox-dropdown-right`                    | `0`                                                                 | right            | Right position of the dropdown relative to the container.                      |
+| `--combobox-dropdown-gap`                      | `4px`                                                               | margin-top       | Gap between the input and the dropdown panel.                                  |
+| `--combobox-dropdown-background`               | `#ffffff`                                                           | background       | Background color of the dropdown panel.                                        |
+| `--combobox-dropdown-border`                   | `1px solid currentColor`                                            | border           | Border of the dropdown panel.                                                  |
+| `--combobox-dropdown-border-radius`            | `8px`                                                               | border-radius    | Corner rounding of the dropdown panel.                                         |
+| `--combobox-dropdown-shadow`                   | `0 4px 12px rgba(0, 0, 0, 0.1)`                                     | box-shadow       | Shadow of the dropdown panel.                                                  |
+| `--combobox-dropdown-max-height`               | `200px`                                                             | max-height       | Maximum height of the dropdown before it scrolls.                              |
+| `--combobox-dropdown-z-index`                  | `10`                                                                | z-index          | Stack order of the dropdown panel.                                             |
+| `--combobox-dropdown-padding`                  | `0`                                                                 | padding          | Inner padding of the dropdown panel.                                           |
+| `--combobox-option-padding`                    | `8px 12px`                                                          | padding          | Inner padding of each option.                                                  |
+| `--combobox-option-color`                      | `currentColor`                                                      | color            | Text color of options.                                                         |
+| `--combobox-option-font-size`                  | `inherit`                                                           | font-size        | Font size of option text.                                                      |
+| `--combobox-option-font-weight`                | `inherit`                                                           | font-weight      | Font weight of option text.                                                    |
+| `--combobox-option-hover-background`           | `#f4f4f5`                                                           | background       | Background color of an option on hover or when highlighted via keyboard.       |
+| `--combobox-option-hover-color`                | `var(--combobox-option-color, currentColor)`                        | color            | Text color of an option on hover.                                              |
+| `--combobox-option-selected-background`        | `transparent`                                                       | background       | Background color of the currently selected option.                             |
+| `--combobox-option-selected-color`             | `var(--combobox-option-color, currentColor)`                        | color            | Text color of the currently selected option.                                   |
+| `--combobox-option-selected-font-weight`       | `inherit`                                                           | font-weight      | Font weight of the currently selected option.                                  |
+| `--combobox-option-selected-hover-background`  | `var(--combobox-option-selected-background, #f4f4f5)`               | background       | Background color of the selected option when also hovered/highlighted.         |
+| `--combobox-option-disabled-opacity`           | `0.4`                                                               | opacity          | Opacity of disabled options.                                                   |
+| `--combobox-option-disabled-cursor`            | `not-allowed`                                                       | cursor           | Cursor shown when hovering disabled options.                                   |
+| `--combobox-empty-padding`                     | `8px 12px`                                                          | padding          | Padding of the "no results" message.                                           |
+| `--combobox-empty-color`                       | `currentColor`                                                      | color            | Color of the "no results" message text.                                        |
+| `--combobox-empty-font-style`                  | `italic`                                                            | font-style       | Font style of the "no results" message.                                        |
+| `--combobox-dropdown-header-border`            | `none`                                                              | border-bottom    | Bottom border of the dropdown header section.                                  |
+| `--combobox-dropdown-header-padding`           | `0`                                                                 | padding          | Padding of the dropdown header section.                                        |
+| `--combobox-dropdown-footer-border`            | `none`                                                              | border-top       | Top border of the dropdown footer section.                                     |
+| `--combobox-dropdown-footer-padding`           | `0`                                                                 | padding          | Padding of the dropdown footer section.                                        |
+
+## Type Reference
+
+Custom types used by this component's props and events:
+
+### ComboboxItem
+
+```typescript
+type ComboboxItem = {
+  id: string; // Unique identifier for the item, used as the selected value
+  label: string; // Display text shown in the dropdown and input when selected
+  disabled?: boolean; // When true, the item is dimmed and cannot be selected
+};
+```
+
+To pass extra data (icons, descriptions, etc.), extend the type: `type MyItem = ComboboxItem & { icon: string }` and cast inside `itemSnippet`.
+
+## Internal Dependencies
+
+This component uses the following library components internally:
+
+- Input (for the text input field — inherits validation, text transformers, and ARIA support)
+
+## Web Component
+
+Tag: `<pui-combobox>`
+
+```html
+<pui-combobox placeholder="Search fruits...">
+  <svg slot="input-prefix">...</svg>
+</pui-combobox>
+```
+
+### Slots
+
+| Slot Name         | Maps to Snippet  | Description                                              |
+| ----------------- | ---------------- | ------------------------------------------------------- |
+| `input-prefix`    | `inputPrefix`    | Content rendered before the input (e.g., a search icon).|
+| `input-suffix`    | `inputSuffix`    | Content rendered after the input (e.g., a clear button).|
+| `empty`           | `emptySnippet`   | Content shown when the filter matches no items.         |
+| `dropdown-header` | `dropdownHeader` | Content rendered at the top of the dropdown.            |
+| `dropdown-footer` | `dropdownFooter` | Content rendered at the bottom of the dropdown.         |
+
+> **Note:** `items`, `filterFn`, `inputProperties`, `inputEventProperties`, and `itemSnippet` are object/function props — set them via JavaScript properties. The `itemSnippet` (which receives per-item arguments) cannot be supplied through a slot.