polymorph-ui-components-mcp 0.0.1

package/build/docs/SplitInput.md

@@ -0,0 +1,157 @@
+# SplitInput
+
+A generic segmented input component for capturing structured multi-field values such as OTP/PIN codes, RGB/HSL color channels, or IP addresses. Each segment is an independent `Input` instance with its own validation, data type, and constraints configured via `FieldConfig`. The `values` prop is a bindable `string[]` where each element corresponds to one field. When `autoAdvance` is enabled the cursor automatically moves to the next field after a character is entered, enabling rapid single-character entry (e.g., OTP). Supports paste distribution across fields, keyboard navigation with arrow keys and Tab, and optional separators and per-field labels. Validation is fully delegated to the underlying Input component.
+
+## Usage
+
+```svelte
+<script>
+  import { SplitInput } from 'polymorph-ui-components';
+
+  let otpValues = $state(['', '', '', '', '', '']);
+  let rgbValues = $state(['', '', '']);
+  let ipValues = $state(['', '', '', '']);
+</script>
+
+<!-- OTP / PIN entry (6 digits, auto-advance) -->
+<SplitInput bind:values={otpValues} length={6} autoAdvance />
+
+<!-- RGB color channels with labels and separator -->
+<SplitInput
+  bind:values={rgbValues}
+  separator=","
+  fields={[
+    { dataType: 'number', maxLength: 3, min: 0, max: 255, placeholder: '0', label: 'R' },
+    { dataType: 'number', maxLength: 3, min: 0, max: 255, placeholder: '0', label: 'G' },
+    { dataType: 'number', maxLength: 3, min: 0, max: 255, placeholder: '0', label: 'B' }
+  ]}
+/>
+
+<!-- IP address with dot separators -->
+<SplitInput
+  bind:values={ipValues}
+  separator="."
+  fields={[
+    { dataType: 'number', maxLength: 3, min: 0, max: 255, placeholder: '0' },
+    { dataType: 'number', maxLength: 3, min: 0, max: 255, placeholder: '0' },
+    { dataType: 'number', maxLength: 3, min: 0, max: 255, placeholder: '0' },
+    { dataType: 'number', maxLength: 3, min: 0, max: 255, placeholder: '0' }
+  ]}
+/>
+```
+
+## Props
+
+| Prop        | Type            | Required | Default | Description                                                                                                                                                                                                                                                                                                         |
+| ----------- | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| values      | `string[]`      | Yes      | `[]`    | Bindable. Array of current field values where each element corresponds to one input segment. The array length matches `fieldCount` (derived from `fields.length` or `length`).                                                                                                                                      |
+| fields      | `FieldConfig[]` | No       | `-`     | Array of per-field configuration objects. When provided, `fields.length` determines the number of segments and each entry controls that field's data type, constraints, placeholder, validation, and label. When omitted, the component creates `length` fields defaulting to `dataType: 'tel'` and `maxLength: 1`. |
+| length      | `number`        | No       | `4`     | Number of input fields to render when `fields` is not provided. Ignored when `fields` is supplied since the array length takes precedence.                                                                                                                                                                          |
+| disabled    | `boolean`       | No       | `false` | Whether all fields are disabled. When true, no field accepts input or fires events.                                                                                                                                                                                                                                 |
+| autoAdvance | `boolean`       | No       | `false` | When true and a field's `maxLength` is 1, focus automatically moves to the next field after a character is entered. Also enables paste distribution where pasted text is spread one character per field starting from the focused field.                                                                            |
+| separator   | `string`        | No       | `-`     | A string rendered between each pair of adjacent fields as a visual separator (e.g., `"."` for IP addresses, `","` for RGB, `"-"` for formatted codes).                                                                                                                                                              |
+| testId      | `string`        | No       | `-`     | Value for the `data-pw` attribute on the top-level 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.                                                                                                                                             |
+
+## Methods
+
+| Method  | Signature    | Description                                                                                                                   |
+| ------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| clear() | `() => void` | Clears all field values to empty strings, fires `oninput` and `onchange` with the cleared array, and focuses the first field. |
+| focus() | `() => void` | Moves focus to the first input field.                                                                                         |
+
+## Events
+
+| Event      | Type                         | Description                                                                                                                                                                                         |
+| ---------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| oninput    | `(values: string[]) => void` | Fires on every value change as the user types, pastes, or clears. Receives a copy of the current `values` array. Use this for live preview updates.                                                 |
+| onchange   | `(values: string[]) => void` | Fires alongside `oninput` on every value change. Receives a copy of the current `values` array. Use this for committing values or triggering side effects.                                          |
+| oncomplete | `(values: string[]) => void` | Fires when every field contains a non-empty value (i.e., all segments are filled). Receives a copy of the completed `values` array. Use this to trigger submission or validation of the full input. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                            | Default             | CSS Property  | Description                                                                                  |
+| ----------------------------------- | ------------------- | ------------- | -------------------------------------------------------------------------------------------- |
+| `--split-input-gap`                 | `8px`               | gap           | Horizontal spacing between field segments (and separators).                                  |
+| `--split-input-width`               | `fit-content`       | width         | Width of the overall field group container.                                                  |
+| `--split-input-label-gap`           | `3px`               | gap           | Vertical spacing between a field input and its label below.                                  |
+| `--split-input-border`              | `1px solid currentColor` | border        | Border applied to each individual input field.                                               |
+| `--split-input-border-radius`       | `6px`               | border-radius | Corner rounding of each individual input field.                                              |
+| `--split-input-focus-border`        | `1px solid currentColor` | border        | Border applied to a field when it receives focus.                                            |
+| `--split-input-input-width`         | `100%`              | width         | Width of each individual input field.                                                        |
+| `--split-input-input-height`        | `36px`              | height        | Height of each individual input field. Also sets the height of separator elements.           |
+| `--split-input-text-align`          | `center`            | text-align    | Text alignment within each input field.                                                      |
+| `--split-input-font-size`           | `14px`              | font-size     | Font size of input text within each field.                                                   |
+| `--split-input-font-weight`         | `500`               | font-weight   | Font weight of input text within each field.                                                 |
+| `--split-input-font-family`         | (inherited)         | font-family   | Font family of input text within each field. Falls through to the Input component's default. |
+| `--split-input-input-padding`       | `0 6px`             | padding       | Padding inside each individual input field.                                                  |
+| `--split-input-label-font-size`     | `12px`              | font-size     | Font size of per-field labels displayed below each input.                                    |
+| `--split-input-label-font-weight`   | `500`               | font-weight   | Font weight of per-field labels.                                                             |
+| `--split-input-label-color`         | `currentColor`           | color         | Text color of per-field labels.                                                              |
+| `--split-input-separator-font-size` | `16px`              | font-size     | Font size of separator characters rendered between fields.                                   |
+| `--split-input-separator-color`     | `currentColor`           | color         | Text color of separator characters.                                                          |
+
+## Internal Dependencies
+
+- `Input` -- each field segment is rendered as an Input component instance with validation, data type, and constraint props delegated from the corresponding `FieldConfig`.
+
+## Type Reference
+
+### FieldConfig
+
+Per-field configuration object. Picked from `OptionalInputProperties`.
+
+```typescript
+type FieldConfig = {
+  dataType?: 'text' | 'tel' | 'password' | 'email' | 'number';
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  placeholder?: string | null;
+  validationPattern?: RegExp | null;
+  validators?: CustomValidator[];
+  label?: string | null;
+};
+```
+
+- `dataType` -- The HTML input type for the field. Controls keyboard behavior on mobile (e.g., `'tel'` shows numeric pad). Defaults to `'text'`; when `fields` is omitted, auto-generated configs use `'tel'`.
+- `maxLength` -- Maximum number of characters allowed in the field. Defaults to `1000`; when `fields` is omitted, auto-generated configs use `1`.
+- `min` -- Minimum numeric value (only effective when `dataType` is `'number'`).
+- `max` -- Maximum numeric value (only effective when `dataType` is `'number'`).
+- `placeholder` -- Placeholder text shown when the field is empty.
+- `validationPattern` -- A `RegExp` used by the underlying Input to validate the field value. Defaults to `null` (no pattern validation).
+- `validators` -- Array of `CustomValidator` functions for custom validation logic. Each receives the input value and current validation state and returns a new `ValidationState`.
+- `label` -- Text label displayed below the field (e.g., `'R'`, `'G'`, `'B'` for color channels).
+
+### CustomValidator
+
+```typescript
+type CustomValidator = (
+  inputValue: string,
+  currentValidationState: ValidationState
+) => ValidationState;
+```
+
+### ValidationState
+
+```typescript
+type ValidationState = 'Valid' | 'InProgress' | 'Invalid';
+```
+
+## Web Component
+
+Tag: `<pui-split-input>`
+
+```html
+<pui-split-input length="6" auto-advance></pui-split-input>
+
+<script>
+  const el = document.querySelector('pui-split-input');
+  el.values = ['', '', '', '', '', ''];
+  el.addEventListener('complete', (e) => console.log(e.detail));
+</script>
+```
+
+> **Note:** The `values` and `fields` props are arrays — set them via JavaScript properties, not HTML attributes.

package/build/docs/Step.md

@@ -0,0 +1,52 @@
+# Step
+
+An individual step within a Stepper. Displays either a numbered circle or an icon image, a text label, and a dashed separator line. When clicked, fires the `onclick` event with `{ selectedIndex }`. The separator is hidden for the last step via CSS `--step-separator-display: none`.
+
+## Usage
+
+```svelte
+<script>
+  import { Step } from 'polymorph-ui-components';
+</script>
+
+<Step />
+```
+
+## Props
+
+| Prop      | Type     | Required | Default | Description                                                                                                                                                            |
+| --------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| stepIndex | `number` | Yes      | `-`     | The 1-based step number displayed inside the circle (when no icon is provided).                                                                                        |
+| label     | `string` | Yes      | `-`     | Text label displayed next to the step circle.                                                                                                                          |
+| icon      | `string` | No       | `-`     | Optional URL of an icon image that replaces the step number circle.                                                                                                    |
+| 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                                                                               |
+| --------- | -------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| onclick   | `(event: { selectedIndex: number }) => void` | Fires when the step is clicked. Receives { selectedIndex: number } with the step's index. |
+| onkeydown | `(event: KeyboardEvent) => void`             | Fires when a key is pressed while the step has focus.                                     |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                                  | Default             | CSS Property     | Description                                                            |
+| ----------------------------------------- | ------------------- | ---------------- | ---------------------------------------------------------------------- |
+| `--step-flex-direction`                   | `row`               | flex-direction   | Layout direction of the step (row for horizontal layout).              |
+| `--step-index-container-height`           | `30px`              | height           | Height of the step number circle.                                      |
+| `--step-index-container-width`            | `30px`              | width            | Width of the step number circle.                                       |
+| `--step-index-container-radius`           | `50%`               | border-radius    | Corner rounding of the step number circle.                             |
+| `--step-index-container-background-color` | `#798fa5cc`         | background-color | Background color of the step number circle.                            |
+| `--step-separator-display`                     | `block`             | display          | Display mode of the separator line (set 'none' to hide for last step). |
+| `--step-separator-height`                      | `1px`               | height           | Height (thickness) of the separator line.                              |
+| `--step-separator-width`                       | `50px`              | width            | Width of the separator line.                                           |
+| `--step-separator-margin`                      | `0px 12px 0px 12px` | margin           | Margin around the separator line.                                      |
+| `--step-text-margin`                      | `0px 0px 0px 12px`  | margin           | Margin around the step label text.                                     |
+| `--step-text-font-size`                   | `inherit`           | font-size        | Font size of the step label text.                                      |
+| `--step-text-color`                       | `inherit`           | color            | Color of the step label text.                                          |
+| `--step-index-font-size`                  | `14px`              | font-size        | Font size of the step number inside the circle.                        |
+| `--step-index-color`                      | `white`             | color            | Color of the step number text.                                         |
+| `--step-separator-background-image`            | `repeating-linear-gradient(...)` | background-image | Background image pattern for the step separator line.           |
+| `--step-separator-background-image-color`      | `#798fa5cc`         | color (in gradient) | Color of the dashed separator line between steps.              |

package/build/docs/Stepper.md

@@ -0,0 +1,85 @@
+# Stepper
+
+A progress indicator showing numbered steps with completion and active states. Each step shows either a step number or a custom icon, a label, and a dashed separator line to the next step. Steps before `currentStepIndex` are styled as completed, the step at `currentStepIndex` is active (both inherit the current text color by default), and remaining steps are inactive (grey). Each step is clickable, firing `onhandlestepclick` with the selected index.
+
+## Usage
+
+```svelte
+<script>
+  import { Stepper } from 'polymorph-ui-components';
+</script>
+
+<Stepper />
+```
+
+## Props
+
+| Prop             | Type            | Required | Default | Description                                                                                                                                                            |
+| ---------------- | --------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| steps            | `Array<Step>`   | Yes      | `-`     | Array of Step objects defining each step. Each Step has a `label` string and optional `icon` URL.                                                                      |
+| currentStepIndex | `number`        | Yes      | `-`     | The 0-based index of the currently active step. Steps before this index are styled as completed, the step at this index is active.                                     |
+| 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. |
+| testId           | `string`        | No       | `-`     | Test selector value applied as `data-pw` on the outermost element.                                                                                                    |
+
+## Events
+
+| Event             | Type                                         | Description                                                                                     |
+| ----------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| onhandlestepclick | `(event: { selectedIndex: number }) => void` | Fires when any step is clicked. Receives { selectedIndex: number } with the 1-based step index. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                                            | Default   | CSS Property                       | Description                                                              |
+| --------------------------------------------------- | --------- | ---------------------------------- | ------------------------------------------------------------------------ |
+| `--stepper-flex-direction`                        | `row`     | flex-direction                     | Layout direction of the steps (row for horizontal, column for vertical). |
+| `--step-text-active-color`                          | `currentColor` | --step-text-color                  | Text color of the active step label.                                     |
+| `--step-separator-background-image-active-color`         | `currentColor` | --step-separator-background-image-color | Color of the separator line for active steps.                            |
+| `--step-text-completed-color`                       | `currentColor` | --step-text-color                  | Text color of completed step labels.                                     |
+| `--step-separator-background-image-completed-color`      | `currentColor` | --step-separator-background-image-color | Color of the separator line for completed steps.                         |
+| `--step-index-container-active-background-color`    | `currentColor` | background-color                   | Background color of the active step circle.                              |
+| `--step-index-container-completed-background-color` | `currentColor` | background-color                   | Background color of completed step circles.                              |
+
+### Step Sub-component CSS Variables
+
+These CSS variables are defined in the `Step` sub-component and control individual step styling.
+
+| Variable                                  | Default             | CSS Property     | Description                                  |
+| ----------------------------------------- | ------------------- | ---------------- | -------------------------------------------- |
+| `--step-flex-direction`                   | `row`               | flex-direction   | Layout direction of each step.               |
+| `--step-index-container-height`           | `30px`              | height           | Height of the step number circle.            |
+| `--step-index-container-width`            | `30px`              | width            | Width of the step number circle.             |
+| `--step-index-container-radius`           | `50%`               | border-radius    | Border radius of the step number circle.     |
+| `--step-index-container-background-color` | `currentColor`      | background-color | Background color of inactive step circles.   |
+| `--step-index-font-size`                  | `14px`              | font-size        | Font size of the step number.                |
+| `--step-index-color`                      | `white`             | color            | Text color of the step number.               |
+| `--step-separator-display`                     | `block`             | display          | Display mode of the step separator.          |
+| `--step-separator-height`                      | `1px`               | height           | Height of the separator line.                |
+| `--step-separator-width`                       | `50px`              | width            | Width of the separator line.                 |
+| `--step-separator-margin`                      | `0px 12px 0px 12px` | margin           | Margin around the separator.                 |
+| `--step-separator-background-image`            | `repeating-linear-gradient(...)` | background-image | Background image pattern for the step separator line. |
+| `--step-separator-background-image-color`      | `currentColor`      | (gradient color) | Color used in the dashed separator gradient. |
+| `--step-text-margin`                      | `0px 0px 0px 12px`  | margin           | Margin around the step label text.           |
+| `--step-text-font-size`                   | `inherit`           | font-size        | Font size of the step label.                 |
+| `--step-text-color`                       | `inherit`           | color            | Color of the step label text.                |
+
+## Type Reference
+
+Custom types used by this component's props and events:
+
+### Step
+
+```typescript
+type Step = { label: string; icon?: string };
+```
+
+## Web Component
+
+Tag: `<pui-stepper>`
+
+```html
+<pui-stepper current-step-index="1"></pui-stepper>
+```
+
+> **Note:** The `steps` prop is an array — set it via JavaScript property.

package/build/docs/Table.md

@@ -0,0 +1,252 @@
+# Table
+
+A sortable data table with clean, modern defaults. Supports column sorting (ascending/descending) for string, number, and boolean values. Features sticky headers, custom cell rendering via Svelte 5 snippets, row click interaction, and customizable sort icons. Table data is an array of arrays (rows x columns).
+
+## Usage
+
+```svelte
+<script>
+  import { Table } from 'polymorph-ui-components';
+</script>
+
+<Table
+  tableHeaders={['Name', 'Email', 'Role']}
+  tableData={[
+    ['Alice', 'alice@example.com', 'Admin'],
+    ['Bob', 'bob@example.com', 'Editor']
+  ]}
+/>
+```
+
+### Custom Cell Rendering
+
+Use the `cell` snippet to render components (Pills, links, badges) inside cells instead of plain text:
+
+```svelte
+<script>
+  import { Table, Pill } from 'polymorph-ui-components';
+</script>
+
+<Table
+  tableHeaders={['Name', 'Status']}
+  tableData={[
+    ['Alice', 'Active'],
+    ['Bob', 'Inactive']
+  ]}
+>
+  {#snippet cell(value, rowIndex, colIndex)}
+    {#if colIndex === 1}
+      <Pill text={String(value)} classes={value === 'Active' ? 'pill-success' : 'pill-error'} />
+    {:else}
+      {value}
+    {/if}
+  {/snippet}
+</Table>
+```
+
+### Sticky Header
+
+Use `stickyHeader` to keep headers fixed while scrolling. Works with `isTableScrollable` (table's own scroll area) or a parent scroll container.
+
+```svelte
+<Table
+  stickyHeader
+  isTableScrollable
+  tableHeaders={['Name', 'Score']}
+  tableData={largeDataset}
+  --table-container-height="400px"
+/>
+```
+
+### Custom Sort Icons
+
+Replace the default SVG chevron icons with custom snippets:
+
+```svelte
+<Table tableHeaders={['Name', 'Score']} tableData={data}>
+  {#snippet sortAscIcon()}<span>↑</span>{/snippet}
+  {#snippet sortDescIcon()}<span>↓</span>{/snippet}
+  {#snippet sortDefaultIcon()}<span>↕</span>{/snippet}
+</Table>
+```
+
+### Per-Column Widths
+
+Control individual column widths via CSS using the `classes` prop and `nth-child` selectors:
+
+```css
+/* app.css */
+.my-table th:nth-child(1),
+.my-table td:nth-child(1) {
+  width: 200px;
+}
+.my-table th:nth-child(2),
+.my-table td:nth-child(2) {
+  width: 30%;
+}
+.my-table th:nth-child(3),
+.my-table td:nth-child(3) {
+  width: 100px;
+}
+```
+
+```svelte
+<Table classes="my-table" tableHeaders={['Name', 'Email', 'Role']} tableData={data} />
+```
+
+For a uniform column width across all columns, use the `--table-column-width` CSS variable instead.
+
+### Empty State
+
+Show a placeholder when `tableData` is empty:
+
+```svelte
+<Table tableHeaders={['Name', 'Email']} tableData={[]}>
+  {#snippet empty()}
+    <p>No records found.</p>
+  {/snippet}
+</Table>
+```
+
+## Props
+
+| Prop                | Type                                   | Required | Default          | Description                                                                                                                                                            |
+| ------------------- | -------------------------------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| tableTitle          | `string \| null`                       | No       | `''`             | Optional title text displayed above the table.                                                                                                                         |
+| tableHeaders        | `string[]`                             | No       | `[]`             | Array of column header strings. Each header is clickable for sorting (when sortable).                                                                                  |
+| tableData           | `Array<TableCellValue[]>`              | No       | `[]`             | Array of row arrays. Each row is an array of cell values (string, number, or boolean). Columns correspond to tableHeaders by index.                                    |
+| sortable            | `boolean`                              | No       | `true`           | When false, disables sorting on all columns. Sort buttons are hidden.                                                                                                  |
+| sortableColumns     | `number[]`                             | No       | `-`              | Array of column indices that are sortable. When provided, only these columns show sort buttons. Other columns are non-sortable regardless of the `sortable` prop.      |
+| stickyHeader        | `boolean`                              | No       | `false`          | When true, the header row sticks to the top during scroll. Works with `isTableScrollable` or any parent scroll container. Offset via `--table-header-sticky-top`.      |
+| isTableScrollable   | `boolean`                              | No       | `false`          | When true, creates a bounded scroll area on the table container. Headers are automatically sticky. Use `--table-container-height` to set the scroll area height.       |
+| isContentScrollable | `boolean`                              | No       | `false`          | When true, individual cell content scrolls vertically if it overflows the fixed cell height.                                                                           |
+| testId              | `string`                               | No       | `-`              | Value for the data-pw attribute on the table container, used for end-to-end testing selectors.                                                                         |
+| caption             | `string`                               | No       | `-`              | Accessible caption for screen readers. Rendered as a visually hidden `<caption>` element.                                                                              |
+| sortAscIcon         | `Snippet`                              | No       | SVG chevron up   | Custom snippet rendered for the ascending sort indicator.                                                                                                              |
+| sortDescIcon        | `Snippet`                              | No       | SVG chevron down | Custom snippet rendered for the descending sort indicator.                                                                                                             |
+| sortDefaultIcon     | `Snippet`                              | No       | SVG chevron pair | Custom snippet rendered for columns that haven't been sorted yet. Default is a dimmed up/down chevron pair.                                                            |
+| cell                | `Snippet<[TableCellValue, number, number]>` | No  | `-`              | Custom cell renderer. Receives `(value, rowIndex, colIndex)`. When not provided, cells render the raw value as text.                                                   |
+| empty               | `Snippet`                              | No       | `-`              | Content to show when `tableData` is empty. Rendered inside a full-width table row.                                                                                     |
+| 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                                                                                       |
+| ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| onrowclick | `(rowIndex: number, rowData: TableCellValue[]) => void`   | Fires when a data row is clicked. The row becomes focusable and keyboard-navigable when provided. |
+| onsort     | `(columnIndex: number, direction: SortDirection) => void` | Fires after a column sort is toggled. `direction` is `'asc'` or `'desc'`.                         |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+### Title
+
+| Variable                    | Default      | CSS Property | Description                     |
+| --------------------------- | ------------ | ------------ | ------------------------------- |
+| `--table-title-margin`      | `0px 0px 12px 0px` | margin       | Margin around the table title.  |
+| `--table-title-font-size`   | `18px`       | font-size    | Font size of the table title.   |
+| `--table-title-font-weight` | `600`        | font-weight  | Font weight of the table title. |
+| `--table-title-color`       | `currentColor` | color      | Text color of the table title.  |
+| `--table-title-font-family` | `-`          | font-family  | Font family of the table title. |
+| `--table-title-padding`     | `-`          | padding      | Padding of the table title.     |
+
+### Container & Layout
+
+| Variable                   | Default             | CSS Property    | Description                                                        |
+| -------------------------- | ------------------- | --------------- | ------------------------------------------------------------------ |
+| `--table-border`           | `1px solid currentColor` | border          | Border of the table container.                                     |
+| `--table-border-radius`    | `8px`               | border-radius   | Border radius of the table container.                              |
+| `--table-container-width`  | `100%`              | width           | Width of the table container.                                      |
+| `--table-container-height` | `143px`             | height          | Height of the scrollable table container (when isTableScrollable). |
+| `--table-width`            | `100%`              | width           | Width of the table element.                                        |
+| `--table-border-collapse`  | `collapse`          | border-collapse | Border collapse mode of the table.                                 |
+
+### Cell Grid
+
+| Variable                     | Default             | CSS Property  | Description                                                                                                |
+| ---------------------------- | ------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
+| `--table-inner-border`       | `none`              | border        | Border of individual table cells. Set to `1px solid #ccc` for full grid.                                   |
+| `--table-row-border`         | `1px solid #e4e4e7` | border-bottom | Border on the bottom of each data row. Subtle row separators.                                              |
+| `--table-row-last-border`    | `none`              | border-bottom | Border on the last data row. Set to match `--table-row-border` if needed.                                  |
+| `--table-padding`            | `12px 16px`         | padding       | Padding inside table cells.                                                                                |
+| `--table-text-align`         | `left`              | text-align    | Text alignment inside table cells.                                                                         |
+| `--table-column-width`       | `-`                 | width         | Sets a uniform width for all table columns. Unset lets the table auto-size columns.                        |
+| `--table-scrollable-column-height` | `20px`              | height        | Height of scrollable cell content (when isContentScrollable).                                              |
+
+### Header Cells
+
+| Variable                        | Default   | CSS Property     | Description                                                                      |
+| ------------------------------- | --------- | ---------------- | -------------------------------------------------------------------------------- |
+| `--table-header-background`     | `transparent` | background-color | Background color of header cells. Falls back to `--table-header-border-bgcolor`. |
+| `--table-header-font-size`      | `14px`    | font-size        | Font size of header cells.                                                       |
+| `--table-header-font-family`    | `-`       | font-family      | Font family of header cells.                                                     |
+| `--table-header-font-weight`    | `600`     | font-weight      | Font weight of header cells.                                                     |
+| `--table-header-letter-spacing` | `0.02em`  | letter-spacing   | Letter spacing of header text.                                                   |
+| `--table-header-text-transform` | `-`       | text-transform   | Text transform of header cells (e.g. `uppercase`, `capitalize`).                 |
+| `--table-header-color`          | `currentColor` | color            | Text color of header cells. Falls back to `--table-header-font-color`.           |
+| `--table-header-sticky-top`     | `0`       | top              | Top offset for sticky headers. Use when a fixed navbar is above the table.       |
+
+### Data Cells
+
+| Variable                      | Default   | CSS Property     | Description                                                                     |
+| ----------------------------- | --------- | ---------------- | ------------------------------------------------------------------------------- |
+| `--table-content-background`  | `-`       | background-color | Background color of data cells. Falls back to `--table-content-border-bgcolor`. |
+| `--table-content-font-size`   | `14px`    | font-size        | Font size of data cells.                                                        |
+| `--table-content-font-family` | `-`       | font-family      | Font family of data cells.                                                      |
+| `--table-content-color`       | `currentColor` | color            | Text color of data cells. Falls back to `--table-content-font-color`.           |
+
+### Rows
+
+| Variable                       | Default   | CSS Property     | Description                                                                                  |
+| ------------------------------ | --------- | ---------------- | -------------------------------------------------------------------------------------------- |
+| `--table-row-background`       | `-`       | background-color | Background color of data rows.                                                               |
+| `--table-row-alt-background`   | `-`       | background-color | Background of even-numbered rows for striped effect. Falls back to `--table-row-background`. |
+| `--table-row-hover-background` | `-`       | background-color | Background color of data rows on hover.                                                      |
+| `--table-focus-outline-color`  | `currentColor` | outline          | Outline color for focused clickable rows.                                                    |
+
+### Sort Controls
+
+| Variable                               | Default            | CSS Property     | Description                                       |
+| -------------------------------------- | ------------------ | ---------------- | ------------------------------------------------- |
+| `--table-sort-button-color`            | `inherit`          | color            | Color of the sort button icon.                    |
+| `--table-sort-button-hover-color`      | `-`                | color            | Color of the sort button icon on hover.           |
+| `--table-sort-button-hover-background` | `rgba(0,0,0,0.05)` | background-color | Background of the sort button on hover.           |
+| `--table-sort-icon-size`               | `14px`             | width, height    | Size of the sort indicator SVG icons.             |
+| `--table-sort-idle-opacity`            | `0.3`              | opacity          | Opacity of the default (unsorted) sort indicator. |
+
+### Empty State
+
+| Variable                | Default     | CSS Property | Description                             |
+| ----------------------- | ----------- | ------------ | --------------------------------------- |
+| `--table-empty-padding` | `32px 24px` | padding      | Padding around the empty state content. |
+| `--table-empty-color`   | `currentColor` | color        | Text color of the empty state content.  |
+
+## Type Reference
+
+```typescript
+type SortDirection = 'asc' | 'desc';
+
+type TableCellValue = string | number | boolean | null | Record<string, unknown> | unknown[];
+```
+
+## Web Component
+
+Tag: `<pui-table>`
+
+```html
+<pui-table table-title="Users" sortable sticky-header>
+  <div slot="empty">No data found</div>
+</pui-table>
+```
+
+### Slots
+
+| Slot Name           | Maps to Snippet   | Description                               |
+| ------------------- | ----------------- | ----------------------------------------- |
+| `empty`             | `empty`           | Content shown when the table has no data. |
+| `sort-asc-icon`     | `sortAscIcon`     | Custom ascending sort icon.               |
+| `sort-desc-icon`    | `sortDescIcon`    | Custom descending sort icon.              |
+| `sort-default-icon` | `sortDefaultIcon` | Custom default (unsorted) sort icon.      |
+
+> **Note:** `tableHeaders`, `tableData`, and `sortableColumns` are arrays — set them via JavaScript properties. The `cell` snippet is parameterized and only available via JavaScript.