@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/skill/wm-snackbar.md

@@ -0,0 +1,101 @@
+### Snackbar
+- **Element:** `<wm-snackbar>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `notifications` -- JSON-encoded array of notification objects to display. Each object must
+include `id` (string) and `message` (string). Optional fields: `link` (string, renders
+a navigation anchor), `action` (string, renders a button), `newWindow` (boolean, adds an
+"opens in new window" indicator to the link). Always pass as `JSON.stringify(array)` --
+passing an array directly causes a "[object Object] is not valid JSON" error.
+
+**Events:**
+- `wmSnackbarActionTriggered`
+- `wmSnackbarSnackFinished`
+
+**Accessibility:**
+
+- Renders an `aria-live` region that announces new notification messages to screen readers.
+- When a notification includes a `link` or `action` and the user is navigating by keyboard,
+  focus moves automatically to the action element when the notification appears.
+- Focus returns to the previously active element when the notification is dismissed.
+- **Keyboard:** - **Tab**: Moves focus from the action link/button to the close button; tabbing past the
+  close button dismisses the notification and returns focus to the previously active element.
+- **Shift+Tab**: Dismisses the notification from the action link and returns focus; moves
+  from the close button back to the action link.
+- **Enter**: Activates the focused close button or action link/button.
+
+**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.
+
+**Code example:**
+
+_Simple notification_
+
+```html
+<wm-snackbar notifications='[{"id":"1","message":"Changes saved."}]'></wm-snackbar>
+```
+
+_Notification stack with action and link variants_
+
+```react
+// notifications is typed as string -- always pass JSON.stringify(array), never the array directly.
+// wmSnackbarSnackFinished fires when a notification auto-dismisses or is closed.
+// wmSnackbarActionTriggered fires when the action button or link is clicked;
+// remove the notification manually after handling the action.
+let nextId = 1;
+const [notifications, setNotifications] = useState([]);
+
+const addNotification = (notification) =>
+setNotifications((prev) => [...prev, { id: String(nextId++), ...notification }]);
+
+const removeNotification = (id) =>
+setNotifications((prev) => prev.filter((n) => n.id !== id));
+
+const handleActionTriggered = (e) => {
+const { id, action } = e.detail;
+if (action === "Undo") { handleUndo(); }
+removeNotification(id);
+};
+
+<WmButton buttonType="secondary" onClick={() => addNotification({ message: "Changes saved." })}>
+Simple notification
+</WmButton>
+<WmButton buttonType="secondary" onClick={() => addNotification({ message: "Item deleted.", action: "Undo" })}>
+With action
+</WmButton>
+<WmButton buttonType="secondary" onClick={() => addNotification({ message: "Report ready.", link: "#report" })}>
+With link
+</WmButton>
+
+<WmSnackbar
+notifications={JSON.stringify(notifications)}
+onWmSnackbarSnackFinished={(e) => removeNotification(e.detail.id)}
+onWmSnackbarActionTriggered={handleActionTriggered}
+/>
+```

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

@@ -0,0 +1,35 @@
+### Tab Item
+- **Element:** `<wm-tab-item>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**Variants / types:**
+
+- `tab-id` is required and must match the `tab-id` of the corresponding wm-tab-panel.
+- Listen to `wmTabSelected` and update the `selected-tab` prop on the parent wm-tab-list
+  to switch the active tab and show the associated panel.
+
+**Props:**
+- `selected` -- Whether this tab is currently active. Managed by the parent wm-tab-list --
+do not set manually.
+- `tab-id` -- Unique identifier linking this tab to its associated wm-tab-panel. Must
+match the `tab-id` on the corresponding wm-tab-panel.
+
+**Events:**
+- `wmTabSelected`
+
+**Code example:**
+
+_Tab item_
+
+```html
+<wm-tab-item tab-id="overview">Overview</wm-tab-item>
+```
+
+_Tab item_
+
+```react
+<WmTabItem tabId="overview">Overview</WmTabItem>
+```

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

@@ -0,0 +1,112 @@
+### Tab List
+- **Element:** `<wm-tab-list>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+- `customBackground="dark" (on wm-tab-list)` -- applies a dark background variant to the tab bar
+
+**Props:**
+- `custom-background` -- Sets the visual theme. Pass `"dark"` for the dark theme; omit for the
+default light theme.
+- `selected-tab` -- The `tab-id` of the currently active tab. Update this prop in response to
+`wmTabSelected` to switch tabs. Defaults to the first tab if not set.
+
+**Accessibility:**
+
+- Sets `aria-controls` on each wm-tab-item link pointing to its associated wm-tab-panel.
+- Sets `aria-labelledby` on each wm-tab-panel pointing back to its wm-tab-item link.
+- ARIA attributes are updated dynamically when tab content is conditionally rendered in a
+  single shared panel.
+- **Keyboard:** - **Arrow Left / Arrow Right**: Cycles focus to the previous/next tab item; wraps at both ends.
+- **Arrow Down**: Moves focus to the content area of the active tab panel.
+- **Enter / Space**: Activates the focused tab and shows its panel.
+- **Tab**: Moves focus from the selected tab to the first focusable element inside the
+  active panel.
+- **Shift+Tab**: Moves focus back to the selected tab item from within the panel.
+
+**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.
+
+**Code example:**
+
+_Basic tabs (discrete panels)_
+
+```html
+<wm-tab-list>
+<wm-tab-item tab-id="overview">Overview</wm-tab-item>
+<wm-tab-item tab-id="details">Details</wm-tab-item>
+<wm-tab-item tab-id="history">History</wm-tab-item>
+</wm-tab-list>
+<wm-tab-panel tab-id="overview"><p>Overview content</p></wm-tab-panel>
+<wm-tab-panel tab-id="details"><p>Details content</p></wm-tab-panel>
+<wm-tab-panel tab-id="history"><p>History content</p></wm-tab-panel>
+```
+
+_Basic tabs (discrete panels)_
+
+```react
+// wmTabSelected fires when a tab is clicked or activated via keyboard.
+// event.detail is { tabId: string } -- the tab-id of the newly selected tab.
+const [selectedTab, setSelectedTab] = useState("overview");
+
+<WmTabList selectedTab={selectedTab} onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}>
+<WmTabItem tabId="overview">Overview</WmTabItem>
+<WmTabItem tabId="details">Details</WmTabItem>
+<WmTabItem tabId="history">History</WmTabItem>
+</WmTabList>
+<WmTabPanel tabId="overview"><p>Overview content</p></WmTabPanel>
+<WmTabPanel tabId="details"><p>Details content</p></WmTabPanel>
+<WmTabPanel tabId="history"><p>History content</p></WmTabPanel>
+```
+
+_Single shared panel (content rendered conditionally)_
+
+```html
+<wm-tab-list custom-background="dark">
+<wm-tab-item tab-id="summary">Summary</wm-tab-item>
+<wm-tab-item tab-id="activity">Activity</wm-tab-item>
+</wm-tab-list>
+<wm-tab-panel tab-id="summary">
+<!-- app renders content here based on the active tab -->
+</wm-tab-panel>
+```
+
+_Single shared panel (content rendered conditionally)_
+
+```react
+// One wm-tab-panel shared by all tabs -- ARIA attributes update automatically.
+// Render content conditionally based on selectedTab.
+const [selectedTab, setSelectedTab] = useState("summary");
+
+<WmTabList
+customBackground="dark"
+selectedTab={selectedTab}
+onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}
+>
+<WmTabItem tabId="summary">Summary</WmTabItem>
+<WmTabItem tabId="activity">Activity</WmTabItem>
+</WmTabList>
+<WmTabPanel tabId="summary">
+{selectedTab === "summary" && <p>Summary content</p>}
+{selectedTab === "activity" && <p>Activity content</p>}
+</WmTabPanel>
+```

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

@@ -0,0 +1,33 @@
+### Tab Panel
+- **Element:** `<wm-tab-panel>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**Variants / types:**
+
+- `tab-id` is required and must match the `tab-id` of the corresponding wm-tab-item.
+- For the single-panel conditional-content pattern, use one wm-tab-panel without a
+  `tab-id` -- the parent wm-tab-list updates its ARIA attributes automatically.
+
+**Props:**
+- `active` -- Whether this panel is currently visible. Managed by the parent wm-tab-list --
+do not set manually.
+- `tab-id` -- Unique identifier linking this panel to its associated wm-tab-item. Must
+match the `tab-id` on the corresponding wm-tab-item.
+
+**Code example:**
+
+_Tab panel_
+
+```html
+<wm-tab-panel tab-id="overview">Overview content here.</wm-tab-panel>
+```
+
+_Tab panel_
+
+```react
+<WmTabPanel tabId="overview">Overview content here.</WmTabPanel>
+```

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

@@ -0,0 +1,165 @@
+### Tag Input
+- **Element:** `<wm-tag-input>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**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:**
+- `add-new` -- Dropdown variant only. When true, the user can type a new value and add it
+as a tag by pressing Enter or comma.
+- `character-limit` -- Dropdown variant only. Maximum character limit enforced on the search field.
+- `col-headers` -- Table variant only. Comma-separated list of column header labels. The number
+of headers determines the number of columns. _(required; conditionally required: Required when `tag-input-type="table"`.)_
+- `col-widths` -- Table variant only. Comma-separated column widths. Blank values fill
+remaining space.
+- `col-wrap` -- Table variant only. Comma-separated text-wrapping rules per column -- `'wrap'`
+or `'trunc'` (truncate with tooltip).
+- `error-message` -- Puts the component in an error state and displays this message below the
+field.
+- `help-text` -- Overrides the default instructional help text shown at the top of the
+dropdown (dropdown variant) or below the input when `max-tags` is set (table variant).
+- `info` -- Hint text displayed below the component.
+- `label` -- Accessible name for the search input and dropdown/table. Required even when
+`label-position="none"`. _(required)_
+- `label-position` -- Controls label placement. `'none'` hides the label visually but keeps it
+accessible. `'left'` is not supported in the `table` variant.
+- `max-tags` -- Maximum number of tags allowed. Displays a "Tags added: x/y" counter but
+does not prevent selection beyond the limit -- enforce the limit in your
+`wmTagOptionSelected` or `wmTagInputTagAdded` handler.
+- `placeholder` -- Placeholder text in the search field. Defaults to a generated string based
+on `add-new` and available options.
+- `required-field` -- Displays a required-field asterisk next to the label.
+- `tag-input-type` -- Selects the component variant. `'dropdown'` shows a filterable list;
+`'table'` shows a filterable multi-column table.
+
+**Events:**
+- `wmTagInputTagAdded`
+
+**Accessibility:**
+
+- `label` is the accessible name for the search input and dropdown/table; required even
+  when `label-position="none"`.
+- An `aria-live` region announces tag additions, removals, result counts, and errors.
+- Two tab stops: the tag area (when tags are present) and the search field.
+- **Keyboard:** **Tag area (when tags are present):**
+- **Arrow Left / Arrow Right**: Cycle focus between selected tags.
+- **Backspace / Delete**: Remove the focused tag.
+
+**Search field:**
+- **Arrow Down / Arrow Up**: Open the dropdown or navigate within it.
+- **Enter**: Add a new tag from typed value (dropdown, `add-new` enabled) or select the
+  focused option.
+- **Comma**: Add a new tag immediately (dropdown, `add-new` enabled).
+- **Escape**: Close the dropdown.
+- **Backspace** (empty field): Move focus to the last selected tag.
+
+**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.
+
+**Code example:**
+
+_Dropdown with add-new_
+
+```html
+<wm-tag-input label="Skills" add-new="true">
+<wm-tag-option>JavaScript</wm-tag-option>
+<wm-tag-option>TypeScript</wm-tag-option>
+<wm-tag-option>React</wm-tag-option>
+</wm-tag-input>
+```
+
+_Dropdown with add-new_
+
+```react
+// wmTagOptionSelected/Deselected bubble to WmTagInput for the dropdown variant.
+// You must set event.target.selected imperatively in each handler.
+// wmTagInputTagAdded fires when a new tag is created; event.detail is the tag string.
+// You must create and append a wm-tag-option DOM element with selected=true.
+const handleOptionSelected = (event) => {
+event.target.selected = true;
+setTags((prev) => [...prev, event.target.textContent.trim()]);
+};
+const handleOptionDeselected = (event) => {
+const isUserAdded = event.target.getAttribute('user-added');
+isUserAdded ? event.target.remove() : (event.target.selected = false);
+setTags((prev) => prev.filter((t) => t !== event.target.textContent.trim()));
+};
+const handleTagAdded = (event) => {
+const taginput = event.currentTarget;
+const newTagName = event.detail;
+const existingNames = Array.from(taginput.querySelectorAll('wm-tag-option'))
+.map((o) => o.textContent.toLowerCase().trim());
+if (!existingNames.includes(newTagName.toLowerCase().trim())) {
+const newOption = document.createElement('wm-tag-option');
+newOption.textContent = newTagName;
+newOption.id = 'tag' + Math.random().toString(36).substr(2, 6);
+newOption.selected = true;
+newOption.setAttribute('user-added', 'true');
+taginput.appendChild(newOption);
+setTags((prev) => [...prev, newTagName]);
+}
+};
+
+<WmTagInput label="Skills" addNew={true}
+onWmTagOptionSelected={handleOptionSelected}
+onWmTagOptionDeselected={handleOptionDeselected}
+onWmTagInputTagAdded={handleTagAdded}>
+<WmTagOption>JavaScript</WmTagOption>
+<WmTagOption>TypeScript</WmTagOption>
+<WmTagOption>React</WmTagOption>
+</WmTagInput>
+```
+
+_Table variant_
+
+```html
+<wm-tag-input label="Assign people" tag-input-type="table" col-headers="Name,Department">
+<wm-tag-option col1="Smith, John" col2="Engineering"></wm-tag-option>
+<wm-tag-option col1="Doe, Jane" col2="Design"></wm-tag-option>
+</wm-tag-input>
+```
+
+_Table variant_
+
+```react
+// For the table variant, put handlers on each WmTagOption rather than on WmTagInput.
+// event.target.col1 is the first column value, used as the tag label.
+const makeHandlers = (col1Value) => ({
+onWmTagOptionSelected: (event) => {
+event.target.selected = true;
+setSelected((prev) => [...prev, col1Value]);
+},
+onWmTagOptionDeselected: (event) => {
+event.target.selected = false;
+setSelected((prev) => prev.filter((p) => p !== col1Value));
+},
+});
+
+<WmTagInput label="Assign people" tagInputType="table" colHeaders="Name,Department">
+<WmTagOption col1="Smith, John" col2="Engineering" {...makeHandlers('Smith, John')} />
+<WmTagOption col1="Doe, Jane" col2="Design" {...makeHandlers('Doe, Jane')} />
+</WmTagInput>
+```

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

@@ -0,0 +1,59 @@
+### Tag Option
+- **Element:** `<wm-tag-option>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**Variants / types:**
+
+- Pre-select an option on load by setting `selected`; lock it from removal by setting
+  `locked`.
+- Listen to `wmTagOptionSelected` and `wmTagOptionDeselected` to react to selection
+  changes.
+
+**Props:**
+- `col1` -- First column value for the `table` variant. Also used as the tag label when
+this option is selected.
+- `col2` -- Second column value for the `table` variant.
+- `col3` -- Third column value for the `table` variant.
+- `col4` -- Fourth column value for the `table` variant.
+- `locked` -- When true, the option is permanently selected and cannot be removed by the
+user.
+- `selected` -- Whether this option is currently selected (appears as a tag). Setting this
+on load pre-selects the option.
+
+**Events:**
+- `wmTagOptionDeselected`
+- `wmTagOptionSelected`
+
+**Methods:**
+- `emitDeselectedEvent() => Promise<void>`
+- `emitSelectedEvent() => Promise<void>`
+
+**Code example:**
+
+_Dropdown option_
+
+```html
+<wm-tag-option>JavaScript</wm-tag-option>
+```
+
+_Dropdown option_
+
+```react
+<WmTagOption onWmTagOptionSelected={handleSelect}>JavaScript</WmTagOption>
+```
+
+_Pre-selected option_
+
+```html
+<wm-tag-option selected>TypeScript</wm-tag-option>
+```
+
+_Table option (col1-col4)_
+
+```react
+<WmTagOption col1="Smith, John" col2="Engineering" />
+```

package/dist/docs/skill/wm-textarea.md

@@ -0,0 +1,94 @@
+### Textarea
+- **Element:** `<wm-textarea>`
+- **Status:** stable
+
+**Purpose:** Multi-line plain-text editing control with a drag handle for vertical resizing. Shares
+most functionality with wm-input. Use instead of native `<textarea>` in all Watermark UI.
+
+**When to use:**
+
+- **Collecting a narrative, description, or open-ended response** -- when a user needs to write more than a short phrase (a program description, assessment rationale, comment, or notes field), use Textarea to give them a multi-line editing surface.
+- **Accepting long-form text with a character cap** -- when the field has a meaningful maximum length (e.g., a mission statement capped at 500 characters), use character-limit to display a running count and turn it red at the limit, while still allowing free editing.
+- **Setting an initial height appropriate to the expected content volume** -- when the typical response will be longer or shorter than the default three lines, use input-height to size the field to match user expectations.
+- **Displaying supplementary guidance below the field** -- when the field benefits from a brief instruction that stays visible while the user types, use the info property to show it persistently below the input area.
+
+**Do not use for:**
+
+- **Short, single-line values** -- if the expected value is a name, identifier, number, or any other brief string, use wm-input instead; Textarea signals to users that a longer response is expected and wastes vertical space for short values.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `character-limit` -- Maximum number of characters allowed. Displays a live counter below the
+field. Does not prevent typing beyond the limit (to allow pasting and editing) but the
+counter turns red when exceeded. Disabled when unset.
+- `disabled` -- Disables the component, preventing all interaction.
+- `error-message` -- Puts the component in an error state and displays this message below the
+textarea.
+- `info` -- Hint text displayed below the textarea. Read by screen readers on focus via
+`aria-describedby`.
+- `input-height` -- CSS height value for the initial height of the textarea. The user can resize
+it with the drag handle.
+- `input-width` -- CSS width value for the textarea element itself, independent of the overall
+component width. Useful when the label or error message should extend wider than the
+field.
+- `label` -- Accessible label for the textarea. Required even when
+`label-position="none"`. _(required)_
+- `label-position` -- Controls label placement. `'none'` hides the label visually but keeps it
+accessible.
+- `placeholder` -- Placeholder text shown inside the empty textarea.
+- `required-field` -- Displays a required-field asterisk next to the label.
+- `value` -- The current value typed by the user. Line breaks are represented as `\n`.
+To set an initial value, use the element's text content instead:
+`<wm-textarea>initial value</wm-textarea>`.
+
+**Events:**
+- `wmTextareaValueChanged`
+
+**Accessibility:**
+
+- `label` sets the accessible label for the textarea; required even when
+  `label-position="none"`.
+- When `character-limit` is set, a counter below the field turns red when exceeded; the
+  count is announced via `aria-live` when within 5 characters of the limit or exceeded.
+- Error messages are announced via an `aria-live` region.
+- `info` text is associated via `aria-describedby` and read by screen readers on focus.
+
+**Related components:**
+
+- `<wm-input>` -- if the expected value fits on a single line, use Input; Textarea is only warranted when multi-line content is genuinely expected. The two share nearly identical props, events, and accessibility behavior, the choice is almost entirely single-line vs. multi-line.
+
+**Code example:**
+
+_Basic textarea_
+
+```html
+<wm-textarea label="Notes" placeholder="Enter notes here..."></wm-textarea>
+```
+
+_Basic textarea_
+
+```react
+// value + onWmTextareaValueChanged is the standard controlled pattern.
+const [notes, setNotes] = useState("");
+
+<WmTextarea
+label="Notes"
+placeholder="Enter notes here..."
+value={notes}
+onWmTextareaValueChanged={(e) => setNotes(e.detail.value)} />
+```
+
+_With character limit_
+
+```html
+<wm-textarea label="Summary" character-limit="500"></wm-textarea>
+```
+
+_With character limit_
+
+```react
+<WmTextarea label="Summary" characterLimit={500} />
+```