@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -0,0 +1,174 @@
+### Flyout
+- **Element:** `<wm-flyout>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**Variants / types:**
+
+_None documented_
+
+**Props:**
+- `breadcrumb` -- Comma-separated list of breadcrumb labels rendered above the heading.
+The last item is displayed as plain text (current step); earlier items are rendered as
+buttons that fire `wmFlyoutBreadcrumbClicked`.
+- `element-to-focus` -- Element to focus when the flyout opens. Pass `"primary"` or `"secondary"` to
+focus the corresponding footer button, or an element `id` to focus a specific element in the
+flyout body. Defaults to the close button.
+- `eyebrow` -- Small label displayed above the heading. Useful for context like a category or record type.
+- `flyout-width` -- CSS width value for the flyout panel. Capped at 90% of the viewport width,
+and at 100% on viewports narrower than 534px.
+- `heading` -- Heading text displayed at the top of the flyout. Also used as the dialog's accessible name. _(required)_
+- `info-text` -- Informational text displayed in the lower-left corner of the footer
+(e.g. `"* Required fields"`).
+- `open` -- Controls the open/closed state of the flyout. Always render the component on
+page load and toggle this prop rather than conditionally mounting/unmounting the element.
+- `primary-text` -- Label for the primary footer button. When set, a primary button is rendered
+in the footer. Fires `wmFlyoutPrimaryTriggered` when clicked.
+- `secondary-text` -- Label for the secondary footer button. When set, a secondary button is rendered
+in the footer. Fires `wmFlyoutSecondaryTriggered` when clicked.
+- `subheading` -- Subtitle text displayed below the heading.
+
+**Events:**
+- `wmFlyoutBreadcrumbClicked`
+- `wmFlyoutCloseTriggered`
+- `wmFlyoutPrimaryTriggered`
+- `wmFlyoutSecondaryTriggered`
+
+**Methods:**
+- `focusHeading() => Promise<void>`
+
+**Accessibility:**
+
+- Rendered as a `<dialog>` element with `aria-labelledby` pointing to the heading.
+- Focus is trapped inside the flyout while open and returns to the trigger element on close.
+- Call `focusHeading()` after updating content in a multi-step workflow so screen readers
+  announce the new heading.
+- **Keyboard:** - **Escape**: Fires `wmFlyoutCloseTriggered` (the host application is responsible for setting `open` to false).
+- **Tab**: Cycles forward through focusable elements; wraps from the last element back to the first.
+- **Shift+Tab**: Cycles backward; wraps from the first element to the last footer button.
+
+**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.
+
+**Code example:**
+
+_Basic flyout_
+
+```html
+<button onclick="document.getElementById('edit-profile').open = true">Open flyout</button>
+
+<wm-flyout id="edit-profile" heading="Edit profile" eyebrow="Student"
+subheading="Update your information below"
+primary-text="Save" secondary-text="Cancel" info-text="* Required fields">
+<div class="flyout-content">
+<wm-input label="First name *"></wm-input>
+<wm-input label="Last name *"></wm-input>
+<wm-input label="Email" type="email"></wm-input>
+</div>
+</wm-flyout>
+```
+
+_Basic flyout_
+
+```react
+// Set open imperatively via ref -- use onClick on the trigger, not onWmButtonClicked.
+const flyoutRef = useRef(null);
+
+const openFlyout = () => { flyoutRef.current.open = true; };
+const closeFlyout = () => { flyoutRef.current.open = false; };
+
+<WmButton onClick={openFlyout}>Open flyout</WmButton>
+
+<WmFlyout
+ref={flyoutRef}
+heading="Edit profile"
+eyebrow="Student"
+subheading="Update your information below"
+primaryText="Save"
+secondaryText="Cancel"
+infoText="* Required fields"
+onWmFlyoutCloseTriggered={closeFlyout}
+onWmFlyoutSecondaryTriggered={closeFlyout}
+onWmFlyoutPrimaryTriggered={closeFlyout}
+>
+<div className="flyout-content">
+<WmInput label="First name *" />
+<WmInput label="Last name *" />
+<WmInput label="Email" type="email" />
+</div>
+</WmFlyout>
+```
+
+_Multi-step flyout with breadcrumbs_
+
+```html
+<button onclick="document.getElementById('multi-step').open = true">Open multi-step flyout</button>
+
+<wm-flyout id="multi-step" heading="Vestibulum convallis"
+breadcrumb="Vestibulum convallis"
+primary-text="Next" secondary-text="Cancel">
+<div id="step1" class="flyout-content"><p>Step 1 content</p></div>
+<div id="step2" class="flyout-content" style="display:none"><p>Step 2 content</p></div>
+</wm-flyout>
+```
+
+_Multi-step flyout with breadcrumbs_
+
+```react
+// Drive heading/breadcrumb/primaryText/secondaryText from step state so React keeps them
+// in sync on re-render. Use useEffect to call focusHeading() after the DOM has updated.
+const flyoutRef = useRef(null);
+const [step, setStep] = useState(0);
+const [focusHeading, setFocusHeading] = useState(false);
+
+const steps = [
+{ heading: "Vestibulum convallis", breadcrumb: "Vestibulum convallis", primaryText: "Next", secondaryText: "Cancel" },
+{ heading: "Dignissim magna", breadcrumb: "Vestibulum convallis,Dignissim magna", primaryText: "Submit", secondaryText: "Back" },
+];
+
+useEffect(() => {
+if (focusHeading) {
+flyoutRef.current.focusHeading();
+setFocusHeading(false);
+}
+}, [step, focusHeading]);
+
+const goToStep = (idx) => { setStep(idx); setFocusHeading(true); };
+const handlePrimary = () => { step === 0 ? goToStep(1) : (flyoutRef.current.open = false); };
+const handleSecondary = () => { step === 0 ? (flyoutRef.current.open = false) : goToStep(0); };
+
+<WmButton onClick={() => { setStep(0); flyoutRef.current.open = true; }}>Open flyout</WmButton>
+
+<WmFlyout
+ref={flyoutRef}
+heading={steps[step].heading}
+breadcrumb={steps[step].breadcrumb}
+primaryText={steps[step].primaryText}
+secondaryText={steps[step].secondaryText}
+onWmFlyoutPrimaryTriggered={handlePrimary}
+onWmFlyoutSecondaryTriggered={handleSecondary}
+onWmFlyoutCloseTriggered={() => { flyoutRef.current.open = false; }}
+onWmFlyoutBreadcrumbClicked={(ev) => goToStep(ev.detail.index)}
+>
+{step === 0 && <div className="flyout-content"><WmInput label="Program name *" /></div>}
+{step === 1 && <div className="flyout-content"><WmInput label="Start date" /></div>}
+</WmFlyout>
+```

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

@@ -0,0 +1,126 @@
+### Input
+- **Element:** `<wm-input>`
+- **Status:** stable
+
+**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
+
+**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.
+- `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.
+- `is-submit` -- When true, pressing Enter when the input is focused submits the containing form.
+- `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.
+- `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.
+- `required-field` -- Displays a required-field asterisk (*) next to the label and sets `aria-required="true"` on the input.
+- `step` -- For use with `type='number'`. The interval between values when stepping.
+- `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`.
+- `value` -- The initial value of the input field, or its current value when reading from the component.
+
+**Events:**
+- `wmInputValueChanged`
+
+**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,108 @@
+### Line Chart
+- **Element:** `<wm-line-chart>`
+- **Status:** stable
+
+**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.
+
+**Variants / types:**
+
+- `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.
+- `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"`).
+- `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.
+- `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 } }`. _(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.
+- `show-grid` -- When true, renders horizontal and vertical grid lines.
+- `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 }`.
+- `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"`.
+- `visibility-toggles` -- When true, renders hide/show toggle buttons in the legend, allowing users to
+hide individual lines.
+- `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.
+
+**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,72 @@
+### Menuitem
+- **Element:** `<wm-menuitem>`
+- **Status:** stable
+
+**Purpose:** A single item within a wm-action-menu dropdown. Always used as a direct child of
+wm-action-menu -- never rendered in isolation.
+
+**Variants / types:**
+
+- `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.
+- `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`.
+
+**Events:**
+- `wmEndKeyPressed`
+- `wmEscKeyPressed`
+- `wmHomeKeyPressed`
+- `wmKeyDownPressed`
+- `wmKeyUpPressed`
+- `wmLetterPressed`
+- `wmMenuitemBlurred`
+- `wmMenuitemClicked`
+- `wmPageDownItems`
+- `wmPageUpItems`
+- `wmTabKeyPressed`
+
+**Accessibility:**
+
+- Rendered with `role="menuitem"` and `aria-disabled` when disabled.
+- Keyboard events (Arrow keys, Home, End, Tab, Escape, character keys) are captured and
+  re-emitted as custom events consumed by the parent wm-action-menu to manage focus and
+  menu state -- do not listen to these events directly in application code.
+
+**Code example:**
+
+_Basic menu items_
+
+```html
+<wm-action-menu tooltip="Actions">
+<wm-menuitem>Edit</wm-menuitem>
+<wm-menuitem>Delete</wm-menuitem>
+</wm-action-menu>
+```
+
+_Basic menu items_
+
+```react
+<WmActionMenu tooltip="Actions">
+<WmMenuitem>Edit</WmMenuitem>
+<WmMenuitem>Delete</WmMenuitem>
+</WmActionMenu>
+```
+
+_Menu item with icon_
+
+```html
+<wm-menuitem icon="#edit">Edit</wm-menuitem>
+```
+
+_Disabled menu item_
+
+```react
+<WmMenuitem disabled={true}>Export</WmMenuitem>
+```

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

@@ -0,0 +1,73 @@
+### Modal Footer
+- **Element:** `<wm-modal-footer>`
+- **Status:** stable
+
+**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
+
+**Props:**
+- `delete-style` -- Renders the primary button in the wm-button `permanently-delete` destructive
+style. Use for irreversible actions.
+- `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"`.
+- `primary-action-disabled` -- Disables the primary action button.
+- `primary-text` -- Label for the primary action button.
+- `secondary-text` -- Label for the secondary action button. Omit to render the footer with only
+a primary button.
+
+**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,65 @@
+### Modal Header
+- **Element:** `<wm-modal-header>`
+- **Status:** stable
+
+**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
+
+**Props:**
+- `heading` -- The main title text displayed in the modal header.
+- `subheading` -- Optional descriptive text displayed below the heading. Should not be used
+when the parent modal has `modal-type="dialog"`.
+
+**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." />
+```