@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/wm-flyout.md

@@ -0,0 +1,123 @@
+# `wm-flyout`
+
+Slide-in panel that renders over the main content as a modal dialog. Used for detail views,
+multi-step workflows, and forms that require focus without navigating away from the page.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `breadcrumb` | `breadcrumb` | `string \| undefined` |  |  |  |
+| `elementToFocus` | `element-to-focus` | `string` | `""` |  |  |
+| `eyebrow` | `eyebrow` | `string \| undefined` |  |  |  |
+| `flyoutWidth` | `flyout-width` | `string` | `"45rem"` |  |  |
+| `heading` | `heading` | `string` |  | ✓ |  |
+| `infoText` | `info-text` | `string \| undefined` |  |  |  |
+| `open` | `open` | `boolean` | `false` |  |  |
+| `primaryText` | `primary-text` | `string \| undefined` |  |  |  |
+| `secondaryText` | `secondary-text` | `string \| undefined` |  |  |  |
+| `subheading` | `subheading` | `string \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmFlyoutBreadcrumbClicked` | `{ breadcrumb: string; index: number; }` | ✓ |  |
+| `wmFlyoutCloseTriggered` | `void` | ✓ |  |
+| `wmFlyoutPrimaryTriggered` | `void` | ✓ |  |
+| `wmFlyoutSecondaryTriggered` | `void` | ✓ |  |
+
+## Methods
+
+### `focusHeading() => Promise<void>`
+
+**Returns** `Promise<void>` -- A promise that resolves once focus has been applied.
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | Main content of the flyout body. |
+
+## Depends On
+
+- `wm-button`
+
+# wm-flyout
+
+## Purpose
+
+A panel that slides in from the right over the current page, letting users complete a task or view supplementary information without navigating away from their current context.
+
+---
+
+## When to Use
+
+- **Completing a single, focused task without losing page context** -- when a user needs to fill out a form, make selections, or take action on an item while the underlying page remains visible behind them, use a Flyout to keep that context intact rather than navigating to a new page.
+- **Displaying supplementary details about a selected item** -- when a user clicks a row in a table or a card and needs to see more information or edit fields, a Flyout surfaces that content without displacing the list they came from.
+- **Running a short multi-step workflow** -- when a task can be broken into 2-3 manageable steps (using breadcrumbs to navigate between them), a Flyout can host that progression while keeping the originating page visible. The patterns guidance caps this at 3-5 steps before the workflow becomes too complex.
+- **Launching a task from a primary page or immersive view** -- Flyouts can be triggered from main pages and immersive layouts, making them the right container when an action on a parent view needs a dedicated working surface without a full page transition.
+
+---
+
+## Do Not Use For
+
+- **Complex, content-heavy workflows** -- if there is too much content to display comfortably in one view, or the workflow is too involved, use a light immersive view instead; Flyouts are for simple, quick-to-complete tasks.
+- **Launching from another Flyout, Modal, or Dialog** -- stacking containers creates disorienting layers that break focus management and user orientation.
+- **Tasks where the user needs to reference main content alongside the panel** -- if the user is expected to actively compare or interact with the main content area while working in the panel, a side panel is the right choice.
+
+---
+
+## Related Components
+
+- Side Panel -- if the user needs to actively reference or interact with the main content area while the panel is open, use a side panel (which pushes content rather than overlaying it); if focus should be on the panel task alone, use Flyout.
+- `<wm-modal>` -- if the task is short, self-contained, and requires the user to complete or dismiss it before doing anything else, use Modal; if the task is longer or should coexist with the underlying page, use Flyout.
+- Light Immersive Layout -- if the workflow is too complex or content-heavy for a Flyout (more than 3-5 steps), escalate to a light immersive view instead.
+
+---
+
+## Accessibility
+
+- Conditional DOM rendering based on open state: the Flyout must always be present in the DOM; use the open prop to control visibility. Removing it from the DOM breaks screen reader detection of the live region.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `heading` -- required; the panel title, announced by screen readers when the Flyout opens
+- `subheading` -- optional secondary heading rendered below the main heading
+- `eyebrow` -- optional label rendered above the heading
+- `breadcrumb` -- text for the breadcrumb shown at the top; used for multi-step workflows
+- `infoText` -- supplementary text displayed in the panel header area
+- `primaryText` -- label for the primary footer button
+- `secondaryText` -- label for the secondary footer button
+- `open` -- controls panel visibility; always keep the component in the DOM and toggle this prop
+- `flyoutWidth` -- CSS width value for the panel
+- `elementToFocus` -- which element receives focus when opened: "primary", "secondary", or any element ID
+
+---
+
+## Events
+
+- `wmFlyoutPrimaryTriggered` -- fires when the primary footer button is activated
+- `wmFlyoutSecondaryTriggered` -- fires when the secondary footer button is activated
+- `wmFlyoutCloseTriggered` -- fires when the close button or Escape is used
+- `wmFlyoutBreadcrumbClicked` -- fires when the breadcrumb is activated
+
+---
+
+## Methods
+
+- `focusHeading()` -- moves focus to the panel heading; call when content changes mid-workflow so screen reader users are informed
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-input.md

@@ -0,0 +1,120 @@
+# `wm-input`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `characterLimit` | `character-limit` | `number \| undefined` |  |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `info` | `info` | `string \| undefined` |  |  |  |
+| `inputWidth` | `input-width` | `string` | `""` |  |  |
+| `isSubmit` | `is-submit` | `boolean` | `false` |  |  |
+| `label` | `label` | `string` |  | ✓ |  |
+| `labelPosition` | `label-position` | `"left" \| "none" \| "top"` | `"top"` |  |  |
+| `max` | `max` | `number \| undefined` |  |  |  |
+| `min` | `min` | `number \| undefined` |  |  |  |
+| `placeholder` | `placeholder` | `string` | `""` |  |  |
+| `requiredField` | `required-field` | `boolean` | `false` |  |  |
+| `step` | `step` | `number \| undefined` | `1` |  |  |
+| `symbolAfter` | `symbol-after` | `string \| undefined` |  |  |  |
+| `symbolBefore` | `symbol-before` | `string \| undefined` |  |  |  |
+| `textAfter` | `text-after` | `string \| undefined` |  |  |  |
+| `type` | `type` | `"number" \| "text"` | `"text"` |  |  |
+| `value` | `value` | `string` | `""` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmInputValueChanged` | `{ value: string; }` | ✓ |  |
+
+# wm-input
+
+## Purpose
+
+The standard single-line text field for collecting free-form or structured short-form values in a form, supporting both plain text and numeric entry with optional character limits, inline symbols, and validation messaging.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## Accessibility
+
+- Collecting a numeric value with optional constraints: use type="number" with min, max, and step when the field represents a quantity, percentage, or score that should be bounded and steppable, rather than accepting arbitrary text.
+- Omitting the label when hiding the visual label: the label is required for accessibility even when label-position="none"; skipping it leaves the field unnamed for screen reader users.
+
+---
+
+## Variants / Types
+
+- `type="text"` -- default; accepts any string input
+- `type="number"` -- numeric input with optional min, max, and step constraints
+
+---
+
+## Props
+
+- `label` -- required; the field's accessible name even when label-position="none"
+- `labelPosition` -- "top", "left", or "none"
+- `type` -- "text" or "number"
+- `value` -- the current value of the input
+- `placeholder` -- placeholder text shown when the field is empty
+- `characterLimit` -- maximum character count; displays a running count and prevents overrun
+- `symbolBefore` -- a fixed prefix symbol displayed inside the field (e.g., "$")
+- `symbolAfter` -- a fixed suffix symbol displayed inside the field (e.g., "%")
+- `textAfter` -- a text label rendered after the input (e.g., a unit like "hours")
+- `min` -- minimum value for type="number"
+- `max` -- maximum value for type="number"
+- `step` -- step increment for type="number"
+- `info` -- helper text displayed below the field; announced on focus by screen readers
+- `errorMessage` -- validation error text; announced via live region when set
+- `requiredField` -- marks the field as required
+- `disabled` -- disables the input
+- `inputWidth` -- CSS width override for the input element
+- `isSubmit` -- renders the input as a submit input
+
+---
+
+## Events
+
+- `wmInputValueChanged` -- fires on each change to the input value; detail includes { value: string }
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

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

@@ -0,0 +1,32 @@
+# `wm-line-chart`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `decimalPlaces` | `decimal-places` | `number \| undefined` |  |  |  |
+| `description` | `description` | `string` | `""` |  |  |
+| `highlightEnd` | `highlight-end` | `string \| undefined` |  |  |  |
+| `highlightQualifier` | `highlight-qualifier` | `string` | `lineChartMessages.highlightQualifier` |  |  |
+| `highlightStart` | `highlight-start` | `string \| undefined` |  |  |  |
+| `label` | `label` | `string` |  | ✓ |  |
+| `labelWidth` | `label-width` | `string` | `"120px"` |  |  |
+| `lineData` | `line-data` | `string \| { [lineLabel: string]: Line; }` |  | ✓ |  |
+| `showDeltas` | `show-deltas` | `boolean` | `false` |  |  |
+| `showGrid` | `show-grid` | `boolean` | `true` |  |  |
+| `spotlightData` | `` | `SpotlightData \| undefined` |  |  |  |
+| `units` | `units` | `string` | `"null,null"` |  |  |
+| `visibilityToggles` | `visibility-toggles` | `boolean` | `false` |  |  |
+| `xAxisLabel` | `x-axis-label` | `string` |  | ✓ |  |
+| `yAxisLabel` | `y-axis-label` | `string` |  | ✓ |  |
+| `yRange` | `y-range` | `string \| undefined` |  |  |  |
+
+## Depends On
+
+- `wm-button`

package/dist/docs/wm-menuitem.md

@@ -0,0 +1,38 @@
+# `wm-menuitem`
+
+A single item within a wm-action-menu dropdown. Always used as a direct child of
+wm-action-menu -- never rendered in isolation.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `description` | `description` | `string \| undefined` | `undefined` |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `icon` | `icon` | `string \| undefined` | `undefined` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmEndKeyPressed` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmEscKeyPressed` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmHomeKeyPressed` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmKeyDownPressed` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmKeyUpPressed` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmLetterPressed` | `any` | ✓ |  |
+| `wmMenuitemBlurred` | `{ relatedTarget: EventTarget \| null; }` | ✓ |  |
+| `wmMenuitemClicked` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmPageDownItems` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmPageUpItems` | `HTMLWmMenuitemElement` | ✓ |  |
+| `wmTabKeyPressed` | `HTMLWmMenuitemElement` | ✓ |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | The visible label text for the menu item. |
+
+## Used By
+
+- `wm-file`

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

@@ -0,0 +1,106 @@
+# `wm-modal-footer`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `deleteStyle` | `delete-style` | `boolean` | `false` |  |  |
+| `infoText` | `info-text` | `string \| undefined` | `""` |  |  |
+| `primaryActionDisabled` | `primary-action-disabled` | `boolean` | `false` |  |  |
+| `primaryText` | `primary-text` | `string \| undefined` | `""` |  |  |
+| `secondaryText` | `secondary-text` | `string \| undefined` | `""` |  |  |
+
+## Depends On
+
+- `wm-button`
+
+# wm-modal
+
+## Purpose
+
+An overlay container that appears centered over the page and demands the user's full attention to complete a single, self-contained task before returning to the underlying content.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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
+
+---
+
+## Props
+
+- wm-modal props:
+- `uid` -- required; unique identifier for the modal instance
+- `open` -- controls visibility; always keep the component in the DOM and toggle this prop
+- `modalType` -- "modal" or "dialog"
+- `elementToFocus` -- which element receives focus when opened: "primary", "secondary", or any element ID
+- wm-modal-header props:
+- `heading` -- the modal title, announced by screen readers when the Modal opens
+- `subheading` -- optional secondary heading
+- wm-modal-footer props:
+- `primaryText` -- label for the primary action button
+- `secondaryText` -- label for the secondary action button
+- `primaryActionDisabled` -- disables the primary button
+- `deleteStyle` -- applies destructive styling to the footer
+- `infoText` -- supplementary text displayed in the footer
+
+---
+
+## Events
+
+- `wmModalPrimaryTriggered` -- fires when the primary footer button is activated
+- `wmModalSecondaryTriggered` -- fires when the secondary footer button is activated
+- `wmModalCloseTriggered` -- fires when the close button or Escape is used
+
+---
+
+## Methods
+
+- `emitCloseEvent()` -- programmatically emits the close event
+- `emitPrimaryEvent()` -- programmatically emits the primary event
+- `emitSecondaryEvent()` -- programmatically emits the secondary event
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

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

@@ -0,0 +1,100 @@
+# `wm-modal-header`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `heading` | `heading` | `string \| undefined` | `""` |  |  |
+| `subheading` | `subheading` | `string \| undefined` | `""` |  |  |
+
+## Depends On
+
+- `wm-button`
+
+# wm-modal
+
+## Purpose
+
+An overlay container that appears centered over the page and demands the user's full attention to complete a single, self-contained task before returning to the underlying content.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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
+
+---
+
+## Props
+
+- wm-modal props:
+- `uid` -- required; unique identifier for the modal instance
+- `open` -- controls visibility; always keep the component in the DOM and toggle this prop
+- `modalType` -- "modal" or "dialog"
+- `elementToFocus` -- which element receives focus when opened: "primary", "secondary", or any element ID
+- wm-modal-header props:
+- `heading` -- the modal title, announced by screen readers when the Modal opens
+- `subheading` -- optional secondary heading
+- wm-modal-footer props:
+- `primaryText` -- label for the primary action button
+- `secondaryText` -- label for the secondary action button
+- `primaryActionDisabled` -- disables the primary button
+- `deleteStyle` -- applies destructive styling to the footer
+- `infoText` -- supplementary text displayed in the footer
+
+---
+
+## Events
+
+- `wmModalPrimaryTriggered` -- fires when the primary footer button is activated
+- `wmModalSecondaryTriggered` -- fires when the secondary footer button is activated
+- `wmModalCloseTriggered` -- fires when the close button or Escape is used
+
+---
+
+## Methods
+
+- `emitCloseEvent()` -- programmatically emits the close event
+- `emitPrimaryEvent()` -- programmatically emits the primary event
+- `emitSecondaryEvent()` -- programmatically emits the secondary event
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-modal.md

@@ -0,0 +1,127 @@
+# `wm-modal`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `elementToFocus` | `element-to-focus` | `string` | `""` |  |  |
+| `modalType` | `modal-type` | `"dialog" \| "modal"` | `"modal"` |  |  |
+| `open` | `open` | `boolean` | `false` |  |  |
+| `uid` | `uid` | `string` |  | ✓ |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmModalCloseTriggered` | `any` |  |  |
+| `wmModalPrimaryTriggered` | `any` | ✓ |  |
+| `wmModalSecondaryTriggered` | `any` | ✓ |  |
+
+## Methods
+
+### `emitCloseEvent() => Promise<void>`
+
+**Returns** `Promise<void>` -- A promise that resolves once the event has been emitted.
+
+### `emitPrimaryEvent() => Promise<void>`
+
+**Returns** `Promise<void>` -- A promise that resolves once the event has been emitted.
+
+### `emitSecondaryEvent() => Promise<void>`
+
+**Returns** `Promise<void>` -- A promise that resolves once the event has been emitted.
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | Modal content: wm-modal-header, body content, and wm-modal-footer. |
+
+# wm-modal
+
+## Purpose
+
+An overlay container that appears centered over the page and demands the user's full attention to complete a single, self-contained task before returning to the underlying content.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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
+
+---
+
+## Props
+
+- wm-modal props:
+- `uid` -- required; unique identifier for the modal instance
+- `open` -- controls visibility; always keep the component in the DOM and toggle this prop
+- `modalType` -- "modal" or "dialog"
+- `elementToFocus` -- which element receives focus when opened: "primary", "secondary", or any element ID
+- wm-modal-header props:
+- `heading` -- the modal title, announced by screen readers when the Modal opens
+- `subheading` -- optional secondary heading
+- wm-modal-footer props:
+- `primaryText` -- label for the primary action button
+- `secondaryText` -- label for the secondary action button
+- `primaryActionDisabled` -- disables the primary button
+- `deleteStyle` -- applies destructive styling to the footer
+- `infoText` -- supplementary text displayed in the footer
+
+---
+
+## Events
+
+- `wmModalPrimaryTriggered` -- fires when the primary footer button is activated
+- `wmModalSecondaryTriggered` -- fires when the secondary footer button is activated
+- `wmModalCloseTriggered` -- fires when the close button or Escape is used
+
+---
+
+## Methods
+
+- `emitCloseEvent()` -- programmatically emits the close event
+- `emitPrimaryEvent()` -- programmatically emits the primary event
+- `emitSecondaryEvent()` -- programmatically emits the secondary event
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*