@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

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

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

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

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

@@ -0,0 +1,129 @@
+### Uploader
+- **Element:** `<wm-uploader>`
+- **Status:** stable
+
+**Purpose:** File upload component for attaching files. Composed of a trigger button and a list of
+wm-file children. Two variants: `'select'` opens the browser file picker; `'drop'` adds a
+drag-and-drop area. The component emits events when files are selected and when file
+actions are triggered -- the application is responsible for validation, upload, and managing
+the file list. Use wm-file-list instead when displaying files without uploading.
+
+**When to use:**
+
+- **Uploading files that will be stored and accessed later** -- when users need to attach supporting documents, evidence files, or other assets to a record (not to import data), Uploader is the right component; it is explicitly designed for file storage workflows, not data ingestion.
+- **File upload is part of the user's primary workflow** -- use the drop variant when users frequently upload documents and benefit from a prominent drag-and-drop area; use the select variant when uploading is a secondary action and a compact button trigger is more appropriate.
+- **Enforcing file type, size, or count constraints** -- when the upload has restrictions, use file-types, max-size, and max-files to communicate those constraints visibly to users; the component surfaces the constraints in the UI.
+- **Providing per-file actions after upload** -- when users need to preview, download, or delete individual uploaded files, use file-actions on each wm-file child to configure which actions are available per file.
+
+**Do not use for:**
+
+- **Read-only file display** -- if no new files need to be uploaded and the user only needs to view, download, or delete existing files, use wm-file-list instead; Uploader adds unnecessary upload affordances when no upload action is required.
+- **Full-page drop zone when multiple upload areas or competing page interactions exist** -- drop-area="page" is only appropriate when uploading is the singular primary action on that page.
+- **Not keeping progress up to date on wm-file during upload** -- the progress property must be kept current during upload to ensure the progress bar renders correctly and screen readers receive accurate status announcements. This is mandatory, not optional.
+
+**Variants / types:**
+
+- `uploader-type="select"` -- a compact button trigger for file selection
+- `uploader-type="drop"` -- a prominent drag-and-drop area
+- `drop-area="component"` -- the drop zone is scoped to the component itself
+- `drop-area="page"` -- the entire page acts as a drop zone; only appropriate when uploading is the singular primary action on the page
+
+**Props:**
+- `button-text` -- Label text on the upload trigger button, e.g. `'Attach files'`. Should
+match the action verb used in any surrounding instructions. _(required)_
+- `drop-area` -- Scope of the drop zone when `uploader-type="drop"`. `'component'` limits
+the drop area to the component; `'page'` expands it to cover the full page while dragging.
+- `error-message` -- Puts the uploader in an error state with this message (e.g. `'Please add at
+least one file'`).
+- `file-types` -- Space-separated file extensions displayed to the user as accepted types
+(e.g. `'pdf docx xlsx'`). Actual validation must be handled in the
+`wmUploaderFilesSelected` handler.
+- `icon` -- Icon displayed on the upload button. Accepts the same formats as wm-button:
+`'#icon-name'` for a Ripple icon or `'/path/to/file.svg#symbol-id'` for a local SVG
+sprite. _(required)_
+- `label` -- Optional label displayed above the upload button. Use when the uploader is
+required (pair with `required-field`) or needs a descriptive heading.
+- `max-files` -- Maximum number of files displayed to the user. Disables the upload button
+when reached. Validation must be handled in the application.
+- `max-size` -- Maximum file size displayed to the user (e.g. `'100 MB'`). Validation must
+be handled in the `wmUploaderFilesSelected` handler.
+- `required-field` -- Displays a required-field asterisk next to the label. Must be used together
+with the `label` prop.
+- `show-info` -- Which metadata to show for each wm-file child in the list.
+- `uploader-type` -- File selection method. `'select'` opens the browser file picker; `'drop'`
+adds a drag-and-drop area.
+
+**Events:**
+- `wmUploaderFilesSelected`
+
+**Accessibility:**
+
+- The number of in-progress uploads and aggregate upload percentage are announced via
+  `aria-live` regions.
+- Deletion focus is managed automatically: moves to the next file, then the previous file,
+  then the upload button.
+- The `progress` prop on wm-file children must be kept up to date for proper screen reader
+  accessibility.
+
+**Related components:**
+
+- `<wm-file-list>` -- if no new files need to be uploaded and the use case is purely displaying and acting on existing files, use File List; Uploader is only warranted when the user needs to add new files. The two are commonly paired: Uploader to add, File List to display files from a different source.
+- `<wm-button>` with a custom file input -- Uploader handles progress tracking, error states, per-file actions, accessibility, and responsive behavior that a bare button cannot; always prefer Uploader for file upload workflows.
+
+**Code example:**
+
+_Select variant_
+
+```html
+<wm-uploader button-text="Attach files" icon="#attach" label="Project documents">
+<wm-file id="f1" name="proposal" type="pdf" size="1.2 MB"></wm-file>
+</wm-uploader>
+```
+
+_Select variant with file list management_
+
+```react
+// wmUploaderFilesSelected emits a FileList -- use Array.from() to iterate.
+// Extract name (without extension) and type (extension only) for each wm-file child.
+// wmFileDelete fires on the wm-file element; use e.target.id to identify which to remove.
+// showInfo on the uploader propagates automatically to all wm-file children.
+let nextId = 1;
+const [files, setFiles] = useState([]);
+
+const handleFilesSelected = (e) => {
+const newFiles = Array.from(e.detail).map((file) => {
+const lastDot = file.name.lastIndexOf(".");
+const name = lastDot > 0 ? file.name.slice(0, lastDot) : file.name;
+const type = lastDot > 0 ? file.name.slice(lastDot + 1) : "file";
+return { id: String(nextId++), name, type, size: `${(file.size / 1024).toFixed(1)} KB` };
+});
+setFiles((prev) => [...prev, ...newFiles]);
+};
+
+const handleDelete = (e) => {
+const id = e.target.id;
+setFiles((prev) => prev.filter((f) => f.id !== id));
+};
+
+<WmUploader buttonText="Attach files" icon="#attach" label="Project documents" showInfo="size"
+onWmUploaderFilesSelected={handleFilesSelected}>
+{files.map((f) => (
+<WmFile key={f.id} id={f.id} name={f.name} type={f.type} size={f.size}
+onWmFileDelete={handleDelete} />
+))}
+</WmUploader>
+```
+
+_Drop variant_
+
+```html
+<wm-uploader uploader-type="drop" button-text="Upload files" icon="#upload">
+</wm-uploader>
+```
+
+_Drop variant_
+
+```react
+<WmUploader uploaderType="drop" buttonText="Upload files" icon="#upload"
+onWmUploaderFilesSelected={handleFilesSelected} />
+```

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

@@ -0,0 +1,6 @@
+### Wrapper
+- **Element:** `<wm-wrapper>`
+- **Status:** stable
+
+**Events:**
+- `wmWrapperLoaded`

package/dist/docs/wm-action-menu.md

@@ -0,0 +1,111 @@
+# `wm-action-menu`
+
+Dropdown interface that displays a list of action items. When closed it shows a text
+button, icon button, or selector box depending on action-menu-type. Selecting an item
+executes an action and closes the menu. Composed of a parent wm-action-menu element and
+one or more wm-menuitem children.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `actionMenuType` | `action-menu-type` | `"icon" \| "selector" \| "selector-primary" \| "text"` | `"icon"` |  |  |
+| `buttonText` | `button-text` | `string \| undefined` |  | when action-menu-type is 'text', 'selector', or 'selector-primary' |  |
+| `darkMode` | `dark-mode` | `boolean \| undefined` |  |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `labelForIdenticalButtons` | `label-for-identical-buttons` | `string \| undefined` |  |  |  |
+| `tooltip` | `tooltip` | `string \| undefined` |  | when action-menu-type is 'icon' |  |
+| `tooltipPosition` | `tooltip-position` | `"bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "right" \| "top" \| "top-left" \| "top-right" \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `menuLoaded` | `any` | ✓ |  |
+| `wmActionMenuLoaded` | `any` | ✓ |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | One or more wm-menuitem elements. |
+
+## Used By
+
+- `wm-file`
+
+# wm-action-menu
+
+## Purpose
+
+A dropdown component that groups multiple contextual actions behind a single trigger (an icon, text button, or selector) so users can choose and execute one action at a time without cluttering the interface with individual buttons.
+
+---
+
+## When to Use
+
+- **Offering several contextual actions on a row or item** -- when a record in a table or list has multiple possible actions (edit, duplicate, archive, delete), use Action Menu to collapse them behind a single icon trigger rather than rendering a row of buttons.
+- When some actions are secondary or infrequent enough that they do not warrant a persistent button, use a text or icon Action Menu to surface them on demand.
+- **Grouping actions in a space-constrained context** -- when screen real estate is tight (toolbars, card footers, dense data tables), use an icon Action Menu to keep the UI clean while still making all actions reachable.
+
+---
+
+## Do Not Use For
+
+- **A single action** -- if only one action is available, use wm-button directly; a menu that opens to reveal one item creates unnecessary friction.
+- **Setting a form field value** -- if the purpose is to pick an option that persists as a form value, use wm-select instead; the selector type is for actions, not form inputs.
+- **Binary decisions** -- if the user is choosing between exactly two opposing outcomes (approve/reject, yes/no), use wm-button with pairpositive and pairnegative; a dropdown is the wrong pattern for a binary choice.
+- **Icon menus without a tooltip** -- the tooltip is required for icon triggers and is the only thing that tells users and screen readers what the menu is for; omitting it produces an unlabeled control that fails accessibility.
+
+---
+
+## Related Components
+
+- `<wm-button>` -- if there is one specific, known action to take, use Button; if there are multiple actions to choose from, use Action Menu.
+- `<wm-select>` -- if the user is selecting a value to store or filter by, use Select; if selecting an option immediately triggers an action, use Action Menu's selector type.
+- `<wm-nested-select>` -- if the options are hierarchical and the result is a selected value, use Nested Select; Action Menu does not support nested option structures.
+
+---
+
+## Accessibility
+
+_Not documented_
+
+---
+
+## Variants / Types
+
+- `action-menu-type="icon"` -- a single icon button trigger; requires tooltip for accessibility
+- `action-menu-type="text"` -- a text button trigger; use button-text to set the label
+- `action-menu-type="selector"` -- a selector-style trigger for action-driven option picking
+- `action-menu-type="selector-primary"` -- a primary-weight selector trigger
+
+---
+
+## Props
+
+- `buttonText` -- label text for the trigger button when using the text type
+- `darkMode` -- enables dark mode styling
+- `disabled` -- disables the trigger and prevents the menu from opening
+- `labelForIdenticalButtons` -- provides screen readers with a more specific name when multiple Action Menus share the same label or icon
+- `tooltip` -- required for icon triggers; announced by screen readers as the accessible name
+- `tooltipPosition` -- controls where the tooltip appears relative to the trigger
+
+---
+
+## Events
+
+- `wmActionMenuLoaded` -- fires when the menu finishes loading
+- `menuLoaded` -- fires when the menu finishes loading
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-button.md

@@ -0,0 +1,137 @@
+# `wm-button`
+
+Interactive button element that triggers actions and workflows. Has seven visual
+types plus AI variants.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `ariaExpandedPassthrough` | `aria-expanded-passthrough` | `boolean \| undefined` |  |  |  |
+| `ariaLabelPassthrough` | `aria-label-passthrough` | `string \| undefined` |  |  |  |
+| `buttonType` | `button-type` | `"icononly" \| "icononly-ai" \| "navigational" \| "navigational-ai" \| "pairnegative" \| "pairpositive" \| "primary" \| "primary-ai" \| "secondary" \| "secondary-ai" \| "selector" \| "selector-primary" \| "textonly" \| "textonly-ai"` | `"secondary"` |  |  |
+| `customBackground` | `custom-background` | `string \| undefined` |  |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `icon` | `icon` | `string \| undefined` |  | when button-type is 'icononly' or 'navigational' (conditionallyRequired means that the prop is required, but only if the button-type is 'icononly' or 'navigational') |  |
+| `iconFlip` | `icon-flip` | `"horizontal" \| "vertical" \| undefined` |  |  |  |
+| `iconRotate` | `icon-rotate` | `number \| undefined` |  |  |  |
+| `iconSize` | `icon-size` | `string \| undefined` |  |  |  |
+| `isSubmit` | `is-submit` | `boolean` | `false` |  |  |
+| `labelForIdenticalButtons` | `label-for-identical-buttons` | `string \| undefined` |  | when multiple buttons on the same page share identical visible text or identical tooltips (conditionallyRequired means that the prop is required, but only if multiple buttons on the same page share identical visible text or identical tooltips) |  |
+| `permanentlyDelete` | `permanently-delete` | `boolean \| undefined` | `false` |  |  |
+| `textWrap` | `text-wrap` | `boolean` | `true` |  |  |
+| `tooltip` | `tooltip` | `string \| undefined` |  | when button-type is 'icononly' or 'navigational' (conditionallyRequired means that the prop is required, but only if the button-type is 'icononly' or 'navigational') |  |
+| `tooltipPosition` | `tooltip-position` | `"bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "right" \| "top" \| "top-left" \| "top-right"` | `"bottom-right"` |  |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | Button label text. Required for all types. For `icononly` and `navigational`
+buttons, slotted text is not rendered visually but is used as the accessible name
+when no `tooltip` or `label-for-identical-buttons` is provided. |
+
+## Used By
+
+- `wm-file`
+- `wm-flyout`
+- `wm-line-chart`
+- `wm-modal-footer`
+- `wm-modal-header`
+- `wm-modal-pss-footer`
+- `wm-modal-pss-header`
+- `wm-navigation`
+- `wm-search`
+- `wm-tab-list`
+
+# wm-button
+
+## Purpose
+
+Renders a consistently styled, accessible button that allows users to trigger actions or navigate, with seven visual types that signal the relative importance and nature of each action.
+
+---
+
+## When to Use
+
+- **Confirming a primary workflow action** -- use button-type="primary" when one clear, preferred action should stand out on a page or form, such as saving settings or submitting a report.
+- **Offering a secondary or cancel option alongside a primary action** -- use button-type="secondary" when pairing a less-preferred action next to a primary one, such as Cancel next to Save.
+- **Approving or rejecting with equal weight** -- use pairpositive and pairnegative together when two opposing actions carry no preference, such as an approve/reject decision.
+- **Triggering a destructive, irreversible action** -- use the permanently-delete prop when the user is about to take an action that cannot be undone.
+- **Performing a compact, recognizable action without a label** -- use button-type="icononly" when space is tight and the icon is universally understood, such as edit or delete in a data table.
+- **Completing an action and moving the user to a new context** -- use button-type="navigational" for buttons that both trigger an action and navigate, such as a back button in a flyout.
+
+---
+
+## Do Not Use For
+
+- **Icon-only buttons when the icon is not universally recognized** -- use a primary or secondary button with a text label instead.
+- **Destructive styling (permanently-delete) on routine or reversible deletions** -- reserve it for actions that truly cannot be undone.
+- **Multiple primary buttons in the same section** -- there should ideally be only one per page or section.
+- **Lists of contextual actions (edit, duplicate, archive, delete)** -- use wm-action-menu instead.
+
+---
+
+## Related Components
+
+- `<wm-action-menu>` -- if the interaction triggers one of several contextual actions, use Action Menu; if there is one specific, known action, use Button.
+
+---
+
+## Accessibility
+
+_Not documented_
+
+---
+
+## Variants / Types
+
+- `button-type="primary"` -- the single preferred action on a page or form
+- `button-type="secondary"` -- a supporting or cancel action paired with a primary
+- `button-type="textonly"` -- a low-emphasis action with no button chrome
+- `button-type="icononly"` -- a compact action identified solely by a universally recognized icon
+- `button-type="navigational"` -- an action that also moves the user to a new context
+- `button-type="selector"` -- a toggle-style selection button
+- `button-type="selector-primary"` -- a primary-weight selection button
+- `button-type="pairpositive"` -- the affirmative action in an equal-weight approve/reject pair
+- `button-type="pairnegative"` -- the rejecting action in an equal-weight approve/reject pair
+- `button-type="primary-ai"` -- primary variant for AI-generated or AI-assisted actions
+- `button-type="secondary-ai"` -- secondary variant for AI context
+- `button-type="textonly-ai"` -- text-only variant for AI context
+- `button-type="icononly-ai"` -- icon-only variant for AI context
+- `button-type="navigational-ai"` -- navigational variant for AI context
+
+---
+
+## Props
+
+- `customBackground` -- overrides the background color; use only when a specific brand or contextual color is required
+- `disabled` -- disables the button and prevents interaction
+- `icon` -- icon to display; uses Ripple custom #kebab-case names (e.g. #show, #close), not Material Design names
+- `iconFlip` -- flips the icon "horizontal" or "vertical"
+- `iconRotate` -- rotates the icon by a number of degrees
+- `iconSize` -- overrides the default icon size
+- `isSubmit` -- renders the button as a form submit button
+- `labelForIdenticalButtons` -- provides screen readers with a more specific label when multiple buttons share the same visible text
+- `permanentlyDelete` -- applies destructive styling; use only for irreversible actions
+- `textWrap` -- allows the button label to wrap to a second line
+- `tooltip` -- required for icononly and navigational buttons; screen readers announce this as the accessible name
+- `tooltipPosition` -- controls where the tooltip appears relative to the button
+
+---
+
+## Events
+
+_None exposed_
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

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

@@ -0,0 +1,23 @@
+# `wm-chart-bar`
+
+Renders a horizontal bar chart for comparing values across nominal categories. Data and
+configuration are set via JavaScript properties (`chart.config` and `chart.data`) -- not
+HTML attributes. Supports single-color, discrete palette, semantic palette, and grouped bars.
+
+**Preferred** over wm-chart's bar subtypes for all comparison and distribution use cases.
+Use this component (or wm-chart-column) instead of `<wm-chart chart-type="bar*">`.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `config` | `` | `undefined \| { label: string; showLabel: boolean; valueAxisLabel: string; categoryAxisLabel: string; printMode: boolean; printModeFormat: "amount" \| "percentage"; gridMax: number \| "auto"; sort?: "ascending" \| "descending" \| "none" \| undefined; showLegend?: "top" \| "bottom" \| "left" \| "right" \| "none" \| undefined; showGrid?: boolean \| undefined; subinfo?: string \| undefined; valueFormat?: "amount" \| "percentage" \| "none" \| undefined; colors?: string \| undefined; popoverTitle?: string \| undefined; popoverText?: string \| undefined; popoverButtonText?: string \| undefined; decimalPlaces?: number \| undefined; patternMode?: boolean \| undefined; }` |  |  |  |
+| `data` | `` | `ChartData[] \| undefined` |  |  |  |
+| `patternMode` | `pattern-mode` | `boolean \| undefined` |  |  |  |
+| `printMode` | `print-mode` | `boolean \| undefined` |  |  |  |
+| `subinfo` | `subinfo` | `string \| undefined` |  |  |  |
+
+## Depends On
+
+- `wm-chart-legend`
+- `priv-chart-popover`

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

@@ -0,0 +1,26 @@
+# `wm-chart-column`
+
+Renders a vertical column chart for comparing values across nominal categories or showing
+distribution across interval/ratio ranges. Data and configuration are set via JavaScript
+properties (`chart.config` and `chart.data`) -- not HTML attributes. Supports single-color,
+discrete palette, semantic palette, and grouped columns.
+
+**Preferred** over wm-chart's bar subtypes for comparison and distribution use cases.
+Use this component (or wm-chart-bar) instead of `<wm-chart chart-type="bar*">`. When
+columns exceed available width, the chart scrolls horizontally.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `config` | `` | `undefined \| { label: string; showLabel: boolean; valueAxisLabel: string; categoryAxisLabel: string; printMode: boolean; printModeFormat: "amount" \| "percentage"; gridMax: number \| "auto"; sort?: "ascending" \| "descending" \| "none" \| undefined; showLegend?: "top" \| "bottom" \| "left" \| "right" \| "none" \| undefined; showGrid?: boolean \| undefined; subinfo?: string \| undefined; valueFormat?: "amount" \| "percentage" \| "none" \| undefined; colors?: string \| undefined; popoverTitle?: string \| undefined; popoverText?: string \| undefined; popoverButtonText?: string \| undefined; decimalPlaces?: number \| undefined; patternMode?: boolean \| undefined; }` |  |  |  |
+| `data` | `` | `ChartData[] \| undefined` |  |  |  |
+| `patternMode` | `pattern-mode` | `boolean \| undefined` |  |  |  |
+| `printMode` | `print-mode` | `boolean \| undefined` |  |  |  |
+| `printWidth` | `print-width` | `string \| undefined` |  |  |  |
+| `subinfo` | `subinfo` | `string \| undefined` |  |  |  |
+
+## Depends On
+
+- `wm-chart-legend`
+- `priv-chart-popover`