@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/wm-progress-monitor.md

@@ -0,0 +1,27 @@
+# `wm-progress-monitor`
+
+Container for one or more wm-progress-indicator elements, each showing binary completion
+progress (e.g. "Completed" vs "Not Completed"). Above the layout breakpoint, indicators
+render as doughnuts in a horizontal row; below it, they collapse into horizontal bars in a
+vertical stack.
+
+**Strict constraints:**
+1. Each wm-progress-indicator must have EXACTLY TWO wm-progress-slice children -- one for
+   the "complete" state and one for the "incomplete" state.
+2. This component is ONLY suitable for binary completion tracking. For more than two states,
+   general comparisons, composition breakdowns, or distributions, use wm-chart,
+   wm-chart-bar, or wm-chart-column.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `barLabelsWidth` | `bar-labels-width` | `string \| undefined` |  |  |  |
+| `breakpoint` | `breakpoint` | `number \| string \| undefined` |  |  |  |
+| `groupLegend` | `group-legend` | `string \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmProgressMonitorModeChange` | `any` | ✓ |  |

package/dist/docs/wm-progress-slice.md

@@ -0,0 +1,16 @@
+# `wm-progress-slice`
+
+Data slice for a wm-progress-indicator. Represents one state (complete or incomplete) in
+a binary progress chart. Always used as a direct child of wm-progress-indicator.
+
+Each wm-progress-indicator must contain EXACTLY TWO wm-progress-slice elements.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `amount` | `amount` | `string \| undefined` |  |  |  |
+| `legend` | `legend` | `string \| undefined` |  |  |  |
+| `popoverButtonText` | `popover-button-text` | `string \| undefined` |  |  |  |
+| `popoverText` | `popover-text` | `string \| undefined` |  |  |  |
+| `popoverTitle` | `popover-title` | `string \| undefined` |  |  |  |

package/dist/docs/wm-search.md

@@ -0,0 +1,119 @@
+# `wm-search`
+
+Search input for filtering data by query. Two variants: `'basic'` for simple text
+filtering, and `'find'` which adds prev/next result navigation buttons, a result count
+("x of y results"), and a keyboard-accessible "jump to result" link. The component does
+not filter data itself -- it exposes the user's query and result position via events and
+properties for the application to handle.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `highlightedId` | `highlighted-id` | `string` | `""` | Required when `search-type="find"`. |  |
+| `highlightedName` | `highlighted-name` | `null \| string` | `null` | Required when `search-type="find"`. |  |
+| `label` | `label` | `string` | `""` |  |  |
+| `numResults` | `num-results` | `number` | `0` |  |  |
+| `placeholder` | `placeholder` | `string` | `""` |  |  |
+| `searchType` | `search-type` | `"basic" \| "find"` | `"basic"` |  |  |
+| `value` | `value` | `string` | `""` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmSearchBrowseResults` | `{ position: number; }` | ✓ |  |
+| `wmSearchValueChanged` | `{ value: string; }` | ✓ |  |
+
+## Methods
+
+### `updateValue(value: string) => Promise<void>`
+
+**Parameters**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `value` | `string` |  |
+
+**Returns** `Promise<void>`
+
+## Depends On
+
+- `wm-button`
+
+# wm-search
+
+## Purpose
+
+A text input purpose-built for filtering or locating content in real time, with two variants: a basic filter that returns matching results as the user types, and a find variant that lets users step through highlighted matches one at a time.
+
+---
+
+## When to Use
+
+- **Instantly filtering a visible dataset as the user types** -- use the basic variant when the user is narrowing down a list, table, or set of cards and expects the content to respond immediately to their query. Ideal for smaller datasets where results update without performance concerns.
+- **Locating and stepping through matches within a page or document** -- when the user needs to jump between individual matches (like a browser's find function), use the find variant, which provides previous/next navigation and an "x of y results" count.
+- **Including search as part of a filter toolbar** -- Search is a valid data input for toolbar and side panel filter patterns when users have a clear idea of what they're looking for and the dataset is large enough that browsing alone is not practical.
+- **Combining search with other filter inputs** -- Search pairs naturally with dropdowns, date pickers, and tag inputs in a toolbar or side panel; it narrows by text while other inputs narrow by category, date, or attribute simultaneously.
+
+---
+
+## Do Not Use For
+
+- **Collecting a stored form value** -- Search is not a form input; it filters or locates content dynamically. If the user is typing a value to be saved as data (a name, identifier, or description), use wm-input instead.
+- **Very large datasets with the basic variant without considering performance** -- instant filtering for large datasets may cause performance issues; consider a batch-apply approach with an explicit apply action instead.
+- **Exploratory filtering where users do not have a specific target** -- Search is best when the user has a clear idea of what they want; for browsing by category or attribute, dropdowns and selects are more appropriate.
+
+---
+
+## Related Components
+
+- `<wm-input>` -- if the user is typing a value to store as form data rather than to filter visible content, use Input; Search has no form submission semantics.
+- `<wm-select>` with search property -- if the user is searching within a bounded dropdown list of options to make a selection, use Select's built-in search; `<wm-search>` is for filtering page-level content, not for narrowing selectable options.
+- `<wm-tag-input>` -- if the user needs to search and then commit multiple selected values as discrete tags, Tag Input combines search-style filtering with multi-value selection; `<wm-search>` alone has no concept of committed selected values.
+
+---
+
+## Accessibility
+
+- Wiring to the change event: Search emits on input (as the user types), not change; wiring to the wrong event means filtering will not respond until the user commits the value, breaking the real-time interaction model.
+
+---
+
+## Variants / Types
+
+- `search-type="basic"` -- simple filter that updates results in real time as the user types
+- `search-type="find"` -- search-and-find with previous/next result navigation and a result count display; requires num-results, highlighted-id, and highlighted-name to be kept in sync
+
+---
+
+## Props
+
+- `label` -- required for accessibility; the accessible name announced by screen readers
+- `placeholder` -- placeholder text shown when the field is empty
+- `value` -- the current input value; also settable programmatically via updateValue()
+- `searchType` -- "basic" or "find"
+- `numResults` -- the count of matching results; displayed in the UI and announced by screen readers
+- `highlightedId` -- the ID of the currently highlighted result in the find variant
+- `highlightedName` -- the name/label of the currently highlighted result
+- `disabled` -- disables the search input
+
+---
+
+## Events
+
+- `wmSearchValueChanged` -- fires as the user types; detail includes { value: string }
+- `wmSearchBrowseResults` -- fires when the user activates previous/next navigation in the find variant; detail includes { position: number }
+
+---
+
+## Methods
+
+- `updateValue(value: string)` -- programmatically sets the input value
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-select.md

@@ -0,0 +1,120 @@
+# `wm-select`
+
+Dropdown list of options that allows single or multi-select. Functionally similar to the
+native HTML `<select>` element but with Ripple styling and richer features including
+multiselect, search filtering, and a Select All control. Composed of a parent wm-select
+element and wm-option children.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `allSelectedMessage` | `all-selected-message` | `string` | `selectMessages.allSelected` |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `info` | `info` | `string \| undefined` |  |  |  |
+| `label` | `label` | `string \| undefined` |  |  |  |
+| `labelPosition` | `label-position` | `"left" \| "none" \| "top"` | `"top"` |  |  |
+| `maxHeight` | `max-height` | `string` | `"200px"` |  |  |
+| `multiple` | `multiple` | `boolean` | `false` |  |  |
+| `placeholder` | `placeholder` | `string` | `selectMessages.multiPlaceholder` |  |  |
+| `requiredField` | `required-field` | `boolean` | `false` |  |  |
+| `search` | `search` | `boolean` | `false` |  |  |
+| `searchPlaceholder` | `search-placeholder` | `string` | `selectMessages.searchPlaceholder` |  |  |
+| `selectAll` | `select-all` | `boolean` | `false` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmSelectAllDeselected` | `any` | ✓ |  |
+| `wmSelectAllSelected` | `any` | ✓ |  |
+| `wmSelectBlurred` | `void` | ✓ |  |
+| `wmSelectDidLoad` | `void` | ✓ |  |
+
+## Depends On
+
+- `priv-option-list`
+
+# wm-select
+
+## Purpose
+
+A dropdown component that lets users select one or more values from a flat list of options, storing the result as a form field value rather than triggering an action.
+
+---
+
+## When to Use
+
+- **Choosing a single value from a known, bounded list** -- when a user needs to pick exactly one option from a fixed set (e.g., selecting a term, role, or status), use the default single-select variant to record that choice as a form value.
+- **Selecting multiple values from a flat list** -- when a user can choose more than one option from an unstructured set, use the multiple property, optionally with select-all for bulk selection convenience.
+- **Filtering a manageable option set by typing** -- when the list has up to 50 options and scanning is impractical, use the search property to let users narrow options by typing rather than scrolling.
+- **Displaying supplementary context alongside options** -- when each option benefits from a short secondary label (e.g., a code, count, or category hint), use the subinfo property on wm-option to show italicized supporting text inline.
+
+---
+
+## Do Not Use For
+
+- **Categorized options** -- if the option set has a meaningful group structure, use wm-nested-select instead; Select only supports a single flat list.
+- **Selecting an option that triggers an action** -- if selecting an item should immediately execute something, use wm-action-menu's selector variant, not Select.
+- **More than 50 options in search mode** -- the search variant is intended for 50 or fewer options; beyond that, it creates usability and potential performance problems.
+- **Single Select with no pre-selected option** -- single Select must always have a selected value; if no default exists, the first option must explicitly represent a null state using only approved language ("None", "Select an option", or "--").
+
+---
+
+## Related Components
+
+- `<wm-nested-select>` -- if the options have a two-level category structure, use Nested Select; if they are a single flat list, use Select.
+- `<wm-action-menu>` (selector type) -- if picking an option should immediately execute an action rather than record a value, use Action Menu's selector type, not Select.
+- `<wm-tag-input>` -- if the user needs to select or create values displayed as removable tags (e.g., adding people or labels), Tag Input is likely the better fit over multi-select Select.
+
+---
+
+## Accessibility
+
+_Not documented_
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `label` -- required even when label-position="none"
+- `labelPosition` -- "top", "left", or "none"
+- `multiple` -- enables multi-selection
+- `selectAll` -- adds a bulk-select option; intended for use with multiple
+- `search` -- adds a type-ahead search field to filter options; intended for lists of 50 or fewer options
+- `searchPlaceholder` -- placeholder text for the search input
+- `placeholder` -- placeholder text shown in the trigger when no value is selected
+- `allSelectedMessage` -- message shown in the trigger when all options are selected
+- `info` -- supplementary context shown alongside the label
+- `errorMessage` -- validation error text displayed below the control
+- `requiredField` -- marks the field as required
+- `disabled` -- disables the control and prevents interaction
+- `maxHeight` -- sets the max height of the open dropdown panel
+
+---
+
+## Events
+
+- `wmSelectAllDeselected` -- fires when all options are deselected
+- `wmSelectAllSelected` -- fires when all options are selected
+- `wmSelectBlurred` -- fires when the control loses focus
+- `wmSelectDidLoad` -- fires when the component finishes loading
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-snackbar.md

@@ -0,0 +1,87 @@
+# `wm-snackbar`
+
+Toast notification stack that renders transient messages at the bottom of the page.
+Notifications auto-dismiss after 6 seconds unless they include a `link` or `action`, in
+which case they persist until explicitly dismissed or the user tabs past them.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `notifications` | `notifications` | `string` | `"[]"` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmSnackbarActionTriggered` | `Object` | ✓ |  |
+| `wmSnackbarSnackFinished` | `Object` | ✓ |  |
+
+# wm-snackbar
+
+## Purpose
+
+A lightweight, self-dismissing notification that appears at the bottom of the screen to confirm that a user-initiated action completed successfully, without interrupting or blocking the current workflow.
+
+---
+
+## When to Use
+
+- **Confirming the successful completion of a user action** -- when a user submits a form, uploads a file, adds or removes an item, or saves changes and the result is not immediately visible on screen, use a Snackbar to close the feedback loop with a brief confirmation message.
+- **Providing a link to the result of a completed action** -- when the action produces something the user might want to navigate to immediately (e.g., a newly created record), use a Snackbar with a link to offer that shortcut without forcing navigation.
+- **Offering a quick undo after an action** -- when a reversible action has just been taken, use a Snackbar with an action button (e.g., "Undo") to give the user a brief window to reverse it without a confirmation step.
+- **Consolidating rapid successive notifications** -- when multiple similar actions fire in quick succession (under 6 seconds), use a single Snackbar summarizing them (e.g., "3 items updated") rather than stacking individual notifications per action.
+
+---
+
+## Do Not Use For
+
+- **Actions whose result is immediately visible** -- if the outcome is already visible in the interface (an item appears in a list, a field updates inline), a Snackbar adds noise without adding information; skip it.
+- **Every minor or intuitive action** -- routine, low-stakes interactions do not warrant a notification and will overwhelm users over time if over-triggered.
+- **Essential information or links the user must act on** -- because Snackbars auto-dismiss after 6 seconds, any message or action the user genuinely needs to see should be in a Dialog or banner instead; Snackbar content must always be findable elsewhere in the interface.
+- **Triggering other containers or including more than one link** -- Snackbars should not launch other layout containers or inputs, and are limited to a single link; it is a terminal notification, not a launching point.
+
+---
+
+## Related Components
+
+- Dialog -- if the message requires the user to make a decision or acknowledge something before continuing, use Dialog; Snackbar is for passive confirmations that do not require a response.
+- Banner -- if the message is tied to a persistent system status, an error the user must fix, or information that needs to stay visible until resolved, use a banner; Snackbar is for transient, action-completion feedback only.
+- `<wm-toggletip>` -- if contextual information needs to be available on demand near a specific element rather than as a system notification, use Toggletip; Snackbar is not a help or hint mechanism.
+
+---
+
+## Accessibility
+
+_Not documented_
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `notifications` -- a JSON string of Notification[] objects; this single prop drives all Snackbar content including message text, optional link, optional action button, and display duration
+
+---
+
+## Events
+
+- `wmSnackbarActionTriggered` -- fires when the user activates the optional action button (e.g., "Undo")
+- `wmSnackbarSnackFinished` -- fires when a notification has been dismissed (by user or auto-dismiss timeout)
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-tab-item.md

@@ -0,0 +1,23 @@
+# `wm-tab-item`
+
+Individual tab button inside a wm-tab-list. Renders as a link with `role="tab"` and
+manages selection state. Always used as a direct child of wm-tab-list.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `selected` | `selected` | `boolean` | `false` |  |  |
+| `tabId` | `tab-id` | `string` | `""` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmTabSelected` | `{ tabId: string; }` | ✓ |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | The visible label text for the tab. |

package/dist/docs/wm-tab-list.md

@@ -0,0 +1,98 @@
+# `wm-tab-list`
+
+Tab list container that manages a group of wm-tab-item children and their associated
+wm-tab-panel elements. Handles keyboard navigation, ARIA wiring between tabs and panels,
+horizontal scroll with arrow buttons on overflow, and optional dark theme.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `customBackground` | `custom-background` | `"" \| "dark" \| undefined` |  |  |  |
+| `selectedTab` | `selected-tab` | `string \| undefined` |  |  |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | One or more wm-tab-item elements. |
+
+## Depends On
+
+- `wm-button`
+
+# wm-tab-list + wm-tab-item + wm-tab-panel
+
+## Purpose
+
+A within-page navigation pattern that divides related content into labeled sections, letting users switch between views without leaving their current context or navigating to a new page.
+
+---
+
+## When to Use
+
+- **Organizing related content into parallel sections within a page** -- when a page or container holds distinct but related content areas that do not all need to be visible at once (e.g., Overview, Details, History on a record page), use Tabs to present them as switchable views with short, clear labels.
+- **Breaking up content within a layout container** -- Tabs are usable inside primary pages, immersive layouts, Flyouts, and side panels; use them whenever a container has enough content variety to warrant sub-sections without adding navigation overhead.
+
+---
+
+## Do Not Use For
+
+- **Primary navigation between pages** -- Tabs should not be used as primary navigation; they are for switching sections within a single page or container. Cross-page navigation belongs in wm-navigation.
+- **More tabs than fit in a single row** -- all tabs should be visible on one row; if there are too many, the content should be simplified or a different pattern considered.
+- **Sequential steps that must be completed in order** -- Tabs imply free switching between any section at any time; if the user must complete steps in sequence, a stepper pattern is more appropriate.
+
+---
+
+## Related Components
+
+- `<wm-navigation>` -- if the purpose is navigating between separate pages or top-level product areas, use Navigation; Tabs are strictly for switching views within a single page or container context.
+- `<wm-pagination>` -- if the user is moving through pages of a dataset rather than switching between content sections, use Pagination; Tabs are not a data paging mechanism.
+- Stepper pattern -- if the content sections represent sequential steps that must be completed in order, use a stepper; Tabs allow unrestricted movement between sections and carry no sense of progress or completion state.
+
+---
+
+## Accessibility
+
+- Controlling which tab is active on initial load: when the application needs to open to a specific tab by default or in response to a URL parameter or state, use selected-tab on wm-tab-list to set the initially active tab declaratively.
+- Conditionally rendering content vs. using discrete panels: when tab content is heavy and should only load when needed, render a single wm-tab-panel and update its content in response to wmTabSelected; when lightweight, give each tab its own wm-tab-panel and swap visibility via the active prop.
+- Containers with unset width: the component determines available space by checking its parent's width; if the container width is unset, it sizes to content and the tab layout will produce unpredictable behavior. The container should almost always be width: 100%.
+
+---
+
+## Variants / Types
+
+- `customBackground="dark" (on wm-tab-list)` -- applies a dark background variant to the tab bar
+
+---
+
+## Props
+
+- wm-tab-list props:
+- `selectedTab` -- the tabId of the tab that should be active on initial render
+- `customBackground` -- "dark" applies a dark background variant
+- wm-tab-item props:
+- `tabId` -- required; links this tab trigger to its corresponding wm-tab-panel by matching ID
+- `selected` -- marks this tab as the initially selected tab
+- wm-tab-panel props:
+- `tabId` -- required; links this panel to its corresponding wm-tab-item by matching ID
+- `active` -- controls whether this panel's content is visible
+- `CRITICAL: Do NOT put bare <button> elements inside wm-tab-list` -- only wm-tab-item children are valid.
+
+---
+
+## Events
+
+- `wmTabSelected (on wm-tab-item)` -- fires when a tab is activated; detail includes { tabId: string }
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-tab-panel.md

@@ -0,0 +1,18 @@
+# `wm-tab-panel`
+
+Content panel associated with a wm-tab-item. Shows or hides based on whether its
+`tab-id` matches the selected tab in the parent wm-tab-list. Rendered with
+`role="tabpanel"`. Always used alongside a wm-tab-list.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `active` | `active` | `boolean` | `false` |  |  |
+| `tabId` | `tab-id` | `string` | `""` |  |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | The panel content to display when this tab is active. |

package/dist/docs/wm-tag-input.md

@@ -0,0 +1,123 @@
+# `wm-tag-input`
+
+Input for selecting or creating a list of tags. Two variants: `'dropdown'` (options in a
+filterable list, supports creating new tags) and `'table'` (options in a filterable
+multi-column table). Options are defined as wm-tag-option children. Selected options appear
+as removable tags above the search field.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `addNew` | `add-new` | `boolean` | `true` |  |  |
+| `characterLimit` | `character-limit` | `number` | `50` |  |  |
+| `colHeaders` | `col-headers` | `string` |  | ✓ |  |
+| `colWidths` | `col-widths` | `string \| undefined` |  |  |  |
+| `colWrap` | `col-wrap` | `string \| undefined` |  |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `helpText` | `help-text` | `string \| undefined` |  |  |  |
+| `info` | `info` | `string \| undefined` |  |  |  |
+| `label` | `label` | `string` |  | ✓ |  |
+| `labelPosition` | `label-position` | `"left" \| "none" \| "top"` | `"top"` |  |  |
+| `maxTags` | `max-tags` | `number \| undefined` |  |  |  |
+| `placeholder` | `placeholder` | `string \| undefined` |  |  |  |
+| `requiredField` | `required-field` | `boolean` | `false` |  |  |
+| `tagInputType` | `tag-input-type` | `"dropdown" \| "table"` | `"dropdown"` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmTagInputTagAdded` | `any` | ✓ |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | One or more wm-tag-option children. |
+
+# wm-tag-input
+
+## Purpose
+
+A multi-value selection input that lets users search for and commit multiple options as removable tags, with a dropdown variant for selecting or creating simple values and a table variant for selecting from richer, multi-column option sets.
+
+---
+
+## When to Use
+
+- **Selecting multiple values from a large, searchable list** -- use Tag Input when the option set is too long to scan in a flat multi-select dropdown but users know roughly what they are looking for; best for selecting a few options from a large searchable list.
+- **Allowing users to create new values on the fly** -- when valid values are not fully predefined and users may need to introduce new entries (e.g., new skill labels, keywords, or categories), use the dropdown variant with add-new="true".
+- **Selecting from options that have multiple attributes** -- when each option carries more context than a single label (e.g., a person's name, email, and role), use the table variant to display each option as a multi-column row.
+- **Enforcing a cap on how many values can be selected** -- when the field has a meaningful limit (e.g., "select up to 5 reviewers"), use max-tags to surface a running count and a limit-reached message.
+
+---
+
+## Do Not Use For
+
+- **Small, fully known option sets** -- if the list is short and bounded with no need for search or free entry, use wm-select with multiple instead; Tag Input's search and creation overhead adds complexity without benefit.
+- **Single-value fields** -- if only one value can be selected, Tag Input's tag-area model and two-tab-stop structure are unnecessary; use wm-select or wm-input for single-value cases.
+
+---
+
+## Related Components
+
+- `<wm-select>` with multiple -- if the option set is small, fully known, and does not benefit from search or free entry, use multi-select Select; Tag Input's extra capabilities add complexity not warranted for simple bounded lists.
+- `<wm-search>` -- if the goal is to filter visible page content as the user types rather than commit selected values to a form, use Search; Tag Input accumulates stored values, not a real-time content filter.
+- `<wm-input>` -- if the user is entering a single free-form string rather than selecting or creating multiple discrete values, use Input; Tag Input is only appropriate when the field holds a collection.
+
+---
+
+## Accessibility
+
+- The table variant without ensuring the input field remains visible: the input field must always remain visible while the user interacts; overriding the max-height in a way that hides the input breaks the interaction model.
+- Hard-enforcing a tag count limit via max-tags alone: the component does not enforce max-tags and will still emit events when the limit is reached; the application must implement its own enforcement logic for a truly hard cap.
+
+---
+
+## Variants / Types
+
+- `tag-input-type="dropdown"` -- users search for and select from a flat list; supports add-new to allow creation of new values
+- `tag-input-type="table"` -- users select from a multi-column option list; requires col-headers and options use col1-col4 props on wm-tag-option
+
+---
+
+## Props
+
+- wm-tag-input props:
+- `label` -- required; accessible name even when label-position="none"
+- `labelPosition` -- "top", "left", or "none"
+- `tagInputType` -- "dropdown" or "table"
+- `addNew` -- when true on the dropdown variant, allows users to commit a typed value that does not exist in the list
+- `maxTags` -- displays a running count and a limit-reached message; informational only -- the application must enforce the hard limit
+- `characterLimit` -- maximum character length for the search field entry
+- `placeholder` -- placeholder text for the search input
+- `colHeaders` -- required for the table variant; comma-separated column headers
+- `colWidths` -- optional column width overrides for the table variant
+- `colWrap` -- controls text wrapping behavior in table columns
+- `info` -- supplementary helper text
+- `helpText` -- additional guidance text
+- `errorMessage` -- validation error text
+- `requiredField` -- marks the field as required
+- wm-tag-option props (child):
+- `selected` -- marks this option as pre-selected when the component loads
+- `locked` -- prevents the user from removing this tag once selected
+- `col1-col4` -- column values for the table variant
+
+---
+
+## Events
+
+- `wmTagInputTagAdded` -- fires when a tag is committed (selected from the list or created via add-new)
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-tag-option.md

@@ -0,0 +1,33 @@
+# `wm-tag-option`
+
+Option element for wm-tag-input. Represents a selectable tag in the dropdown list or
+table. Always used as a direct child of wm-tag-input. For the dropdown variant, slotted
+text content is the tag label; for the table variant, use `col1`-`col4` props.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `col1` | `col1` | `string \| undefined` |  |  |  |
+| `col2` | `col2` | `string \| undefined` |  |  |  |
+| `col3` | `col3` | `string \| undefined` |  |  |  |
+| `col4` | `col4` | `string \| undefined` |  |  |  |
+| `locked` | `locked` | `boolean` | `false` |  |  |
+| `selected` | `selected` | `boolean` | `false` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmTagOptionDeselected` | `any` | ✓ |  |
+| `wmTagOptionSelected` | `any` | ✓ |  |
+
+## Methods
+
+### `emitDeselectedEvent() => Promise<void>`
+
+**Returns** `Promise<void>` -- A promise that resolves once the event has been emitted.
+
+### `emitSelectedEvent() => Promise<void>`
+
+**Returns** `Promise<void>` -- A promise that resolves once the event has been emitted.