polymorph-ui-components-mcp 0.0.1

package/build/docs/Progress.md

@@ -0,0 +1,53 @@
+# Progress
+
+A linear progress bar showing task completion or usage. The `value` prop controls the filled portion relative to `max`. When `showLabel` is true, a percentage text is displayed next to the bar. Setting `value` to a negative number activates an indeterminate sliding animation for unknown-duration tasks.
+
+## Usage
+
+```svelte
+<script>
+  import { Progress } from 'polymorph-ui-components';
+</script>
+
+<Progress value={60} />
+```
+
+## Props
+
+| Prop      | Type      | Required | Default | Description                                                                                                                                                            |
+| --------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value     | `number`  | Yes      | `-`     | Current progress value (0 to max). Values are clamped to the 0-max range. A negative value activates the indeterminate animation for unknown-duration tasks.           |
+| max       | `number`  | No       | `100`   | The maximum value representing 100% completion. The filled percentage is calculated as (value / max) \* 100.                                                           |
+| showLabel | `boolean` | No       | `false` | Whether to display the rounded percentage text next to the progress bar. Hidden during indeterminate mode.                                                             |
+| testId    | `string`  | No       | `-`     | Value for the data-pw attribute, used for end-to-end testing selectors.                                                                                                |
+| 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. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                            | Default           | CSS Property       | Description                                                   |
+| ----------------------------------- | ----------------- | ------------------ | ------------------------------------------------------------- |
+| `--progress-container-width`        | `100%`            | width              | Width of the outer container holding the track and label.     |
+| `--progress-container-padding`      | `0`               | padding            | Padding around the progress container.                        |
+| `--progress-container-gap`          | `8px`             | gap                | Gap between the track and the percentage label.               |
+| `--progress-track-height`           | `8px`             | height             | Height of the background track.                               |
+| `--progress-track-background`       | `#e4e4e7`         | background         | Background color of the unfilled track.                       |
+| `--progress-track-border-radius`    | `4px`             | border-radius      | Corner rounding of the track.                                 |
+| `--progress-bar-background`         | `currentColor`    | background         | Background color of the filled bar.                           |
+| `--progress-bar-border-radius`      | `4px`             | border-radius      | Corner rounding of the filled bar.                            |
+| `--progress-bar-transition`         | `width 0.3s ease` | transition         | Transition applied when the bar width changes.                |
+| `--progress-indeterminate-duration` | `1.5s`            | animation-duration | Duration of one cycle of the indeterminate sliding animation. |
+| `--progress-label-font-size`        | `14px`            | font-size          | Font size of the percentage label.                            |
+| `--progress-label-font-weight`      | `500`             | font-weight        | Font weight of the percentage label.                          |
+| `--progress-label-color`            | `currentColor`    | color              | Text color of the percentage label.                           |
+| `--progress-label-font-family`      | `inherit`         | font-family        | Font family of the percentage label.                          |
+| `--progress-label-margin`           | `0`               | margin             | Margin around the percentage label.                           |
+
+## Web Component
+
+Tag: `<pui-progress>`
+
+```html
+<pui-progress value="60" max="100" show-label></pui-progress>
+```

package/build/docs/Radio.md

@@ -0,0 +1,75 @@
+# Radio
+
+A single radio button within a group. Multiple Radio components sharing the same `name` form a mutually exclusive group where only one can be selected at a time. Uses a hidden native `<input type="radio">` for accessibility with a fully customizable visual indicator. The `selectedValue` prop is bindable so that all radios in a group stay synchronized.
+
+## Usage
+
+```svelte
+<script>
+  import { Radio } from 'polymorph-ui-components';
+
+  let selectedPayment = $state('upi');
+</script>
+
+<Radio name="payment" value="upi" bind:selectedValue={selectedPayment} text="UPI" />
+<Radio name="payment" value="card" bind:selectedValue={selectedPayment} text="Card" />
+<Radio name="payment" value="netbanking" bind:selectedValue={selectedPayment} text="Net Banking" />
+```
+
+## Props
+
+| Prop          | Type      | Required | Default     | Description                                                                                                                                                            |
+| ------------- | --------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| name          | `string`  | Yes      | —           | The group name shared by all radio buttons in the same group. Maps to the native input's `name` attribute.                                                             |
+| value         | `string`  | Yes      | —           | The value this radio button represents. When selected, `selectedValue` becomes this value.                                                                             |
+| selectedValue | `string`  | No       | `''`        | The currently selected value in the group. Bindable. When this matches `value`, the radio appears selected.                                                            |
+| text          | `string`  | No       | `''`        | Label text displayed next to the radio indicator. Hidden when empty.                                                                                                   |
+| disabled      | `boolean` | No       | `false`     | When true, the radio button cannot be interacted with and appears in a disabled visual state.                                                                          |
+| testId        | `string`  | No       | `undefined` | Test identifier applied as `data-pw` attribute on the container for Playwright test selectors.                                                                         |
+| 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. |
+
+## Events
+
+| Event    | Type                      | Description                                                                                                                                                               |
+| -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| onchange | `(value: string) => void` | Fires when this radio button is selected. Receives the `value` of the newly selected radio. Does not fire when the radio is deselected by selecting another in the group. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                        | Default                             | CSS Property     | Description                                                      |
+| ------------------------------- | ----------------------------------- | ---------------- | ---------------------------------------------------------------- |
+| `--radio-container-display`     | `inline-flex`                       | display          | Display mode of the radio container.                             |
+| `--radio-container-align-items` | `center`                            | align-items      | Vertical alignment of the indicator and label.                   |
+| `--radio-container-gap`         | `8px`                               | gap              | Space between the radio indicator and label text.                |
+| `--radio-container-cursor`      | `pointer`                           | cursor           | Cursor style when hovering over the radio.                       |
+| `--radio-container-opacity`     | `1`                                 | opacity          | Opacity of the entire radio component.                           |
+| `--radio-size`                  | `20px`                              | width, height    | Size of the outer radio circle.                                  |
+| `--radio-border`                | `2px solid currentColor`            | border           | Border of the radio circle when unselected.                      |
+| `--radio-border-radius`         | `50%`                               | border-radius    | Border radius of the outer circle (50% for a perfect circle).    |
+| `--radio-background`            | `#ffffff`                           | background-color | Background color of the radio circle when unselected.            |
+| `--radio-selected-border`       | `2px solid currentColor`            | border           | Border of the radio circle when selected.                        |
+| `--radio-selected-background`   | `#ffffff`                           | background-color | Background color of the radio circle when selected.              |
+| `--radio-disabled-border`       | `2px solid currentColor`            | border           | Border of the radio circle when disabled.                        |
+| `--radio-disabled-background`   | `transparent`                       | background-color | Background color of the radio circle when disabled.              |
+| `--radio-dot-size`              | `10px`                              | width, height    | Size of the inner dot that appears when selected.                |
+| `--radio-dot-color`             | `currentColor`                      | background-color | Color of the inner dot when selected.                            |
+| `--radio-dot-border-radius`     | `50%`                               | border-radius    | Border radius of the inner dot (50% for a perfect circle).       |
+| `--radio-disabled-dot-color`    | `currentColor`                      | background-color | Color of the inner dot when selected and disabled.               |
+| `--radio-hover-border`          | `2px solid currentColor`            | border           | Border of the radio circle on hover (when not disabled).         |
+| `--radio-focus-shadow`          | `0 0 0 3px currentColor`            | box-shadow       | Focus ring shadow shown when the radio receives keyboard focus.  |
+| `--radio-transition`            | `0.2s`                              | transition       | Transition duration for state changes (border, background, dot). |
+| `--radio-text-font-size`        | `14px`                              | font-size        | Font size of the label text.                                     |
+| `--radio-text-font-weight`      | `400`                               | font-weight      | Font weight of the label text.                                   |
+| `--radio-text-color`            | `currentColor`                      | color            | Color of the label text.                                         |
+| `--radio-disabled-text-color`   | `currentColor`                      | color            | Color of the label text when disabled.                           |
+
+## Web Component
+
+Tag: `<pui-radio>`
+
+```html
+<pui-radio name="color" value="red" text="Red"></pui-radio>
+<pui-radio name="color" value="blue" text="Blue"></pui-radio>
+```

package/build/docs/RelativeTime.md

@@ -0,0 +1,76 @@
+# RelativeTime
+
+Displays a human-readable relative time string (e.g., "5 minutes ago", "in 3 hours") that auto-updates at a configurable interval. Uses `Intl.RelativeTimeFormat` for locale-aware formatting. Renders a semantic `<time>` element with an ISO `datetime` attribute. Optionally wraps the text in a Tooltip showing the full date and time.
+
+## Usage
+
+```svelte
+<script>
+  import { RelativeTime } from 'polymorph-ui-components';
+</script>
+
+<RelativeTime date={new Date('2025-12-25T00:00:00')} />
+```
+
+### With Tooltip
+
+```svelte
+<RelativeTime date="2025-01-15T10:30:00Z" tooltip />
+```
+
+### Short Format
+
+```svelte
+<RelativeTime date={Date.now() - 300000} format="short" />
+<!-- Renders: "5 min. ago" -->
+```
+
+## Props
+
+| Prop           | Type                            | Required | Default  | Description                                                                                                                                                            |
+| -------------- | ------------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| date           | `Date \| string \| number`      | Yes      | `-`      | The target date to compute relative time from. Accepts a `Date` object, an ISO date string, or a Unix timestamp in milliseconds.                                       |
+| locale         | `string`                        | No       | `-`      | BCP 47 locale tag for formatting (e.g., `'en-US'`, `'fr'`, `'ja'`). Defaults to the browser's locale when not specified.                                               |
+| format         | `'long' \| 'short' \| 'narrow'` | No       | `'long'` | The formatting style. `'long'` = "5 minutes ago", `'short'` = "5 min. ago", `'narrow'` = "5m ago".                                                                     |
+| updateInterval | `number`                        | No       | `60000`  | How often (in milliseconds) to recalculate the relative time string. Set to `0` to disable auto-updates.                                                               |
+| tooltip        | `boolean`                       | No       | `false`  | When true, wraps the time element in a Tooltip that shows the full date and time on hover (e.g., "Wednesday, January 15, 2025 at 10:30 AM").                           |
+| testId         | `string`                        | No       | `-`      | Value for the `data-pw` attribute on the `<time>` element, used for Playwright selectors.                                                                              |
+| 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. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                      | Default   | CSS Property | Description                                  |
+| ----------------------------- | --------- | ------------ | -------------------------------------------- |
+| `--relative-time-font-size`   | `14px`    | font-size    | Font size of the relative time text.         |
+| `--relative-time-font-weight` | `400`     | font-weight  | Font weight of the relative time text.       |
+| `--relative-time-font-family` | `-`       | font-family  | Font family of the relative time text.       |
+| `--relative-time-color`       | `inherit` | color        | Text color of the relative time.             |
+| `--relative-time-cursor`      | `default` | cursor       | Cursor style when hovering the time element. |
+
+## Type Reference
+
+Custom types used by this component's props:
+
+### RelativeTimeFormat
+
+```typescript
+type RelativeTimeFormat = 'long' | 'short' | 'narrow';
+```
+
+## Internal Dependencies
+
+This component uses the following library components internally:
+
+- Tooltip (when `tooltip` prop is true)
+
+## Web Component
+
+Tag: `<pui-relative-time>`
+
+```html
+<pui-relative-time locale="en-US"></pui-relative-time>
+```
+
+> **Note:** The `date` prop is a Date object — set it via JavaScript property.

package/build/docs/Scroller.md

@@ -0,0 +1,194 @@
+# Scroller
+
+Overflowing horizontal or vertical item list with scroll controls. Shows navigation arrows when content overflows, with gradient fade edges to hint at more content. Supports drag-to-scroll, snap-to-item, and scroll position tracking.
+
+## Import
+
+```svelte
+import {Scroller} from 'polymorph-ui-components';
+```
+
+## Properties
+
+### Mandatory Properties
+
+| Property   | Type      | Description                                                                                                       |
+| ---------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `children` | `Snippet` | The scrollable content rendered inside the scroll container. Each direct child element becomes a scrollable item. |
+
+### Optional Properties
+
+| Property            | Type                         | Default               | Description                                                                                                                                                             |
+| ------------------- | ---------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `direction`         | `'horizontal' \| 'vertical'` | `'horizontal'`        | Controls the scroll axis. When `'horizontal'`, content scrolls left/right. When `'vertical'`, content scrolls up/down.                                                  |
+| `scrollAmount`      | `number`                     | Container client size | The number of pixels to scroll when an arrow is clicked. Defaults to one full page width (horizontal) or height (vertical) of the visible container.                    |
+| `showArrows`        | `boolean`                    | `true`                | Whether to show navigation arrow buttons when content overflows. Arrows auto-hide when scrolled to the start or end.                                                    |
+| `showGradient`      | `boolean`                    | `true`                | Whether to show gradient fade overlays at the edges of the scroll container to visually hint at more content.                                                           |
+| `dragToScroll`      | `boolean`                    | `false`               | Enables click-and-drag scrolling with the mouse. When active, the cursor changes to a grabbing hand during drag.                                                        |
+| `snapToItem`        | `boolean`                    | `false`               | Enables CSS scroll snapping so the scroll position aligns to child item boundaries. Child items should have `scroll-snap-align` set (e.g., `scroll-snap-align: start`). |
+| `hideScrollbar`     | `boolean`                    | `true`                | Whether to hide the native browser scrollbar. When `true`, the scrollbar is hidden via CSS while maintaining scroll functionality.                                      |
+| `hideArrowsOnTouch` | `boolean`                    | `true`                | Whether to auto-hide navigation arrows on touch-capable devices where swiping is the natural scroll interaction.                                                        |
+| `smoothScroll`      | `boolean`                    | `true`                | Whether arrow-click scrolling uses smooth animated transitions or jumps instantly.                                                                                      |
+| `testId`            | `string`                     | `undefined`           | Sets `data-pw` on the root element. Arrow buttons get `{testId}-prev` and `{testId}-next`.                                                                              |
+| `arrowPrevious`     | `Snippet`                    | Built-in chevron SVG  | Custom snippet to render inside the previous/back arrow button, replacing the default chevron icon.                                                                     |
+| `arrowNext`         | `Snippet`                    | Built-in chevron SVG  | Custom snippet to render inside the next/forward arrow button, replacing the default chevron icon.                                                                      |
+| `classes`           | `string`                     | `-`                   | 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.  |
+
+### Event Properties
+
+| Property           | Type                                 | Description                                                                                                                                                               |
+| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onscrollposition` | `(position: ScrollPosition) => void` | Called whenever the scroll position changes (on scroll, resize, or content change). Receives a `ScrollPosition` object with current scroll metrics and progress (0 to 1). |
+
+## Usage
+
+### Basic Horizontal Scroller
+
+```svelte
+<Scroller>
+  {#each items as item}
+    <div class="card">{item.name}</div>
+  {/each}
+</Scroller>
+```
+
+### Vertical Scroller
+
+```svelte
+<Scroller direction="vertical">
+  {#each items as item}
+    <div class="row">{item.name}</div>
+  {/each}
+</Scroller>
+```
+
+### With Drag-to-Scroll and Snap
+
+```svelte
+<Scroller dragToScroll snapToItem>
+  {#each items as item}
+    <div class="snap-card" style="scroll-snap-align: start;">
+      {item.name}
+    </div>
+  {/each}
+</Scroller>
+```
+
+### Custom Arrow Icons
+
+```svelte
+<Scroller>
+  {#snippet arrowPrevious()}
+    <span>←</span>
+  {/snippet}
+  {#snippet arrowNext()}
+    <span>→</span>
+  {/snippet}
+  {#each items as item}
+    <div>{item.name}</div>
+  {/each}
+</Scroller>
+```
+
+### Tracking Scroll Position
+
+```svelte
+<script>
+  function handleScroll(position) {
+    console.log(`Progress: ${(position.progress * 100).toFixed(0)}%`);
+  }
+</script>
+
+<Scroller onscrollposition={handleScroll}>
+  {#each items as item}
+    <div>{item.name}</div>
+  {/each}
+</Scroller>
+```
+
+## CSS Custom Properties
+
+### Container
+
+| Variable                     | Default       | Description                                                                               |
+| ---------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
+| `--scroller-width`           | `100%`        | Width of the entire scroller component including arrows.                                  |
+| `--scroller-height`          | `fit-content` | Height of the entire scroller component. Useful for vertical scrollers with fixed height. |
+| `--scroller-gap`             | `0px`         | Gap between child items inside the scroll container.                                      |
+| `--scroller-padding`         | `0px`         | Padding inside the scroll container around the child items.                               |
+| `--scroller-scroll-behavior` | `smooth`      | CSS scroll-behavior for the scroll container. Controls transition style.                  |
+
+### Arrows
+
+| Variable                            | Default                           | Description                                                            |
+| ----------------------------------- | --------------------------------- | ---------------------------------------------------------------------- |
+| `--scroller-arrow-size`             | `32px`                            | Width and height of the circular arrow buttons.                        |
+| `--scroller-arrow-border-radius`    | `50%`                             | Border radius of arrow buttons. `50%` makes them circular.             |
+| `--scroller-arrow-background`       | `#ffffff`                         | Background color of arrow buttons in their default state.              |
+| `--scroller-arrow-border`           | `1px solid currentColor`          | Border of arrow buttons.                                               |
+| `--scroller-arrow-color`            | `currentColor`                    | Icon/text color inside arrow buttons.                                  |
+| `--scroller-arrow-padding`          | `4px`                             | Internal padding of arrow buttons.                                     |
+| `--scroller-arrow-box-shadow`       | `0 1px 3px rgba(0,0,0,0.12)`      | Box shadow applied to arrow buttons for depth.                         |
+| `--scroller-arrow-margin`           | `0px`                             | Margin around each arrow button for spacing from the scroll area.      |
+| `--scroller-arrow-hover-background` | `transparent`                     | Background color of arrow buttons on hover.                            |
+| `--scroller-arrow-hover-color`      | Inherits `--scroller-arrow-color` | Icon/text color of arrow buttons on hover.                             |
+| `--scroller-arrow-icon-size`        | `16px`                            | Width and height of the default chevron SVG icon inside arrow buttons. |
+
+### Gradients
+
+| Variable                    | Default                       | Description                                                           |
+| --------------------------- | ----------------------------- | --------------------------------------------------------------------- |
+| `--scroller-gradient-size`  | `80px`                        | Width (horizontal) or height (vertical) of the gradient fade overlay. |
+| `--scroller-gradient-start` | White-to-transparent gradient | Custom gradient for the start (left/top) fade edge.                   |
+| `--scroller-gradient-end`   | White-to-transparent gradient | Custom gradient for the end (right/bottom) fade edge.                 |
+
+### Snap
+
+| Variable               | Default                       | Description                                                                          |
+| ---------------------- | ----------------------------- | ------------------------------------------------------------------------------------ |
+| `--scroller-snap-type` | `x mandatory` / `y mandatory` | CSS scroll-snap-type value. Automatically adapts to direction but can be overridden. |
+
+## Type Reference
+
+### ScrollDirection
+
+```typescript
+type ScrollDirection = 'horizontal' | 'vertical';
+```
+
+### ScrollPosition
+
+```typescript
+type ScrollPosition = {
+  scrollOffset: number; // Current scroll offset in pixels
+  scrollSize: number; // Total scrollable content size in pixels
+  clientSize: number; // Visible container size in pixels
+  progress: number; // Scroll progress from 0 (start) to 1 (end)
+};
+```
+
+### ScrollerProperties
+
+```typescript
+type ScrollerProperties = OptionalScrollerProperties &
+  ScrollerEventProperties &
+  MandatoryScrollerProperties;
+```
+
+## Web Component
+
+Tag: `<pui-scroller>`
+
+```html
+<pui-scroller direction="horizontal" show-arrows>
+  <div>Scrollable content</div>
+</pui-scroller>
+```
+
+### Slots
+
+| Slot Name        | Maps to Snippet | Description                 |
+| ---------------- | --------------- | --------------------------- |
+| _(default)_      | `children`      | Scrollable content.         |
+| `arrow-previous` | `arrowPrevious` | Custom previous/left arrow. |
+| `arrow-next`     | `arrowNext`     | Custom next/right arrow.    |

package/build/docs/Select.md

@@ -0,0 +1,177 @@
+# Select
+
+A dropdown selector that supports single and multi-select modes with optional search filtering. In single-select mode, clicking an item selects it and closes the dropdown. In multi-select mode, clicking items toggles them on or off and the dropdown stays open. Selected items in multi-select are shown as dismissible pills. Supports keyboard navigation (Arrow keys, Enter, Escape, Backspace) and closes automatically when clicking outside. The `value` prop is bindable.
+
+## Usage
+
+```svelte
+<script>
+  import { Select } from 'polymorph-ui-components';
+
+  const items = [
+    { id: 'apple', label: 'Apple' },
+    { id: 'banana', label: 'Banana' },
+    { id: 'cherry', label: 'Cherry' }
+  ];
+</script>
+
+<Select {items} placeholder="Pick a fruit" onchange={(val) => console.log(val)} />
+```
+
+### Multi-Select with Search
+
+```svelte
+<Select {items} multiple searchable placeholder="Search fruits..." bind:value={selectedIds} />
+```
+
+## Props
+
+| Prop        | Type           | Required | Default | Description                                                                                                                                                            |
+| ----------- | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| items       | `SelectItem[]` | Yes      | -       | Array of selectable options. Each item has an `id` and a `label`.                                                                                                      |
+| value       | `string[]`     | No       | `[]`    | Bindable. Array of selected item IDs. In single-select mode, contains at most one element.                                                                             |
+| multiple    | `boolean`      | No       | `false` | Enables multi-select mode. Items are toggled on/off and displayed as dismissible pills in the trigger area.                                                            |
+| searchable  | `boolean`      | No       | `false` | Enables a text input in the trigger area for filtering items by label. Works in both single and multi-select modes.                                                    |
+| placeholder | `string`       | No       | `''`    | Text shown when no item is selected (or in the search input when empty).                                                                                               |
+| disabled    | `boolean`      | No       | `false` | When true, the select is non-interactive, has reduced opacity, and pointer events are disabled.                                                                        |
+| 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 element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
+
+## Events
+
+| Event    | Type                        | Description                                                                                                                       |
+| -------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| onchange | `(value: string[]) => void` | Fires when the selection changes. Receives the full array of selected item IDs. In single-select mode, the array has one element. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+### Root
+
+| Variable               | Default   | CSS Property | Description                           |
+| ---------------------- | --------- | ------------ | ------------------------------------- |
+| `--select-width`       | `100%`    | width        | Width of the select container.        |
+| `--select-font-family` | `inherit` | font-family  | Font family for the select component. |
+| `--select-font-size`   | `14px`    | font-size    | Font size for the select component.   |
+| `--select-color`       | `currentColor` | color        | Text color of the select component.   |
+
+### Disabled State
+
+| Variable                    | Default       | CSS Property | Description                               |
+| --------------------------- | ------------- | ------------ | ----------------------------------------- |
+| `--select-disabled-opacity` | `0.5`         | opacity      | Opacity when the select is disabled.      |
+| `--select-disabled-cursor`  | `not-allowed` | cursor       | Cursor shown when the select is disabled. |
+
+### Trigger
+
+| Variable                              | Default                                | CSS Property  | Description                                                 |
+| ------------------------------------- | -------------------------------------- | ------------- | ----------------------------------------------------------- |
+| `--select-trigger-gap`                | `4px`                                  | gap           | Gap between items (pills, input, value) inside the trigger. |
+| `--select-trigger-min-height`         | `40px`                                 | min-height    | Minimum height of the trigger area.                         |
+| `--select-trigger-padding`            | `8px 12px`                             | padding       | Inner padding of the trigger area.                          |
+| `--select-trigger-background`         | `#ffffff`                              | background    | Background color of the trigger area.                       |
+| `--select-trigger-border`             | `1px solid currentColor`               | border        | Border of the trigger area.                                 |
+| `--select-trigger-border-radius`      | `6px`                                  | border-radius | Corner rounding of the trigger area.                        |
+| `--select-trigger-transition`         | `border-color 0.15s, box-shadow 0.15s` | transition    | Transition for trigger hover/focus effects.                 |
+| `--select-trigger-hover-border-color` | `currentColor`                         | border-color  | Border color of the trigger on hover.                       |
+| `--select-trigger-focus-border-color` | `currentColor`                         | border-color  | Border color of the trigger when focused or open.           |
+| `--select-trigger-focus-shadow`       | `0 0 0 2px currentColor`               | box-shadow    | Box shadow of the trigger when focused or open.             |
+
+### Placeholder
+
+| Variable                     | Default   | CSS Property | Description                                                 |
+| ---------------------------- | --------- | ------------ | ----------------------------------------------------------- |
+| `--select-placeholder-color` | `currentColor` | color        | Text color of the placeholder and search input placeholder. |
+
+### Arrow
+
+| Variable               | Default   | CSS Property  | Description                               |
+| ---------------------- | --------- | ------------- | ----------------------------------------- |
+| `--select-arrow-size`  | `16px`    | width, height | Size of the dropdown chevron arrow icon.  |
+| `--select-arrow-color` | `currentColor` | color         | Color of the dropdown chevron arrow icon. |
+
+### Dropdown
+
+| Variable                          | Default                         | CSS Property  | Description                                      |
+| --------------------------------- | ------------------------------- | ------------- | ------------------------------------------------ |
+| `--select-dropdown-gap`           | `4px`                           | margin-top    | Gap between the trigger and the dropdown panel.  |
+| `--select-dropdown-background`    | `#ffffff`                       | background    | Background color of the dropdown panel.          |
+| `--select-dropdown-border`        | `1px solid currentColor`        | border        | Border of the dropdown panel.                    |
+| `--select-dropdown-border-radius` | `8px`                           | border-radius | Corner rounding of the dropdown panel.           |
+| `--select-dropdown-shadow`        | `0 4px 12px rgba(0, 0, 0, 0.1)` | box-shadow    | Box shadow of the dropdown panel.                |
+| `--select-dropdown-max-height`    | `200px`                         | max-height    | Maximum height of the dropdown (scrolls beyond). |
+| `--select-dropdown-z-index`       | `10`                            | z-index       | Stack order of the dropdown panel.               |
+
+### Options
+
+| Variable                                    | Default                                        | CSS Property | Description                                           |
+| ------------------------------------------- | ---------------------------------------------- | ------------ | ----------------------------------------------------- |
+| `--select-option-padding`                   | `8px 12px`                                     | padding      | Padding inside each dropdown option.                  |
+| `--select-option-color`                     | `currentColor`                                 | color        | Text color of dropdown options.                       |
+| `--select-option-font-size`                 | `inherit`                                      | font-size    | Font size of dropdown options.                        |
+| `--select-option-hover-background`          | `#f4f4f5`                                       | background   | Background of options on hover or keyboard highlight. |
+| `--select-option-hover-color`               | inherits `--select-option-color`               | color        | Text color of options on hover or keyboard highlight. |
+| `--select-option-selected-background`       | `#18181b`                                       | background   | Background of selected options.                       |
+| `--select-option-selected-color`            | `#ffffff`                                       | color        | Text color of selected options.                       |
+| `--select-option-selected-hover-background` | inherits `--select-option-selected-background` | background   | Background of selected options on hover.              |
+
+### Empty State
+
+| Variable                    | Default    | CSS Property | Description                                      |
+| --------------------------- | ---------- | ------------ | ------------------------------------------------ |
+| `--select-empty-padding`    | `8px 12px` | padding      | Padding of the "No results" empty state message. |
+| `--select-empty-color`      | `currentColor` | color        | Text color of the empty state message.           |
+| `--select-empty-font-style` | `italic`   | font-style   | Font style of the empty state message.           |
+| `--select-empty-font-size`  | `inherit`  | font-size    | Font size of the empty state message.            |
+
+### Pills (Multi-Select)
+
+These variables style the Pill components shown for selected items in multi-select mode. They are forwarded to the internal Pill component.
+
+| Variable                      | Default   | CSS Property  | Description                              |
+| ----------------------------- | --------- | ------------- | ---------------------------------------- |
+| `--select-pill-background`    | `#18181b`      | background    | Background color of selected item pills. |
+| `--select-pill-color`         | `#ffffff`      | color         | Text color of selected item pills.       |
+| `--select-pill-border-radius` | `999px`   | border-radius | Corner rounding of selected item pills.  |
+| `--select-pill-padding`       | `2px 8px` | padding       | Padding inside selected item pills.      |
+| `--select-pill-font-size`     | `14px`    | font-size     | Font size of selected item pills.        |
+
+## Type Reference
+
+Custom types used by this component's props and events:
+
+### SelectItem
+
+```typescript
+type SelectItem = {
+  id: string;
+  label: string;
+};
+```
+
+## Internal Dependencies
+
+This component uses the following library components internally:
+
+- Pill (for displaying selected items in multi-select mode)
+
+## Web Component
+
+Tag: `<pui-select>`
+
+```html
+<pui-select placeholder="Pick a fruit"></pui-select>
+
+<script>
+  const el = document.querySelector('pui-select');
+  el.items = [
+    { id: 'apple', label: 'Apple' },
+    { id: 'banana', label: 'Banana' },
+    { id: 'cherry', label: 'Cherry' }
+  ];
+  el.addEventListener('change', (e) => console.log(e.detail));
+</script>
+```
+
+> **Note:** The `items` and `value` props are arrays — set them via JavaScript properties, not HTML attributes.