@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,187 @@
+### Tag Input
+- **Element:** `<wm-tag-input>`
+
+**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
+
+**Usage notes:**
+
+- `label` is required and must always be provided.
+- `col-headers` is required for the `table` variant; `label-position="left"` is not
+  supported in the `table` variant.
+- `max-tags` displays a counter but does not prevent selection beyond the limit -- enforce
+  the limit in your `wmTagOptionSelected` or `wmTagInputTagAdded` handler.
+- The `add-new` feature (dropdown only) detects and announces duplicate entries.
+- In React, `wmTagOptionSelected` and `wmTagOptionDeselected` bubble from `wm-tag-option`
+  to `wm-tag-input` for the dropdown variant (listen on `WmTagInput`). For the table
+  variant, put the handlers directly on each `WmTagOption` instead. In both cases, you
+  must set `event.target.selected = true/false` imperatively -- the component does not do
+  this automatically.
+- For the `add-new` dropdown variant, create and append a new `wm-tag-option` element with
+  `selected = true` in the `wmTagInputTagAdded` handler -- the component does not create
+  the option element automatically.
+
+**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. _(default: `true`)_
+- `character-limit` -- Dropdown variant only. Maximum character limit enforced on the search field. _(default: `50`)_
+- `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. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `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. _(default: `false`)_
+- `tag-input-type` -- Selects the component variant. `'dropdown'` shows a filterable list;
+`'table'` shows a filterable multi-column table. _(type: `"dropdown" | "table"`; default: `"dropdown"`)_
+
+**Slots:**
+- _(default)_ -- One or more wm-tag-option children.
+
+**Events:**
+- `wmTagInputTagAdded` -- Fires when the user adds a new tag by typing and pressing Enter or comma
+(dropdown variant, `add-new` enabled). The event detail is the text string of the new
+tag. Not fired when selecting an existing wm-tag-option -- listen to `wmTagOptionSelected`
+on the wm-tag-option for that. Detail: `string -- the text of the newly created tag.`
+
+**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,60 @@
+### Tag Option
+- **Element:** `<wm-tag-option>`
+
+**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.
+
+**Usage notes:**
+
+- 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. _(default: `false`)_
+- `selected` -- Whether this option is currently selected (appears as a tag). Setting this
+on load pre-selects the option. _(default: `false`)_
+
+**Events:**
+- `wmTagOptionDeselected` -- Fires when this option's tag is removed.
+- `wmTagOptionSelected` -- Fires when this option is selected as a tag.
+
+**Methods:**
+- `emitDeselectedEvent() => Promise<void>` -- Programmatically deselects this option, removing it as a tag.
+  - **Returns:** A promise that resolves once the event has been emitted.
+- `emitSelectedEvent() => Promise<void>` -- Programmatically selects this option, adding it as a tag.
+  - **Returns:** A promise that resolves once the event has been emitted.
+
+**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,102 @@
+### Textarea
+- **Element:** `<wm-textarea>`
+
+**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_
+
+**Usage notes:**
+
+- In HTML, set the initial value via text content: `<wm-textarea>initial value</wm-textarea>`.
+  In React, use the `value` prop for controlled usage.
+- `wmTextareaValueChanged` fires on blur only when the value has changed; use the native
+  `input` event for per-keystroke updates.
+- `event.detail.value` is the current string value.
+
+**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. _(default: `false`)_
+- `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. _(default: `""`)_
+- `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. _(default: `""`)_
+- `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. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `placeholder` -- Placeholder text shown inside the empty textarea. _(default: `""`)_
+- `required-field` -- Displays a required-field asterisk next to the label. _(default: `false`)_
+- `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>`. _(default: `""`)_
+
+**Events:**
+- `wmTextareaValueChanged` -- Fires on blur when the value has changed since load or the last blur. Use
+the native `input` event for per-keystroke updates. Detail: `{{ value: string }} value -- the current textarea value at the time of blur.`
+
+**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} />
+```

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

@@ -0,0 +1,156 @@
+### Timepicker
+- **Element:** `<wm-timepicker>`
+
+**Purpose:** Time input that lets users type a time or pick one from a dropdown list of 15-minute
+intervals. Supports 12-hour and 24-hour display and provides `reformatTime` and
+`isValidTime` utility methods. Use instead of native `<input type="time">`.
+
+**When to use:**
+
+- **Collecting a specific time of day in a form** -- Timepicker is the standard input, offering both typed entry for precision and a dropdown for browsing.
+- **Pre-focusing the dropdown on a relevant time** -- when a default or suggested time exists (e.g., the start of a business day), use the preselected property in 24hr format to open the dropdown already positioned at that time.
+- **Pairing with Datepicker for a full date-and-time value** -- when a form requires both a date and a time of day, pair Timepicker with wm-datepicker to collect each value with its purpose-built input; Timepicker handles the time portion only.
+
+**Do not use for:**
+
+- **Collecting a date with no time component** -- if the value is a date only, use wm-datepicker alone; adding Timepicker implies a time dimension that may not exist in the data.
+- **Plain text entry for a time value** -- a plain wm-input offers no time validation, no format guidance, no dropdown for browsing, and no reformatTime or isValidTime utilities; whenever a time of day is being collected, Timepicker is always the correct component.
+
+**Variants / types:**
+
+_None documented_
+
+**Usage notes:**
+
+- The dropdown displays 15-minute intervals (00:00-23:45) in 12-hour format; typed input
+  is accepted in both 12-hour and 24-hour formats.
+- `wmTimepickerTimeSelected` emits `{ time: string }` in 24-hour `hh:mm` format. Always
+  call `reformatTime("12", ...)` on the result and write it back to `value` so the input
+  displays the formatted string.
+- Use `reformatTime` and `isValidTime` via an imperative ref -- they are async component
+  methods, not props.
+- When writing a curried event-handler factory, the outer function must NOT be async;
+  only the inner handler should be async, otherwise the factory returns a Promise instead
+  of a function.
+
+**Props:**
+- `disabled` -- Disables the timepicker, preventing all interaction. _(default: `false`)_
+- `error-message` -- Puts the component in an error state and displays this message below the
+input.
+- `label` -- Accessible label for the input. Required even when `label-position="none"`. _(required; default: `""`)_
+- `label-position` -- Controls label placement. `'none'` hides the label visually but keeps it
+accessible. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `preselected` -- The time the dropdown scrolls to and focuses when opened, in 24-hour format
+(e.g. `'14:30'`). Falls back to parsing `value`; defaults to `'09:00'` if unparseable.
+- `required-field` -- Displays a required-field asterisk next to the label. _(default: `false`)_
+- `value` -- The time displayed in the input field. Updated as the user types. Can also
+be set programmatically by the application. _(default: `""`)_
+
+**Events:**
+- `wmTimepickerInputBlurred` -- Fires when the input field loses focus.
+- `wmTimepickerTimeSelected` -- Fires when the user selects a time from the dropdown list. Detail: `{{ time: string }} time -- the selected time in 24-hour `hh:mm` format.`
+
+**Methods:**
+- `isValidTime(input: string) => Promise<boolean>` -- Validates a time string against both 12-hour and 24-hour formats.
+  - `input` -- The time string to validate.
+  - **Returns:** `true` if the string is a valid time, `false` otherwise.
+- `reformatTime(format: "12" | "24", time: TimeFormat12 | TimeFormat24) => Promise<string>` -- Converts a time string between 12-hour and 24-hour formats.
+  - `format` -- The target format: `"12"` for 12-hour (e.g. `"02:30 PM"`), `"24"` for
+24-hour (e.g. `"14:30"`).
+  - `time` -- The time string to convert. Accepts both 12-hour and 24-hour input.
+  - **Returns:** The reformatted time string.
+
+**Accessibility:**
+
+- `label` sets the accessible name on the input; required even when `label-position="none"`.
+- Error messages are announced via an `aria-live` region.
+- **Keyboard:**
+  **Input field:**
+  - **Arrow Down / Arrow Up**: Open the dropdown focused on the nearest time interval.
+  **Dropdown button:**
+  - **Enter / Space**: Open the dropdown.
+  **Dropdown list:**
+  - **Arrow Down / Arrow Up**: Move focus to the next/previous option; wraps at both ends.
+  - **Home / End**: Move focus to the first/last option.
+  - **Enter / Space**: Select the focused time and close the dropdown.
+  - **Tab**: Close the dropdown and advance focus (without selecting).
+  - **Escape**: Close the dropdown without selecting.
+
+**Related components:**
+
+- `<wm-datepicker>` -- if the value is a date rather than a time, use Datepicker; when both are needed, the two should be paired as separate inputs rather than combined into one.
+- `<wm-input>` -- a plain Input has no time-specific behavior; whenever the value being collected is a time of day, Timepicker is always the right choice over a generic text field.
+- `<wm-select>` -- if the user is choosing from a small, fixed list of named time slots or periods (e.g., "Morning", "Afternoon", "Evening") rather than a precise time of day, Select may be more appropriate; Timepicker is for collecting an actual clock time.
+
+**Code example:**
+
+_Basic timepicker_
+
+```html
+<wm-timepicker label="Start time"></wm-timepicker>
+```
+
+_Basic timepicker_
+
+```react
+// wmTimepickerTimeSelected emits { time } in 24hr format.
+// Call reformatTime and write back to value so the input displays the result.
+// handleInputBlur validates free-form typed input on blur using isValidTime.
+// NOTE: the outer factory function must NOT be async -- only the inner handler should be.
+const startRef = useRef(null);
+const [startValue, setStartValue] = useState("");
+const [startError, setStartError] = useState("");
+
+const handleTimeSelected = (ref, setValue, setError) => async (e) => {
+const time12 = await ref.current.reformatTime("12", e.detail.time);
+setError("");
+setValue(time12);
+};
+
+const handleInputBlur = (ref, value, setValue, setError) => async () => {
+if (!value) return;
+const valid = await ref.current.isValidTime(value);
+if (valid) {
+const time12 = await ref.current.reformatTime("12", value);
+setError("");
+setValue(time12);
+} else {
+setError("Please enter a valid time.");
+}
+};
+
+<WmTimepicker
+ref={startRef}
+label="Start time"
+value={startValue}
+errorMessage={startError}
+onWmTimepickerTimeSelected={handleTimeSelected(startRef, setStartValue, setStartError)}
+onWmTimepickerInputBlurred={handleInputBlur(startRef, startValue, setStartValue, setStartError)}
+/>
+```
+
+_With pre-selected time_
+
+```html
+<wm-timepicker label="Meeting time" preselected="14:30" value="2:30 PM"></wm-timepicker>
+```
+
+_With pre-selected time_
+
+```react
+// preselected (24hr) controls where the dropdown focuses on open.
+// value sets the initial display string in the input.
+const meetingRef = useRef(null);
+const [meetingValue, setMeetingValue] = useState("2:30 PM");
+const [meetingError, setMeetingError] = useState("");
+
+<WmTimepicker
+ref={meetingRef}
+label="Meeting time"
+preselected="14:30"
+value={meetingValue}
+errorMessage={meetingError}
+onWmTimepickerTimeSelected={handleTimeSelected(meetingRef, setMeetingValue, setMeetingError)}
+onWmTimepickerInputBlurred={handleInputBlur(meetingRef, meetingValue, setMeetingValue, setMeetingError)}
+/>
+```

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

@@ -0,0 +1,98 @@
+### Toggletip
+- **Element:** `<wm-toggletip>`
+
+**Purpose:** Toggletip button that shows a small informational panel when clicked. Two visual types:
+`'info'` renders an info icon button; `'ai'` renders an animated AI sparkle icon. The
+panel content is provided via the `tooltip` prop and is announced to screen readers via
+an `aria-live` region.
+
+**When to use:**
+
+- Use a Toggletip to surface a brief supplementary explanation on demand without cluttering the interface.
+- **Explaining a concept or term inline** -- when a page contains terminology, metrics, or calculated values that users may not recognize, a Toggletip lets curious users get the definition without requiring everyone to read it by default.
+- **Providing AI-related contextual information** -- when content or a control is AI-generated or AI-assisted, use toggletip-type="ai" to visually signal the AI context and explain what it means or how it was produced.
+- **Adding help content to a standalone control** -- when the Toggletip is placed away from tight inline content (e.g., a section header or card), use target-size="large" to meet touch target size requirements and make it easier to tap on mobile.
+
+**Do not use for:**
+
+- **Describing what a button does when clicked** -- a tooltip on hover/focus describes button behavior; a Toggletip on click provides contextual information about content or a control. Using a Toggletip to describe button behavior is the wrong pattern.
+- **Lengthy or rich content** -- if the explanation requires formatting, links, multiple paragraphs, or interactive content, it belongs in a Flyout or another container, not a Toggletip.
+- **System messages, errors, or alerts** -- Toggletip is strictly a user-initiated help tool and should never be used to surface notifications that users might miss if they do not click the icon.
+
+**Variants / types:**
+
+- `toggletip-type="info"` -- standard information icon; use for general contextual help
+- `toggletip-type="ai"` -- AI-branded icon; use when the explanation relates to AI-generated or AI-assisted content
+- `target-size="small"` -- compact touch target for inline or dense contexts
+- `target-size="large"` -- larger touch target for standalone placements or mobile contexts
+
+**Usage notes:**
+
+- Both `label` and `tooltip` are required; the component logs a console error on load if
+  either is missing.
+- `tooltip-position` is the preferred opening direction; the component auto-corrects it if
+  the panel would overflow the viewport.
+
+**Props:**
+- `label` -- Accessible label for the trigger button. Also shown as a hover/focus tooltip
+while the panel is closed. Required for screen reader users. _(required)_
+- `target-size` -- Size of the trigger button icon. `'large'` satisfies WCAG 2.5.8 touch
+target requirements. _(type: `"large" | "small"`; default: `"small"`)_
+- `toggletip-type` -- Visual style of the trigger icon. `'info'` shows an info icon; `'ai'` shows
+an animated sparkle icon. _(type: `"ai" | "info"`; default: `"info"`)_
+- `tooltip` -- Content displayed inside the toggletip panel when opened. Also announced
+via an `aria-live` region when the panel opens. _(required)_
+- `tooltip-position` -- Preferred opening direction for the panel. Auto-corrected if the panel would
+overflow the viewport. _(type: `"bottom" | "bottom-left" | "bottom-right" | "left" | "right" | "top" | "top-left" | "top-right"`; default: `"bottom-right"`)_
+
+**Accessibility:**
+
+- `label` sets the `aria-label` on the trigger button -- required even though the button
+  has a visual icon.
+- The panel content is announced via `role="status"` / `aria-live="polite"` when opened.
+- A hover/focus tooltip shows `"More information"` (info type) or `"Powered by AI"` (ai
+  type) while the panel is closed.
+- **Keyboard:**
+  - **Enter / Space**: Opens or toggles the toggletip panel.
+  - **Escape**: Closes the panel without propagating (will not close a parent modal).
+  - **Tab**: Closes the panel and advances focus to the next element.
+
+**Related components:**
+
+_None_
+
+**Code example:**
+
+_Info toggletip_
+
+```html
+<wm-toggletip
+label="More about this field"
+tooltip="This field accepts ISO 8601 dates.">
+</wm-toggletip>
+```
+
+_Info toggletip_
+
+```react
+<WmToggletip label="More about this field" tooltip="This field accepts ISO 8601 dates." />
+```
+
+_AI toggletip_
+
+```html
+<wm-toggletip
+toggletip-type="ai"
+label="AI-generated content"
+tooltip="This summary was generated by AI and may contain errors.">
+</wm-toggletip>
+```
+
+_AI toggletip_
+
+```react
+<WmToggletip
+toggletipType="ai"
+label="AI-generated content"
+tooltip="This summary was generated by AI and may contain errors." />
+```