@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,134 @@
+### Input
+- **Element:** `<wm-input>`
+
+**Purpose:** Accessible single-line text input. Supports text and number types, character limits,
+symbol prefixes/suffixes, and inline info/error messaging. Use instead of a native
+`<input>` in all Watermark UI.
+
+**When to use:**
+
+- **Collecting a short, free-form text value** -- when a user needs to type a name, title, identifier, URL, or any other brief string that does not fit a more specialized input (date, time, search), Input is the default choice.
+- **Displaying a value with a unit or currency symbol** -- when the field has a fixed prefix or suffix that is part of the value's meaning (e.g., "$" before a dollar amount, "%" after a score), use symbol-before or symbol-after to attach it inline.
+- **Enforcing a character limit with live feedback** -- when a field has a maximum length the user should be aware of while typing (e.g., a short title with a cap), use character-limit to display the running count and prevent overrun.
+
+**Do not use for:**
+
+- **Multi-line or long-form text** -- if the user needs to write a paragraph or any text that may wrap across multiple lines, use wm-textarea instead; Input is a single-line field and will not expand.
+- **Date or time entry** -- if the value is a date or time, use wm-datepicker or wm-timepicker; plain Input has no calendar, no format enforcement, and no date validation utilities.
+- **Search interactions** -- if the field's purpose is to filter or search a dataset, use wm-search instead, which is purpose-built for that interaction pattern.
+
+**Variants / types:**
+
+- `type="text"` -- default; accepts any string input
+- `type="number"` -- numeric input with optional min, max, and step constraints
+
+**Usage notes:**
+
+- `wmInputValueChanged` only fires on blur and only when the value has changed -- use the
+  native `input` event if you need every keystroke.
+- When using `symbol-before`, `symbol-after`, or `text-after`, the full field context is
+  announced to screen readers by associating those elements via `aria-describedby`.
+- Keep `text-after` to 55 characters or fewer.
+
+**Props:**
+- `character-limit` -- Maximum number of characters the user can type. Displays a live character counter and announces warnings via an `aria-live` region. Disabled when unset.
+- `disabled` -- Disables the input, preventing interaction. _(default: `false`)_
+- `error-message` -- Puts the component in an error state and displays this message below the input. Set to a non-empty string to activate; clear to remove.
+- `info` -- Hint text displayed below the input field. Read by screen readers when the field is focused.
+- `input-width` -- CSS width value for the input element itself, independent of the component's overall width (which includes the label, info, and error). Useful when you want the label wider than the input. _(default: `""`)_
+- `is-submit` -- When true, pressing Enter when the input is focused submits the containing form. _(default: `false`)_
+- `label` -- Visible label for the input. Required even when `label-position` is `'none'` -- used as the aria label for screen readers. _(required)_
+- `label-position` -- Position of the label relative to the input. `'none'` hides the label visually but keeps it accessible. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `max` -- For use with `type='number'`. The maximum value reachable with the stepper.
+- `min` -- For use with `type='number'`. The minimum value reachable with the stepper.
+- `placeholder` -- Placeholder text shown inside the empty input field. _(default: `""`)_
+- `required-field` -- Displays a required-field asterisk (*) next to the label and sets `aria-required="true"` on the input. _(default: `false`)_
+- `step` -- For use with `type='number'`. The interval between values when stepping. _(default: `1`)_
+- `symbol-after` -- String displayed after the input value (e.g. `'%'` for a percentage field).
+- `symbol-before` -- String displayed before the input value (e.g. `'$'` for a currency field).
+- `text-after` -- Text displayed after the input element (outside it). Keep to 55 characters or fewer.
+- `type` -- The input type. Use `'number'` for numeric fields; pair with `min`, `max`, and `step`. _(type: `"number" | "text"`; default: `"text"`)_
+- `value` -- The initial value of the input field, or its current value when reading from the component. _(default: `""`)_
+
+**Events:**
+- `wmInputValueChanged` -- Fires on blur when the input value has changed since the last blur. Use the
+native `input` event if you need to react to every keystroke. Detail: `{{ value: string }} value -- the current value of the input at the time of blur.`
+
+**Accessibility:**
+
+- `label` is required even when `label-position` is `"none"` -- it becomes the input's aria label.
+- Error messages and character-limit warnings are announced via an `aria-live` region.
+- Info text is associated via `aria-describedby` and read when the field receives focus.
+- `required-field` sets `aria-required="true"` on the underlying input.
+- **Keyboard:** - **Enter**: Submits the containing form when `is-submit` is true.
+
+**Related components:**
+
+- `<wm-textarea>` -- if the expected value spans multiple lines or requires significant length, use Textarea; Input is single-line only.
+- `<wm-search>` -- if the field drives a search or filter interaction rather than collecting a stored form value, use Search; Input has no search-specific behavior or affordances.
+- `<wm-datepicker>` / `<wm-timepicker>` -- if the value is a date or time, use the dedicated components; Input provides no format guidance, calendar navigation, or date validation.
+- `<wm-tag-input>` -- if the user needs to enter multiple discrete values (tags, names, identifiers) as a list rather than a single string, use Tag Input instead.
+
+**Code example:**
+
+_Basic input_
+
+```html
+<wm-input label="First name"></wm-input>
+```
+
+_Basic input_
+
+```react
+<WmInput label="First name" />
+```
+
+_Required field with error_
+
+```html
+<wm-input label="Email" required-field error-message="Please enter a valid email address"></wm-input>
+```
+
+_Form with submit validation and blur error clearing_
+
+```react
+// wmInputValueChanged fires on blur only when the value has changed.
+// event.detail.value is the current string value.
+// Validate required fields on submit; clear individual errors on blur once the user provides a value.
+const [name, setName] = useState("");
+const [email, setEmail] = useState("");
+const [errors, setErrors] = useState({ name: "", email: "" });
+
+const setError = (field, message) =>
+setErrors((prev) => ({ ...prev, [field]: message }));
+
+const handleNameBlur = (e) => {
+const val = e.detail.value;
+setName(val);
+if (val) setError("name", "");
+};
+
+const handleEmailBlur = (e) => {
+const val = e.detail.value;
+setEmail(val);
+if (!val) setError("email", "");
+else if (!val.includes("@")) setError("email", "Please enter a valid email address.");
+else setError("email", "");
+};
+
+const handleSubmit = () => {
+const newErrors = {
+name: name ? "" : "Full name is required.",
+email: !email ? "Email is required." : !email.includes("@") ? "Please enter a valid email address." : "",
+};
+setErrors(newErrors);
+if (Object.values(newErrors).every((e) => e === "")) { handleFormSubmit(); }
+};
+
+<WmInput label="Full name" requiredField={true} value={name}
+errorMessage={errors.name} onWmInputValueChanged={handleNameBlur} />
+<WmInput label="Email" requiredField={true} value={email}
+errorMessage={errors.email} onWmInputValueChanged={handleEmailBlur} />
+<WmButton buttonType="secondary" onClick={handleCancel}>Cancel</WmButton>
+<WmButton buttonType="primary" onClick={handleSubmit}>Submit</WmButton>
+```

package/dist/docs/skill/wm-line-chart.md

@@ -0,0 +1,135 @@
+### Line Chart
+- **Element:** `<wm-line-chart>`
+
+**Purpose:** Visualizes how data changes over time. Ideal for trend analysis -- tracking one or more
+metrics across chronological intervals such as semesters, academic years, or months.
+Supports up to 7 lines, each differentiated by both color and symbol. Data is set via the
+`line-data` prop (JSON string or object). Minimum width of 562 px; horizontally scrollable
+at smaller viewports.
+
+**When to use:**
+
+- **Showing a trend over time** -- when the x-axis is a sequence of chronological intervals and the goal is to show how a value rises or falls across them.
+- **Comparing several metrics over the same timeline** -- supports up to seven lines, each differentiated by both color and symbol; enable `visibility-toggles` to let users isolate lines.
+- **Providing a reference point** -- use `spotlight-data` to draw a single reference line (e.g., a target) spanning the chart.
+- **Distinguishing a projected or highlighted range** -- use `highlight-start` / `highlight-end` with a `highlight-qualifier` to mark part of the timeline (e.g., projected values).
+
+**Do not use for:**
+
+- **Comparing values across nominal categories** -- use `wm-chart-bar` or `wm-chart-column`.
+- **Composition / parts of a whole** -- use `wm-chart` or `wm-chart-stack`.
+- **Unequal or non-chronological x-axis spacing** -- x-axis values are treated as evenly spaced labels; the component does not render a true time-scaled axis, so use it only when the intervals are meant to read as equally spaced.
+
+**Variants / types:**
+
+- **Single-line** -- one metric over time.
+- **Multi-line** -- up to seven metrics, each with its own color and symbol.
+- **With visibility toggles** -- legend buttons to hide/show individual lines.
+- **With a spotlight/reference line** -- a single spanning reference value.
+- **With a highlighted region** -- a shaded x-axis range, optionally annotated for screen readers via `highlight-qualifier`.
+- **With deltas** -- `show-deltas` adds a "change since previous point" column to each popover.
+
+**Usage notes:**
+
+- `line-data` expects a JSON object where keys are line labels and values are objects mapping
+  x-axis values (strings) to y-axis values (numbers or `null` for missing data points).
+  In HTML, set it as a JSON string attribute; in JavaScript/React, set it as an object.
+- Up to 7 lines are supported -- each is automatically assigned a color and symbol from
+  the built-in palette.
+- `spotlight-data` adds a single reference line spanning the whole chart. Provide an object
+  with a `label` key and one x-value key mapping to the y-value.
+
+**Props:**
+- `decimal-places` -- Number of decimal places for data point values and y-axis interval labels.
+If omitted, the component infers an appropriate number from the data.
+- `description` -- Accessible description appended to the keyboard instructions read to screen
+readers. Recommended -- use it to summarize the key takeaway of the chart. _(default: `""`)_
+- `highlight-end` -- x-axis value where the highlighted background area ends.
+- `highlight-qualifier` -- Screen reader qualifier appended to the `aria-label` of data points that fall
+within a highlighted section (e.g. `"projected"`). _(default: `lineChartMessages.highlightQualifier`)_
+- `highlight-start` -- x-axis value where the highlighted background area begins. If used without
+`highlight-end`, the highlight extends to the right edge of the chart.
+- `label` -- Accessible label for the chart, used as the `aria-label` on the chart
+container. Required for accessibility. _(required)_
+- `label-width` -- CSS width of the y-axis interval label column. _(default: `"120px"`)_
+- `line-data` -- Chart data. Each key is a line label (shown in the legend); each value is an
+object mapping x-axis values (strings) to y-axis values (numbers or `null` for missing
+data points). Can be set as a JSON string (HTML attribute) or as an object (JavaScript).
+Example: `{ "Biology": { "2022-23": 310, "2023-24": 420 } }`. _(type: `string | { [lineLabel: string]: Line; }`; required)_
+- `show-deltas` -- When true, a "Change since [previous x-value]" column appears in each data
+point's popover, showing the percentage change from the preceding data point. _(default: `false`)_
+- `show-grid` -- When true, renders horizontal and vertical grid lines. _(default: `true`)_
+- `spotlightData` -- Adds a reference data point and a spanning horizontal line across the chart.
+Must include a `label` key and exactly one x-value key mapping to the y-value.
+Example: `{ label: "Target", "2024-25": 500 }`. _(type: `SpotlightData`)_
+- `units` -- Two comma-separated unit labels for the x and y axes, shown in parentheses
+after axis labels and inside popovers. Use `null` for no unit.
+Example: `"null,students"` or `"semester,percent"`. _(default: `"null,null"`)_
+- `visibility-toggles` -- When true, renders hide/show toggle buttons in the legend, allowing users to
+hide individual lines. _(default: `false`)_
+- `x-axis-label` -- Label for the x-axis (the time dimension, e.g. `"Term"`, `"Academic Year"`).
+Required for accessibility. _(required)_
+- `y-axis-label` -- Label for the y-axis (the measured value, e.g. `"Enrollment"`, `"Score"`).
+Required for accessibility. _(required)_
+- `y-range` -- Comma-separated numbers that explicitly define the y-axis tick values.
+Overrides automatic range and interval calculation.
+Example: `"0,100,200,300"`.
+
+**Accessibility:**
+
+- `label`, `x-axis-label`, and `y-axis-label` are required for accessibility.
+- Each data point renders as `role="img"` with a detailed `aria-label` including the line
+  name, x-value, y-value, units, and (if `show-deltas`) the percentage change from the
+  previous point.
+- An `aria-live` region announces the line name and data point count when keyboard focus
+  moves to a new line.
+- The `description` prop is appended to the chart instructions read to screen readers --
+  use it to summarize the key takeaway.
+- **Keyboard:**
+  - **Tab** (into chart): If `visibility-toggles` is enabled, focuses the first toggle button;
+  otherwise focuses the first data point.
+  - **Tab** (on toggle button): Moves to the first data point of the first visible line.
+  - **Shift+Tab** (on first data point, with toggles): Returns focus to the toggle buttons.
+  - **Arrow Up / Down** (on data point): Moves focus vertically to the same x-interval on
+  the previous/next line.
+  - **Arrow Left / Right** (on data point): Moves focus to the previous/next data point on
+  the same line.
+  - **Arrow Left / Right** (on toggle button): Cycles between toggle buttons.
+
+**Related components:**
+
+- `<wm-chart-bar>` / `<wm-chart-column>` -- for comparison across categories rather than over time.
+- `<wm-chart>` / `<wm-chart-stack>` -- for composition rather than trend.
+
+**Code example:**
+
+_Basic line chart_
+
+```html
+<wm-line-chart label="Enrollment trend" x-axis-label="Term" y-axis-label="Students"
+line-data='{"Biology": {"Fall 2022": 310, "Fall 2023": 340}}'></wm-line-chart>
+```
+
+_Basic line chart_
+
+```react
+<WmLineChart label="Enrollment trend" xAxisLabel="Term" yAxisLabel="Students"
+lineData={{ Biology: { "Fall 2022": 310, "Fall 2023": 340 } }} />
+```
+
+_Multi-line with delta comparisons_
+
+```html
+<wm-line-chart label="Retention rates" x-axis-label="Year" y-axis-label="Rate"
+units="null,percent" show-deltas
+line-data='{"Biology": {"2022": 85, "2023": 88}, "English": {"2022": 79, "2023": 82}}'>
+</wm-line-chart>
+```
+
+_Multi-line with delta comparisons_
+
+```react
+<WmLineChart label="Retention rates" xAxisLabel="Year" yAxisLabel="Rate"
+units="null,percent" showDeltas={true}
+lineData={{ Biology: { "2022": 85, "2023": 88 }, English: { "2022": 79, "2023": 82 } }} />
+```

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

@@ -0,0 +1,64 @@
+### Menuitem
+- **Element:** `<wm-menuitem>`
+
+**Purpose:** A single item within a wm-action-menu dropdown. Always used as a direct child of
+wm-action-menu -- never rendered in isolation.
+
+**Usage notes:**
+
+- `description` is limited to 100 characters and is incompatible with `icon`.
+- When disabled, the host element's `onclick` handler is temporarily removed and restored
+  when re-enabled, so that click handlers set before the prop change are not lost.
+
+**Props:**
+- `description` -- Secondary descriptive text displayed below the label. Maximum 100 characters.
+Incompatible with `icon`.
+- `disabled` -- Disables the menu item, preventing activation. The item remains visible and focusable. _(default: `false`)_
+- `icon` -- Icon to display before the label. Accepts the same formats as wm-button:
+`'#icon-name'` for a Ripple icon, `'/path/to/file.svg#symbol-id'` for a local SVG sprite,
+or an MDI character code (deprecated). Incompatible with `description`.
+
+**Slots:**
+- _(default)_ -- The visible label text for the menu item.
+
+**Required setup:**
+
+- Render it as a direct child of wm-action-menu.
+- Wire the action: attach an `onclick` handler to the item. The parent closes the dropdown when
+  an item is activated, so a menu that closes has not necessarily run anything.
+
+**Accessibility:**
+
+- Rendered with `role="menuitem"` and `aria-disabled` when disabled.
+
+**Code example:**
+
+_Basic menu items_
+
+```html
+<wm-action-menu tooltip="Actions">
+<wm-menuitem onclick="editRecord()">Edit</wm-menuitem>
+<wm-menuitem onclick="deleteRecord()">Delete</wm-menuitem>
+</wm-action-menu>
+```
+
+_Basic menu items_
+
+```react
+<WmActionMenu tooltip="Actions">
+<WmMenuitem onClick={editRecord}>Edit</WmMenuitem>
+<WmMenuitem onClick={deleteRecord}>Delete</WmMenuitem>
+</WmActionMenu>
+```
+
+_Menu item with icon_
+
+```html
+<wm-menuitem icon="#edit" onclick="editRecord()">Edit</wm-menuitem>
+```
+
+_Menu item with icon_
+
+```react
+<WmMenuitem icon="#edit" onClick={editRecord}>Edit</WmMenuitem>
+```

package/dist/docs/skill/wm-modal-footer.md

@@ -0,0 +1,81 @@
+### Modal Footer
+- **Element:** `<wm-modal-footer>`
+
+**Purpose:** Footer section for a wm-modal. Renders a primary action button, an optional secondary
+button, and optional informational text. Button clicks delegate to the parent modal's
+`emitPrimaryEvent()` and `emitSecondaryEvent()` methods, which fire
+`wmModalPrimaryTriggered` and `wmModalSecondaryTriggered` respectively. Always used as a
+direct child of wm-modal -- never rendered in isolation.
+
+**When to use:**
+
+- **Collecting or editing a focused set of information** -- when a user needs to fill out a short form or make a confined set of edits that must be completed or explicitly dismissed before anything else can happen, Modal creates the necessary interruption and focus.
+- **Confirming a consequential or destructive action** -- when the user has initiated something that warrants deliberate confirmation (such as permanently deleting a record), use Modal with deleteStyle on the footer to signal danger and require an explicit choice before proceeding.
+- **Running a short sequential workflow** -- when a task can be broken into a small number of steps using a stepper, Modal can host that progression, provided the workflow is compact enough that a full-page view is not warranted.
+- **Triggering a secondary confirmation from a primary action** -- a Modal's primary action can open an additional Modal, so a two-stage confirmation (e.g., submit then confirm submission) is a supported and appropriate use.
+
+**Do not use for:**
+
+- **Content that is too large for a centered overlay** -- if there is too much content to display comfortably, use a Flyout or light immersive view instead; Modal is not designed to host expansive content.
+- **More than one primary action** -- if more than one distinct action can be taken, break the workflow into separate Modals or reconsider the pattern entirely.
+- **Launching a Flyout or side panel from within a Modal** -- stacking containers at this level breaks user orientation and focus management.
+
+**Variants / types:**
+
+- `modal-type="modal"` -- full overlay for task completion with forms and richer content
+- `modal-type="dialog"` -- lighter variant for simpler, message-style interactions
+
+**Usage notes:**
+
+- `info-text` should not be used when the parent `wm-modal` has `modal-type="dialog"`.
+- Use `delete-style` to render the primary button with the wm-button `permanently-delete`
+  destructive styling.
+- When `element-to-focus="primary"` or `"secondary"` is set on the parent wm-modal, the
+  matching footer button receives focus on open. This requires `id` to be set on the parent
+  `<wm-modal>` element.
+
+**Props:**
+- `delete-style` -- Renders the primary button in the wm-button `permanently-delete` destructive
+style. Use for irreversible actions. _(default: `false`)_
+- `info-text` -- Additional feedback or status text displayed in the lower-left corner of the
+footer. Should not be used when the parent modal has `modal-type="dialog"`. _(default: `""`)_
+- `primary-action-disabled` -- Disables the primary action button. _(default: `false`)_
+- `primary-text` -- Label for the primary action button. _(required; default: `""`)_
+- `secondary-text` -- Label for the secondary action button. Omit to render the footer with only
+a primary button. _(default: `""`)_
+
+**Accessibility:**
+
+- Conditional DOM rendering based on open state: Modal must always be present in the DOM; use the open prop to control visibility. Removing it from the DOM can permanently break page scrolling.
+
+**Related components:**
+
+- Dialog (modal-type="dialog") -- Dialog is the lighter variant of the same component, intended for simpler message-style interactions; Modal is for task completion with forms and richer content.
+- `<wm-flyout>` -- if the task is longer, benefits from more horizontal space, or should coexist alongside the underlying page rather than block it entirely, use Flyout; Modal is for short, blocking, self-contained tasks.
+- Light Immersive Layout -- if the workflow is too complex or content-heavy for a Modal, escalate to a light immersive view; Modal is not suited to multi-faceted or lengthy workflows.
+
+**Code example:**
+
+_Basic footer_
+
+```html
+<wm-modal-footer primary-text="Save" secondary-text="Cancel"></wm-modal-footer>
+```
+
+_Basic footer_
+
+```react
+<WmModalFooter primaryText="Save" secondaryText="Cancel" />
+```
+
+_Delete-style footer_
+
+```html
+<wm-modal-footer primary-text="Delete" secondary-text="Cancel" delete-style></wm-modal-footer>
+```
+
+_Delete-style footer_
+
+```react
+<WmModalFooter primaryText="Delete" secondaryText="Cancel" deleteStyle={true} />
+```

package/dist/docs/skill/wm-modal-header.md

@@ -0,0 +1,71 @@
+### Modal Header
+- **Element:** `<wm-modal-header>`
+
+**Purpose:** Header section for a wm-modal. Renders the modal title, an optional subheading, and the
+close button. Always used as a direct child of wm-modal -- never rendered in isolation.
+
+**When to use:**
+
+- **Collecting or editing a focused set of information** -- when a user needs to fill out a short form or make a confined set of edits that must be completed or explicitly dismissed before anything else can happen, Modal creates the necessary interruption and focus.
+- **Confirming a consequential or destructive action** -- when the user has initiated something that warrants deliberate confirmation (such as permanently deleting a record), use Modal with deleteStyle on the footer to signal danger and require an explicit choice before proceeding.
+- **Running a short sequential workflow** -- when a task can be broken into a small number of steps using a stepper, Modal can host that progression, provided the workflow is compact enough that a full-page view is not warranted.
+- **Triggering a secondary confirmation from a primary action** -- a Modal's primary action can open an additional Modal, so a two-stage confirmation (e.g., submit then confirm submission) is a supported and appropriate use.
+
+**Do not use for:**
+
+- **Content that is too large for a centered overlay** -- if there is too much content to display comfortably, use a Flyout or light immersive view instead; Modal is not designed to host expansive content.
+- **More than one primary action** -- if more than one distinct action can be taken, break the workflow into separate Modals or reconsider the pattern entirely.
+- **Launching a Flyout or side panel from within a Modal** -- stacking containers at this level breaks user orientation and focus management.
+
+**Variants / types:**
+
+- `modal-type="modal"` -- full overlay for task completion with forms and richer content
+- `modal-type="dialog"` -- lighter variant for simpler, message-style interactions
+
+**Usage notes:**
+
+- `subheading` should not be used when the parent `wm-modal` has `modal-type="dialog"`.
+- Clicking the close button delegates to the parent modal's `emitCloseEvent()`, which fires
+  `wmModalCloseTriggered`. The host application must set the parent modal's `open` to false
+  in response.
+
+**Props:**
+- `heading` -- The main title text displayed in the modal header. _(required; default: `""`)_
+- `subheading` -- Optional descriptive text displayed below the heading. Should not be used
+when the parent modal has `modal-type="dialog"`. _(default: `""`)_
+
+**Accessibility:**
+
+- Conditional DOM rendering based on open state: Modal must always be present in the DOM; use the open prop to control visibility. Removing it from the DOM can permanently break page scrolling.
+
+**Related components:**
+
+- Dialog (modal-type="dialog") -- Dialog is the lighter variant of the same component, intended for simpler message-style interactions; Modal is for task completion with forms and richer content.
+- `<wm-flyout>` -- if the task is longer, benefits from more horizontal space, or should coexist alongside the underlying page rather than block it entirely, use Flyout; Modal is for short, blocking, self-contained tasks.
+- Light Immersive Layout -- if the workflow is too complex or content-heavy for a Modal, escalate to a light immersive view; Modal is not suited to multi-faceted or lengthy workflows.
+
+**Code example:**
+
+_Basic header_
+
+```html
+<wm-modal-header heading="Confirm action"></wm-modal-header>
+```
+
+_Basic header_
+
+```react
+<WmModalHeader heading="Confirm action" />
+```
+
+_Header with subheading_
+
+```html
+<wm-modal-header heading="Export data" subheading="This may take a few minutes."></wm-modal-header>
+```
+
+_Header with subheading_
+
+```react
+<WmModalHeader heading="Export data" subheading="This may take a few minutes." />
+```

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

@@ -0,0 +1,172 @@
+### Modal
+- **Element:** `<wm-modal>`
+
+**Purpose:** Modal dialog that overlays the page. Renders as a full-bleed `modal` (default) or a
+smaller centered `dialog`. Content is provided through wm-modal-header, wm-modal-footer,
+and arbitrary slotted children.
+
+**When to use:**
+
+- **Collecting or editing a focused set of information** -- when a user needs to fill out a short form or make a confined set of edits that must be completed or explicitly dismissed before anything else can happen, Modal creates the necessary interruption and focus.
+- **Confirming a consequential or destructive action** -- when the user has initiated something that warrants deliberate confirmation (such as permanently deleting a record), use Modal with deleteStyle on the footer to signal danger and require an explicit choice before proceeding.
+- **Running a short sequential workflow** -- when a task can be broken into a small number of steps using a stepper, Modal can host that progression, provided the workflow is compact enough that a full-page view is not warranted.
+- **Triggering a secondary confirmation from a primary action** -- a Modal's primary action can open an additional Modal, so a two-stage confirmation (e.g., submit then confirm submission) is a supported and appropriate use.
+
+**Do not use for:**
+
+- **Content that is too large for a centered overlay** -- if there is too much content to display comfortably, use a Flyout or light immersive view instead; Modal is not designed to host expansive content.
+- **More than one primary action** -- if more than one distinct action can be taken, break the workflow into separate Modals or reconsider the pattern entirely.
+- **Launching a Flyout or side panel from within a Modal** -- stacking containers at this level breaks user orientation and focus management.
+
+**Variants / types:**
+
+- `modal-type="modal"` -- full overlay for task completion with forms and richer content
+- `modal-type="dialog"` -- lighter variant for simpler, message-style interactions
+
+**Usage notes:**
+
+- Always render the component and toggle `open` -- do not conditionally mount/unmount it.
+  Conditional rendering breaks the `aria-live` region detection and can cause body-scroll issues.
+- In React, set `open` imperatively via a ref (`ref.current.open = true/false`) rather than
+  passing it as a prop. Using the prop triggers a React re-render that interferes with the
+  native `<dialog>` focus-return mechanism and causes `:focus-visible` styles to appear on
+  the trigger element after close.
+- For scrollable modal content, set `overflow: auto` on the content wrapper and reset
+  `scrollTop` when reopening a previously scrolled modal.
+- On mobile (<768px) with `modal-type="dialog"`, `element-to-focus` targeting a footer button
+  is overridden to the close button to avoid disorienting scroll behavior.
+
+**Props:**
+- `element-to-focus` -- Element to focus when the modal opens. Pass `"primary"` or `"secondary"` to
+focus the corresponding wm-modal-footer button, or an element `id` to focus a specific
+element in the modal body. Defaults to the close button. Requires `id` to be set on
+`<wm-modal>` when targeting footer buttons. _(default: `""`)_
+- `modal-type` -- Visual presentation style. `'modal'` renders a full-bleed overlay; `'dialog'`
+renders a smaller centered panel. _(type: `"dialog" | "modal"`; default: `"modal"`)_
+- `open` -- Controls the open/closed state of the modal. Always render the component and
+toggle this prop -- do not conditionally mount/unmount. _(default: `false`)_
+- `uid` -- Unique identifier used internally to wire `aria-labelledby` and
+`aria-describedby` relationships. Set automatically from the element's `id` attribute or
+generated if absent -- do not set this prop manually. _(required)_
+
+**Slots:**
+- _(default)_ -- Modal content: wm-modal-header, body content, and wm-modal-footer.
+
+**Events:**
+- `wmModalCloseTriggered` -- Fires when the close button is clicked or Escape is pressed. Does not bubble,
+preventing nested modals from closing simultaneously. The host application must set `open`
+to false in response.
+- `wmModalPrimaryTriggered` -- Fires when the wm-modal-footer primary button is clicked.
+- `wmModalSecondaryTriggered` -- Fires when the wm-modal-footer secondary button is clicked.
+
+**Methods:**
+- `emitCloseEvent() => Promise<void>` -- Programmatically fires `wmModalCloseTriggered`. Use when you need to trigger
+a close from outside the modal without simulating a button click.
+  - **Returns:** A promise that resolves once the event has been emitted.
+- `emitPrimaryEvent() => Promise<void>` -- Programmatically fires `wmModalPrimaryTriggered`. Use when you need to trigger
+the primary action from outside the modal.
+  - **Returns:** A promise that resolves once the event has been emitted.
+- `emitSecondaryEvent() => Promise<void>` -- Programmatically fires `wmModalSecondaryTriggered`. Use when you need to trigger
+the secondary action from outside the modal.
+  - **Returns:** A promise that resolves once the event has been emitted.
+
+**Required setup:**
+
+- Drive `open` from your own state: true to show the modal, false to hide it. In React set it
+  through a ref (`ref.current.open = true`) rather than as a prop, which breaks the native dialog
+  focus-return.
+- Handle `wmModalCloseTriggered` -- the close button and Escape -- by setting `open = false`. It
+  does not bubble, so attach the listener to the element itself.
+- Handle `wmModalPrimaryTriggered` and `wmModalSecondaryTriggered` for whichever wm-modal-footer
+  buttons you render, setting `open = false` to dismiss.
+- Reset the content wrapper's `scrollTop` to 0 when reopening, if the body content scrolls.
+
+**Accessibility:**
+
+- Rendered as a `<dialog>` element with `aria-labelledby` pointing to the heading.
+- When footer buttons receive initial focus (`element-to-focus="primary"` or `"secondary"`),
+  the element `id` on `<wm-modal>` is required -- it is used to construct `aria-describedby`
+  relationships between the heading, content, and footer.
+- The content wrapper must have `id="content-[id of wm-modal]"` for the aria-describedby association.
+- Focus returns automatically to the element that was active when the modal opened.
+- **Keyboard:**
+  - **Tab**: Advances focus through focusable elements; wraps from the last element back to the first.
+  - **Shift+Tab**: Moves focus backward; wraps from the first element to the last.
+  - **Escape**: Fires `wmModalCloseTriggered` (the host application must set `open = false` on the element ref in response).
+  - **Enter / Space**: Activates the focused button.
+
+**Related components:**
+
+- Dialog (modal-type="dialog") -- Dialog is the lighter variant of the same component, intended for simpler message-style interactions; Modal is for task completion with forms and richer content.
+- `<wm-flyout>` -- if the task is longer, benefits from more horizontal space, or should coexist alongside the underlying page rather than block it entirely, use Flyout; Modal is for short, blocking, self-contained tasks.
+- Light Immersive Layout -- if the workflow is too complex or content-heavy for a Modal, escalate to a light immersive view; Modal is not suited to multi-faceted or lengthy workflows.
+
+**Code example:**
+
+_Basic modal_
+
+```html
+<wm-modal id="confirm-modal" open>
+<wm-modal-header heading="Confirm action"></wm-modal-header>
+<div id="content-confirm-modal">Are you sure you want to continue?</div>
+<wm-modal-footer primary-text="Confirm" secondary-text="Cancel"></wm-modal-footer>
+</wm-modal>
+```
+
+_Basic modal_
+
+```react
+// Set open imperatively via ref -- do not use open={} as a React prop.
+// This preserves the native <dialog> focus-return without triggering :focus-visible.
+const modalRef = useRef(null);
+
+const openModal = () => { modalRef.current.open = true; };
+const closeModal = () => { modalRef.current.open = false; };
+
+<WmButton onClick={openModal}>Open modal</WmButton>
+
+<WmModal
+ref={modalRef}
+id="confirm-modal"
+onWmModalCloseTriggered={closeModal}
+onWmModalPrimaryTriggered={closeModal}
+onWmModalSecondaryTriggered={closeModal}
+>
+<WmModalHeader heading="Confirm action" />
+<div id="content-confirm-modal">Are you sure you want to continue?</div>
+<WmModalFooter primaryText="Confirm" secondaryText="Cancel" />
+</WmModal>
+```
+
+_Dialog type (smaller, centered)_
+
+```html
+<wm-modal id="info-dialog" modal-type="dialog" open>
+<wm-modal-header heading="Information"></wm-modal-header>
+<div id="content-info-dialog">This is additional context.</div>
+<wm-modal-footer primary-text="Got it"></wm-modal-footer>
+</wm-modal>
+```
+
+_Dialog type_
+
+```react
+const dialogRef = useRef(null);
+
+const openDialog = () => { dialogRef.current.open = true; };
+const closeDialog = () => { dialogRef.current.open = false; };
+
+<WmButton onClick={openDialog}>Open dialog</WmButton>
+
+<WmModal
+ref={dialogRef}
+id="info-dialog"
+modalType="dialog"
+onWmModalCloseTriggered={closeDialog}
+onWmModalPrimaryTriggered={closeDialog}
+>
+<WmModalHeader heading="Information" />
+<div id="content-info-dialog">This is additional context.</div>
+<WmModalFooter primaryText="Got it" />
+</WmModal>
+```