@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,153 @@
+### Datepicker
+- **Element:** `<wm-datepicker>`
+
+**Purpose:** Date input that lets users type a date or pick one from a calendar popup. Supports
+configurable date formats, pre-selection, validation, and full keyboard navigation of the calendar.
+Use instead of native `<input type="date">`.
+
+**When to use:**
+
+- **Collecting a single date value in a form** -- when a user needs to provide one specific date (a due date, start date, birth date, submission deadline), Datepicker is the standard input, offering both typed entry for speed and a calendar popup for browsing.
+
+**Do not use for:**
+
+- **Selecting a start and end date together** -- if the input represents a range, use wm-date-range instead; Datepicker only captures a single date and has no concept of a paired second value.
+- **Inputs where time is also required** -- Datepicker captures dates only; if the user also needs to specify a time, pair it with wm-timepicker rather than expecting Datepicker to handle both.
+
+**Variants / types:**
+
+_None documented_
+
+**Usage notes:**
+
+- Set `value` in the same format as `date-format` (default `mm/dd/yyyy`). For programmatic date
+  setting, prefer ISO format via `preselected` and convert with the `reformatDate` method.
+- The calendar popup hides its toggle automatically when there is no room to display it; always
+  allow users to type a date directly in the input as a fallback.
+
+**Props:**
+- `date-format` -- The expected date format. Shown in the input placeholder and announced to screen reader users. _(default: `"mm/dd/yyyy"`)_
+- `disabled` -- Disables the datepicker, preventing all interaction. _(default: `false`)_
+- `error-message` -- Puts the component in an error state and displays this message below the input.
+- `label` -- Visible label for the input. Required even when `label-position` is `'none'` -- used as the ARIA accessible name. _(required; default: `""`)_
+- `label-position` -- Position of the label relative to the input. `'none'` hides the label visually but keeps it accessible via `aria-label`. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `preselected` -- The date the calendar popup focuses when first opened, in ISO format (YYYY-MM-DD). Falls back to the parsed `value`, then the current date if neither can be parsed.
+- `required-field` -- Displays a required-field asterisk (*) next to the label. _(default: `false`)_
+- `value` -- The date displayed in the input field, in the format specified by `date-format`. Updated as the user types. Can also be set programmatically by the application. _(default: `""`)_
+
+**Events:**
+- `wmDatepickerDateSelected` -- Fires when the user selects a date from the calendar popup. Detail: `{{ date: string }} date -- the selected date in ISO format (YYYY-MM-DD).`
+- `wmDatepickerInputBlurred` -- Fires when the text input loses focus.
+
+**Methods:**
+- `isValidIso(input?: string) => Promise<boolean>` -- Validates whether a string is a well-formed, calendar-correct ISO date
+(YYYY-MM-DD). Accounts for invalid day-of-month values and leap years.
+  - `input` -- - The string to validate.
+  - **Returns:** `true` if the string is a valid ISO date, `false` otherwise.
+  - **Example:** `isValidIso("1969-06-20") // -> true`
+  - **Example:** `isValidIso("1969-06-33") // -> false (day 33 does not exist)`
+  - **Example:** `isValidIso("2023-02-29") // -> false (2023 is not a leap year)`
+- `reformatDate(inputFormat: "US" | "INT" | "ISO", outputFormat: "US" | "INT" | "ISO", date?: string) => Promise<string>` -- Converts a date string between the supported format tokens: `"US"` (mm/dd/yyyy),
+`"INT"` (dd/mm/yyyy), and `"ISO"` (YYYY-MM-DD). Direct US ↔ INT conversion is not supported --
+route through ISO as an intermediate step.
+  - `inputFormat` -- - Format of the input date string.
+  - `outputFormat` -- - Desired output format.
+  - `date` -- - The date string to reformat.
+  - **Returns:** The reformatted date string, an empty string if `date` is omitted or falsy, or the
+original string unchanged if it cannot be parsed.
+  - **Example:** `reformatDate("US", "ISO", "06/20/1969") // -> "1969-06-20"`
+  - **Example:** `reformatDate("ISO", "US", "1969-06-20") // -> "06/20/1969"`
+
+**Accessibility:**
+
+- `label` is required even when `label-position` is `"none"` -- it becomes the input's `aria-label`.
+- The calendar toggle button announces "Select date" to screen readers and reflects `aria-expanded`.
+- Validation errors are announced via an `aria-live` region when `error-message` changes.
+- When the input value cannot be parsed as a valid date, the calendar opens to the current date.
+- **Keyboard:**
+  - **Input field**: Tab moves focus to the calendar toggle button.
+  - **Calendar toggle**: Space / Enter / Down Arrow opens the calendar; Shift+Tab returns to the input.
+  - **Day grid**: Arrow keys navigate dates; Enter selects; Escape closes and returns focus to the toggle;
+  Home/End jump to the first/last day of the month; Tab cycles through calendar controls.
+  - **Month/year selectors**: Arrow keys cycle values; Tab/Shift+Tab move focus clockwise/counter-clockwise.
+
+**Related components:**
+
+- `<wm-date-range>` -- if the user needs to select both a start and end date together, use Date Range; Datepicker is for a single date only.
+- `<wm-timepicker>` -- if a time of day is also required alongside the date, pair Datepicker with Timepicker; Datepicker has no time input capability.
+- `<wm-input>` -- if the value being collected looks like a date but has no need for calendar navigation or date validation (e.g., a free-form year field), a plain Input may be sufficient; Datepicker is warranted when the calendar picker or date validation utilities add genuine value.
+
+**Code example:**
+
+_Basic datepicker_
+
+```html
+<wm-datepicker label="Start date"></wm-datepicker>
+```
+
+_Basic datepicker_
+
+```react
+// The component does not update its own value after a calendar selection --
+// the app must call reformatDate and set value/errorMessage imperatively via a ref.
+const ref = useRef(null);
+
+function getFormatName(format) {
+const map = { 'mm/dd/yyyy': 'US', 'dd/mm/yyyy': 'INT', 'yyyy/mm/dd': 'ISO' };
+return format ? map[format] : 'US';
+}
+
+// event.detail is { date: string } -- ISO 8601 (YYYY-MM-DD)
+const handleDateSelected = async (event) => {
+const dp = ref.current;
+const fmt = getFormatName(dp.getAttribute('date-format'));
+dp.value = await dp.reformatDate('ISO', fmt, event.detail.date);
+dp.errorMessage = '';
+};
+
+const handleInputBlurred = async () => {
+const dp = ref.current;
+const fmt = getFormatName(dp.getAttribute('date-format'));
+if (dp.value) {
+const iso = await dp.reformatDate(fmt, 'ISO', dp.value);
+if (await dp.isValidIso(iso)) {
+dp.value = await dp.reformatDate('ISO', fmt, iso);
+dp.errorMessage = '';
+} else {
+dp.errorMessage = `Please enter a valid date in the format ${dp.getAttribute('date-format') ?? 'mm/dd/yyyy'}`;
+}
+}
+};
+
+const handleBlur = () => {
+const dp = ref.current;
+if (dp.requiredField && dp.value === '') dp.errorMessage = 'A date is required';
+};
+
+<WmDatepicker
+ref={ref}
+label="Start date"
+onWmDatepickerDateSelected={handleDateSelected}
+onWmDatepickerInputBlurred={handleInputBlurred}
+onBlur={handleBlur}
+/>
+```
+
+_Required field with validation_
+
+```html
+<wm-datepicker label="Date of birth" required-field></wm-datepicker>
+```
+
+_Required field with validation_
+
+```react
+<WmDatepicker
+ref={ref}
+label="Date of birth"
+requiredField={true}
+onWmDatepickerDateSelected={handleDateSelected}
+onWmDatepickerInputBlurred={handleInputBlurred}
+onBlur={handleBlur}
+/>
+```

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

@@ -0,0 +1,105 @@
+### File List
+- **Element:** `<wm-file-list>`
+
+**Purpose:** Read-only list of files with optional preview and download actions. Visually similar to the
+Uploader but with no upload capability. Use when displaying existing files users can view or
+download, not when they need to upload new ones.
+
+**When to use:**
+
+- **Displaying files already associated with a record** -- when a page or form needs to show files that have previously been uploaded or attached (e.g., supporting documents on a profile, attachments on a submission), use File List to surface them with consistent metadata and actions.
+- **Allowing users to download or preview existing files** -- when the user's relationship to the files is read-access (they need to open or save a file but not replace it), use File List with file-actions="preview download" on each wm-file.
+- **Surfacing file-level error states** -- when a specific file in the list has failed validation or processing, use the error-message property on the individual wm-file to communicate the problem at the file level rather than at the form level.
+
+**Do not use for:**
+
+- **Accepting new file uploads** -- File List is explicitly read-only and has no upload mechanism; if users need to add files, use wm-uploader instead, and pair it with File List to show what has already been uploaded.
+- **Empty states** -- File List has no empty state handling built in; if the list may be empty and that state needs a message or call to action, the surrounding page must handle that.
+- **General-purpose lists of records** -- File List is purpose-built for files with extensions, metadata, and file-specific actions; it is not a substitute for a generic list or table of records.
+
+**Variants / types:**
+
+_None documented_
+
+**Usage notes:**
+
+- Each child wm-file requires a unique `id`, a `name`, and a `type` (file extension).
+- Set `show-info` on wm-file-list to apply the same metadata display to all children -- each
+  wm-file inherits it automatically. Individual wm-file elements can still override it.
+
+**Props:**
+- `show-info` -- Which metadata to display for each file alongside its name. Propagated
+automatically to all wm-file children. _(type: `"all" | "last-updated" | "none" | "size" | "uploaded-by"`; default: `"last-updated"`)_
+
+**Slots:**
+- _(default)_ -- One or more wm-file child elements.
+
+**Related components:**
+
+- `<wm-uploader>` -- if users need to add new files, use Uploader; File List is strictly for displaying and acting on files that already exist. The two are commonly paired: Uploader to add, File List to review what has been added.
+
+**Code example:**
+
+_File list with default metadata (last-updated)_
+
+```html
+<wm-file-list>
+<wm-file id="file-1" name="report" type="pdf" last-updated="1/28/2020 5:29 PM"></wm-file>
+<wm-file id="file-2" name="thesis" type="docx" last-updated="3/15/2024 9:00 AM"></wm-file>
+</wm-file-list>
+```
+
+_File list with managed state_
+
+```react
+// wm-file-list does not manage its own state -- drive the file list from React state.
+// wmFileDelete fires on the wm-file element; use e.target.id to remove the matching entry.
+// showInfo on wm-file-list propagates automatically to all wm-file children.
+const [files, setFiles] = useState([
+{ id: "file-1", name: "annual-report", type: "pdf", lastUpdated: "1/28/2024 5:29 PM" },
+{ id: "file-2", name: "budget-summary", type: "xlsx", lastUpdated: "3/15/2024 9:00 AM" },
+]);
+
+<WmFileList>
+{files.map((f) => (
+<WmFile key={f.id} id={f.id} name={f.name} type={f.type} lastUpdated={f.lastUpdated}
+onWmFileDelete={(e) => setFiles((prev) => prev.filter((f) => f.id !== e.target.id))} />
+))}
+</WmFileList>
+```
+
+_Show all metadata_
+
+```html
+<wm-file-list show-info="all">
+<wm-file id="file-1" name="report" type="pdf"
+size="3 MB" last-updated="1/28/2020 5:29 PM" uploaded-by="Uploaded by Smith, John">
+</wm-file>
+</wm-file-list>
+```
+
+_Show all metadata with preview and download handlers_
+
+```react
+// fileActions controls which buttons appear; omit delete or pass fileActions="" for none.
+// onWmFilePreview and onWmFileDownload fire on the wm-file element; e.target.name is the filename.
+const [files, setFiles] = useState([
+{ id: "file-3", name: "thesis", type: "docx", size: "3.2 MB",
+lastUpdated: "1/28/2024 5:29 PM", uploadedBy: "Uploaded by Smith, John",
+fileActions: "preview download delete" },
+{ id: "file-4", name: "presentation", type: "pptx", size: "8.5 MB",
+lastUpdated: "3/15/2024 9:00 AM", uploadedBy: "Uploaded by Doe, Jane",
+fileActions: "download delete" },
+]);
+
+<WmFileList showInfo="all">
+{files.map((f) => (
+<WmFile key={f.id} id={f.id} name={f.name} type={f.type}
+size={f.size} lastUpdated={f.lastUpdated} uploadedBy={f.uploadedBy}
+fileActions={f.fileActions}
+onWmFilePreview={(e) => alert(`Preview: ${e.target.name}`)}
+onWmFileDownload={(e) => alert(`Download: ${e.target.name}`)}
+onWmFileDelete={(e) => setFiles((prev) => prev.filter((f) => f.id !== e.target.id))} />
+))}
+</WmFileList>
+```

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

@@ -0,0 +1,91 @@
+### File
+- **Element:** `<wm-file>`
+
+**Purpose:** Displays a single file row with its name, optional metadata, and configurable action buttons
+(preview, download, delete). Adapts responsively -- at narrow widths action buttons collapse
+into an action menu. Used as a child of wm-file-list or wm-uploader.
+
+**Usage notes:**
+
+- A unique `id` is required on every wm-file element.
+- `name` and `type` are both required; `type` is the file extension only (e.g. `pdf`, not a MIME type).
+- `show-info` is automatically inherited from the parent wm-file-list or wm-uploader when set there.
+- Pass an empty string to `file-actions` to render no action buttons.
+
+**Props:**
+- `error-message` -- Puts the file row in an error state and displays this message below it.
+- `file-actions` -- Space-separated list of action buttons to display. Accepts any combination of
+`preview`, `download`, and `delete`. Pass an empty string to show no actions. _(default: `"download delete"`)_
+- `last-updated` -- Upload date/time displayed as file metadata. Any display string is accepted
+(e.g. `"1/28/2020 5:29 PM"`).
+- `name` -- Filename without the extension. _(required)_
+- `progress` -- Upload progress as a percentage (0-100). When set and less than 100, the file
+renders in an in-progress state with a progress bar.
+- `show-info` -- Which metadata to display alongside the filename. Automatically inherited
+from the parent wm-file-list or wm-uploader when set there. _(type: `"all" | "last-updated" | "none" | "size" | "time" | "uploaded-by"`; default: `"last-updated"`)_
+- `size` -- File size displayed as file metadata. Include the unit in the string
+(e.g. `"3 MB"`).
+- `type` -- File extension without the leading dot (e.g. `pdf`, `docx`). Not a MIME type. _(required)_
+- `uploaded-by` -- Uploader attribution displayed as file metadata
+(e.g. `"Uploaded by Smith, John"`).
+
+**Events:**
+- `wmFileDelete` -- Fires when the delete button is clicked.
+- `wmFileDownload` -- Fires when the download button is clicked.
+- `wmFileErrorCleared` -- Fires when the user clears a file error by clicking the Clear button.
+- `wmFilePreview` -- Fires when the preview button is clicked.
+
+**Required setup:**
+
+- Render it inside wm-file-list or wm-uploader; it is not a standalone control.
+- Give every wm-file a unique `id`. Its events carry no detail, so `event.target` is the only way
+  to tell which file was acted on.
+- Handle the events for whichever buttons `file-actions` renders -- `wmFileDelete`,
+  `wmFileDownload`, `wmFilePreview` -- bearing in mind it defaults to download and delete.
+  Deleting is not automatic: wm-uploader listens for `wmFileDelete` only to move focus, so the row
+  stays on screen until you drop the file from your own state.
+- Handle `wmFileErrorCleared` by clearing the `error-message` you set; the parent only restores
+  focus to the upload button.
+- Update `progress` as an upload proceeds; it drives the progress bar and the aria-live
+  announcement.
+
+**Accessibility:**
+
+- Icon-only action buttons include context-specific aria labels that embed the filename
+  (e.g. "Download report.pdf") so screen reader users know which file each button acts on.
+- A visually-hidden `aria-live` region announces upload progress and validation errors.
+
+**Code example:**
+
+_Basic file row_
+
+```html
+<wm-file-list>
+<wm-file id="file-1" name="report" type="pdf" last-updated="1/28/2020 5:29 PM"></wm-file>
+</wm-file-list>
+```
+
+_Basic file row_
+
+```react
+<WmFileList>
+<WmFile id="file-1" name="report" type="pdf" lastUpdated="1/28/2020 5:29 PM" />
+</WmFileList>
+```
+
+_All metadata and all actions_
+
+```html
+<wm-file id="file-2" name="thesis" type="docx" file-actions="preview download delete"
+show-info="all" size="3 MB" last-updated="3/15/2024 9:00 AM"
+uploaded-by="Uploaded by Smith, John">
+</wm-file>
+```
+
+_All metadata and all actions_
+
+```react
+<WmFile id="file-2" name="thesis" type="docx" fileActions="preview download delete"
+showInfo="all" size="3 MB" lastUpdated="3/15/2024 9:00 AM"
+uploadedBy="Uploaded by Smith, John" />
+```

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

@@ -0,0 +1,209 @@
+### Flyout
+- **Element:** `<wm-flyout>`
+
+**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_
+
+**Usage notes:**
+
+- Always render the component on page load -- do not conditionally mount/unmount based on
+  visibility. Control visibility with the `open` prop instead.
+- The flyout does not close on outside clicks; the host application must handle close events
+  and set `open` to false.
+- In React, set `open` imperatively via a ref (`ref.current.open = true/false`), and open the
+  flyout from a click handler on the trigger element.
+- Use `element-to-focus` to shift initial focus away from the default close button, e.g. to
+  the `primary` footer button or a specific element id for form workflows.
+- In a multi-step workflow, drive `heading`, `breadcrumb`, `primaryText`, and `secondaryText`
+  from React state so they update on re-render. Call `ref.current.focusHeading()` inside a
+  `useEffect` that runs after the step state change so screen readers announce the new heading.
+- Apply content padding via a container query on the flyout body wrapper so it reduces
+  automatically on narrower flyout widths:
+  ```css
+  .flyout-content { padding: 1.25rem 1.875rem; }
+
+**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. _(default: `""`)_
+- `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. _(default: `"45rem"`)_
+- `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. _(default: `false`)_
+- `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.
+
+**Slots:**
+- _(default)_ -- Main content of the flyout body.
+
+**Events:**
+- `wmFlyoutBreadcrumbClicked` -- Fires when a breadcrumb button (any non-last breadcrumb) is clicked. Detail: `{{ breadcrumb: string, index: number }} breadcrumb -- the label of the clicked breadcrumb; index -- its zero-based position in the original CSV list.`
+- `wmFlyoutCloseTriggered` -- Fires when the close button is clicked, Escape is pressed, or the native
+dialog close event fires. The host application must set `open` to false in response.
+- `wmFlyoutPrimaryTriggered` -- Fires when the primary footer button is clicked.
+- `wmFlyoutSecondaryTriggered` -- Fires when the secondary footer button is clicked.
+
+**Methods:**
+- `focusHeading() => Promise<void>` -- Moves focus to the flyout's heading element. Call this after updating flyout
+content in a multi-step workflow so screen readers announce the new heading to the user.
+  - **Returns:** A promise that resolves once focus has been applied.
+
+**Required setup:**
+
+- Drive `open` from your own state: true to show the flyout, false to hide it.
+- Handle `wmFlyoutCloseTriggered` by setting `open = false`. It covers the close button and
+  Escape, which are the only close paths -- there is no outside-click dismissal.
+- Handle `wmFlyoutPrimaryTriggered` and `wmFlyoutSecondaryTriggered` for whichever footer buttons
+  `primary-text` and `secondary-text` render, setting `open = false` to dismiss.
+- For multi-step flows, drive `heading`, `breadcrumb`, and the button text from state, call
+  `focusHeading()` after each step change, and handle `wmFlyoutBreadcrumbClicked` (`event.detail`
+  is `{ breadcrumb, index }`) to step backwards.
+
+**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.
+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>
+```