@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/skill/index.md

@@ -0,0 +1,32 @@
+## Component Index
+
+| Component | Tag | File | Category |
+|-----------|-----|------|----------|
+| **Action Menu** | `wm-action-menu` | `wm-action-menu.md` | Basic Controls |
+| **Button** | `wm-button` | `wm-button.md` | Basic Controls |
+| **Nested Select** | `wm-nested-select` | `wm-nested-select.md` | Basic Controls |
+| **Select** | `wm-select` | `wm-select.md` | Basic Controls |
+| **Flyout** | `wm-flyout` | `wm-flyout.md` | Communication |
+| **Modal & Dialog** | `wm-modal` | `wm-modal.md` | Communication |
+| **Snackbar** | `wm-snackbar` | `wm-snackbar.md` | Communication |
+| **Toggletip** | `wm-toggletip` | `wm-toggletip.md` | Communication |
+| **Bar Chart** | `wm-chart-bar` | `wm-chart-bar.md` | Data Visualization |
+| **Chart** | `wm-chart` | `wm-chart.md` | Data Visualization |
+| **Chart Legend** | `wm-chart-legend` | `wm-chart-legend.md` | Data Visualization |
+| **Column Chart** | `wm-chart-column` | `wm-chart-column.md` | Data Visualization |
+| **Line Chart** | `wm-line-chart` | `wm-line-chart.md` | Data Visualization |
+| **Progress Monitor** | `wm-progress-monitor` | `wm-progress-monitor.md` | Data Visualization |
+| **Date Range** | `wm-date-range` | `wm-date-range.md` | Form Inputs |
+| **Datepicker** | `wm-datepicker` | `wm-datepicker.md` | Form Inputs |
+| **File List** | `wm-file-list` | `wm-file-list.md` | Form Inputs |
+| **Input** | `wm-input` | `wm-input.md` | Form Inputs |
+| **Search** | `wm-search` | `wm-search.md` | Form Inputs |
+| **Tag Input** | `wm-tag-input` | `wm-tag-input.md` | Form Inputs |
+| **Textarea** | `wm-textarea` | `wm-textarea.md` | Form Inputs |
+| **Timepicker** | `wm-timepicker` | `wm-timepicker.md` | Form Inputs |
+| **Uploader** | `wm-uploader` | `wm-uploader.md` | Form Inputs |
+| **Navigation** | `wm-navigation` | `wm-navigation.md` | Navigation |
+| **Navigator** | `wm-navigator` | `wm-navigator.md` | Navigation |
+| **Pagination** | `wm-pagination` | `wm-pagination.md` | Navigation |
+| **Tabs** | `wm-tab-list` | `wm-tab-list.md` | Navigation |
+| **Wrapper** | `wm-wrapper` | `wm-wrapper.md` | Layout Containers |

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

@@ -0,0 +1,93 @@
+### Action Menu
+- **Element:** `<wm-action-menu>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**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.
+
+**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:**
+- `action-menu-type` -- Visual style of the trigger button. `'icon'` shows an icon-only button (requires `tooltip`). `'text'` shows a labelled button (requires `button-text`). `'selector'` shows a selector box that visually mimics a select control (requires `button-text`). `'selector-primary'` is a primary-styled variant of selector.
+- `button-text` -- Label displayed on the trigger button. _(conditionally required: when action-menu-type is 'text', 'selector', or 'selector-primary')_
+- `dark-mode` -- Applies dark styling to `selector` and `selector-primary` variants. Has no effect on `icon` or `text` types.
+- `disabled` -- Disables the entire menu, preventing the trigger from being activated.
+- `label-for-identical-buttons` -- Use only when multiple action menus on the same page share identical tooltips or button text. Set this to a more descriptive label for screen readers; the visible label stays unchanged. Sets aria-label to this value.
+- `tooltip` -- Tooltip text shown on hover. For `icon` menus, also serves as the accessible name announced by screen readers. _(conditionally required: when action-menu-type is 'icon')_
+- `tooltip-position` -- Position of the tooltip relative to the trigger button. Repositions automatically when there is insufficient space at the specified position.
+
+**Events:**
+- `menuLoaded`
+- `wmActionMenuLoaded`
+
+**Accessibility:**
+
+- For `icon` menus, `tooltip` is required and serves as the accessible name announced by screen readers.
+- When multiple action menus share identical tooltips or button text, use `label-for-identical-buttons` to give each a unique `aria-label`.
+- Focus returns automatically to the trigger button after an item is activated, unless the action removes the trigger from the DOM -- in that case, manage focus explicitly in your action handler.
+- **Keyboard:** - **Trigger button (closed)**: Down Arrow / Space / Enter opens the menu and focuses the first item; Up Arrow opens and focuses the last item.
+- **Open menu**: Up/Down Arrow navigates items (wraps around); Home/End jumps to first/last; Enter activates the focused item and closes the menu; Escape closes the menu and returns focus to the trigger; Tab closes the menu; typing a character focuses the next item starting with that letter.
+
+**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.
+
+**Code example:**
+
+_Icon action menu (default)_
+
+```html
+<wm-action-menu tooltip="More options">
+<wm-menuitem>Edit</wm-menuitem>
+<wm-menuitem>Delete</wm-menuitem>
+</wm-action-menu>
+```
+
+_Icon action menu_
+
+```react
+<WmActionMenu tooltip="More options">
+<WmMenuitem>Edit</WmMenuitem>
+<WmMenuitem>Delete</WmMenuitem>
+</WmActionMenu>
+```
+
+_Text action menu_
+
+```html
+<wm-action-menu action-menu-type="text" button-text="Actions">
+<wm-menuitem>Edit</wm-menuitem>
+<wm-menuitem>Delete</wm-menuitem>
+</wm-action-menu>
+```
+
+_Text action menu_
+
+```react
+<WmActionMenu actionMenuType="text" buttonText="Actions">
+<WmMenuitem>Edit</WmMenuitem>
+<WmMenuitem>Delete</WmMenuitem>
+</WmActionMenu>
+```

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

@@ -0,0 +1,103 @@
+### Button
+- **Element:** `<wm-button>`
+- **Status:** stable
+
+**Purpose:** Interactive button element that triggers actions and workflows. Has seven visual
+types plus AI variants.
+
+**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.
+
+**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:**
+- `aria-expanded-passthrough` -- Sets the button's `aria-expanded` attribute. Use on buttons that toggle a disclosure region,
+menu, popover, or dialog. Use this prop instead of setting `aria-expanded` directly on
+`<wm-button>`.
+- `aria-label-passthrough` -- Sets the button's `aria-label`. Takes priority over `label-for-identical-buttons` and over
+the label automatically derived from `tooltip` for `icononly` and `navigational` buttons. Use
+this prop instead of setting `aria-label` directly on `<wm-button>`.
+- `button-type` -- Visual style of the button. 'primary' for the single preferred action (use sparingly, ideally once per page/section). 'secondary' for other actions, often alongside a primary. 'textonly' for low-emphasis actions. 'icononly' requires icon and tooltip. 'navigational' for icon-only back/forward navigation (e.g. flyout back button). 'pairpositive' and 'pairnegative' must be used together for binary choices (neither is preferred, e.g. Approve/Reject). AI variants apply AI styling automatically -- do not set the icon property on AI types. 'selector' and 'selector-primary' are internal types used by wm-select -- do not use directly.
+- `custom-background` -- Set to 'dark' to render button styles appropriate for a dark background surface.
+- `disabled` -- Disables the button, preventing interaction and applying disabled styling.
+- `icon` -- Icon to display. Required when button-type is 'icononly' or 'navigational'. Formats: '#icon-name' for a commonly-used Ripple icon (e.g. '#edit', '#add-person'), '/path/to/file.svg#symbol-id' for a local SVG sprite symbol, or an MDI character code like 'f3eb' (deprecated). Do not set on AI button types -- their icon is applied automatically. _(conditionally required: when button-type is 'icononly' or 'navigational')_
+- `icon-flip` -- Flips the icon along the specified axis. For use with the icon property.
+- `icon-rotate` -- Rotates the icon by the given number of degrees. For use with the icon property.
+- `icon-size` -- Overrides the default icon size. Accepts any valid CSS size value, e.g. '22px' or '1.3rem'.
+- `is-submit` -- When true, the button submits its containing form. Equivalent to type="submit" on a native button element.
+- `label-for-identical-buttons` -- Accessibility prop. Use ONLY when multiple buttons on the same page share identical visible text or identical tooltips. Set this to a more descriptive label for screen readers; leave the visible button text or tooltip unchanged. Sets aria-label to this value. _(conditionally required: when multiple buttons on the same page share identical visible text or identical tooltips)_
+- `permanently-delete` -- Applies danger/destructive styling to the button. Use sparingly and only for irreversible destructive actions (e.g. permanently deleting an account or record). Applied as a modifier -- not a separate button-type.
+- `text-wrap` -- For 'textonly' buttons only. When false, text is truncated with an ellipsis and a tooltip reveals the full text on hover.
+- `tooltip` -- Tooltip text displayed on hover. _(conditionally required: when button-type is 'icononly' or 'navigational')_
+- `tooltip-position` -- Position of the tooltip relative to the button. If there is insufficient space at the specified position, the component repositions automatically.
+
+**Accessibility:**
+
+`aria-label` resolution order (highest priority first):
+1. `aria-label-passthrough`
+2. `label-for-identical-buttons` (or `tooltip` for icononly/navigational types)
+3. Nothing set -- browser derives the label from visible text or slotted content
+
+`aria-expanded` -- set via `aria-expanded-passthrough` (not directly on `<wm-button>`).
+`aria-haspopup="menu"` -- applied automatically when the host element has an `aria-haspopup` attribute.
+- **Keyboard:** Enter - Fires a click event on the button (mirrors native button behavior).
+
+**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.
+
+**Code example:**
+
+_Primary button -- the preferred action on a page or section. Use once per context._
+
+```html
+<wm-button button-type="primary">Save changes</wm-button>
+```
+
+_Primary button_
+
+```react
+<WmButton buttonType="primary" onClick={handleSave}>Save changes</WmButton>
+```
+
+_Primary and secondary pair -- the most common pattern._
+
+```html
+<wm-button button-type="secondary">Cancel</wm-button>
+<wm-button button-type="primary">Save changes</wm-button>
+```
+
+_Primary and secondary pair_
+
+```react
+<WmButton buttonType="secondary" onClick={handleCancel}>Cancel</WmButton>
+<WmButton buttonType="primary" onClick={handleSave}>Save changes</WmButton>
+```

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

@@ -0,0 +1,129 @@
+### Chart Bar
+- **Element:** `<wm-chart-bar>`
+- **Status:** stable
+
+**Purpose:** 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*">`.
+
+**Variants / types:**
+
+- Set `id` on the element to use with an external `wm-chart-legend` via `chart-ids`.
+- For grouped charts, each `ChartData` item must include a `groupName` field.
+- `config.gridMax: "auto"` calculates a "nice" round upper bound from the data.
+- Bars exceeding the `gridMax` are clipped -- set an appropriate `gridMax` to avoid this.
+
+**Props:**
+- `config` -- Chart configuration object. Set via JavaScript property -- not an HTML
+attribute. See the `ChartConfig` interface for the full list of options (label, gridMax,
+valueFormat, colors, showLegend, etc.).
+- `data` -- Array of data items to render. Set via JavaScript property -- not an HTML
+attribute. Each item must include at least `barLegend` and `amount`; grouped charts also
+require `groupName`. See the `ChartData` interface.
+- `pattern-mode` -- When true, applies a hatching pattern fill to bars in addition to color,
+improving distinguishability for users with color vision deficiencies. Takes precedence
+over `config.patternMode`.
+- `print-mode` -- When true, bar values are included in the legend and keyboard interaction
+instructions are removed from the DOM -- suitable for printed output. Takes precedence over
+`config.printMode`.
+- `subinfo` -- Optional secondary text displayed beneath the chart label. Takes precedence
+over `config.subinfo`.
+
+**Accessibility:**
+
+- `config.label` is required -- used as the chart's `aria-label`.
+- Each bar receives an `aria-label` composed of the category axis label, group name (if
+  grouped), bar legend, and display value.
+- The chart renders with `role="application"` and `aria-roledescription="Interactive chart"`.
+- In `print-mode`, keyboard interaction instructions are removed from the DOM.
+- **Keyboard:** - **Tab**: Enters the chart wrapper.
+- **Arrow Down / Right**: Focuses the first bar; subsequent presses cycle to the next bar.
+- **Arrow Up / Left**: Cycles to the previous bar.
+- **Enter**: Activates the popover button when the popover is open.
+- **Escape**: Closes the open popover.
+- **Tab** (from within): Exits the chart and clears focus.
+
+**Code example:**
+
+_Single-color bar chart_
+
+```html
+<wm-chart-bar id="enrollment-chart"></wm-chart-bar>
+<script>
+const chart = document.querySelector('#enrollment-chart');
+chart.config = { label: 'Enrollment by program', gridMax: 'auto', valueFormat: 'amount' };
+chart.data = [{ barLegend: 'Biology', amount: 310 }, { barLegend: 'English', amount: 280 }];
+</script>
+```
+
+_Single-color bar chart_
+
+```react
+// config and data must be set via JavaScript properties in useEffect -- not as JSX props.
+const singleRef = useRef(null);
+
+useEffect(() => {
+singleRef.current.config = {
+label: 'Enrollment by program',
+gridMax: 'auto',
+valueFormat: 'amount',
+popoverTitle: 'Details',
+};
+singleRef.current.data = [
+{ barLegend: 'Biology', amount: 310, popoverText: '310 students enrolled' },
+{ barLegend: 'English', amount: 280, popoverText: '280 students enrolled' },
+{ barLegend: 'History', amount: 195, popoverText: '195 students enrolled' },
+{ barLegend: 'Chemistry', amount: 240, popoverText: '240 students enrolled' },
+];
+}, []);
+
+<WmChartBar ref={singleRef} />
+```
+
+_Grouped bar chart_
+
+```html
+<wm-chart-bar id="grouped-chart"></wm-chart-bar>
+<script>
+const chart = document.querySelector('#grouped-chart');
+chart.config = { label: 'Retention by cohort and program', gridMax: 'auto',
+categoryAxisLabel: 'Cohort', valueAxisLabel: 'Students', showLegend: 'bottom' };
+chart.data = [
+{ barLegend: 'Biology', amount: 120, groupName: '2022', popoverTitle: 'Biology -- 2022', popoverText: '120 students retained' },
+{ barLegend: 'English', amount: 95, groupName: '2022', popoverTitle: 'English -- 2022', popoverText: '95 students retained' },
+{ barLegend: 'Biology', amount: 135, groupName: '2023', popoverTitle: 'Biology -- 2023', popoverText: '135 students retained' },
+{ barLegend: 'English', amount: 110, groupName: '2023', popoverTitle: 'English -- 2023', popoverText: '110 students retained' },
+];
+</script>
+```
+
+_Grouped bar chart_
+
+```react
+// config and data must be set via JavaScript properties in useEffect -- not as JSX props.
+const groupedRef = useRef(null);
+
+useEffect(() => {
+groupedRef.current.config = {
+label: 'Retention by cohort and program',
+gridMax: 'auto',
+valueFormat: 'amount',
+categoryAxisLabel: 'Cohort',
+valueAxisLabel: 'Students',
+showLegend: 'bottom',
+};
+groupedRef.current.data = [
+{ barLegend: 'Biology', amount: 120, groupName: '2022', popoverTitle: 'Biology -- 2022', popoverText: '120 students retained' },
+{ barLegend: 'English', amount: 95, groupName: '2022', popoverTitle: 'English -- 2022', popoverText: '95 students retained' },
+{ barLegend: 'History', amount: 80, groupName: '2022', popoverTitle: 'History -- 2022', popoverText: '80 students retained' },
+{ barLegend: 'Biology', amount: 135, groupName: '2023', popoverTitle: 'Biology -- 2023', popoverText: '135 students retained' },
+{ barLegend: 'English', amount: 110, groupName: '2023', popoverTitle: 'English -- 2023', popoverText: '110 students retained' },
+{ barLegend: 'History', amount: 72, groupName: '2023', popoverTitle: 'History -- 2023', popoverText: '72 students retained' },
+];
+}, []);
+
+<WmChartBar ref={groupedRef} />
+```

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

@@ -0,0 +1,96 @@
+### Chart Column
+- **Element:** `<wm-chart-column>`
+- **Status:** stable
+
+**Purpose:** 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.
+
+**Variants / types:**
+
+- Set `id` on the element to use with an external `wm-chart-legend` via `chart-ids`.
+- Use `print-width` to fix chart width for exported PDFs or print stylesheets (accepts `px`,
+  `in`, or `cm`). The chart will wrap columns across multiple plots when they exceed the
+  available `print-width`.
+- For grouped charts, each `ChartData` item must include a `groupName` field.
+
+**Props:**
+- `config` -- Chart configuration object. Set via JavaScript property -- not an HTML
+attribute. See the `ChartConfig` interface for the full list of options (label, gridMax,
+valueFormat, colors, showLegend, etc.).
+- `data` -- Array of data items to render. Set via JavaScript property -- not an HTML
+attribute. Each item must include at least `barLegend` and `amount`; grouped charts also
+require `groupName`. See the `ChartData` interface.
+- `pattern-mode` -- When true, applies a hatching pattern fill to columns in addition to color,
+improving distinguishability for users with color vision deficiencies. Takes precedence
+over `config.patternMode`.
+- `print-mode` -- When true, column values are included in the legend and keyboard interaction
+instructions are removed from the DOM -- suitable for printed output. Takes precedence over
+`config.printMode`.
+- `print-width` -- Fixed chart width for print or PDF export. Accepts `px`, `in`, or `cm` (e.g.
+`"7.5in"`). When set alongside `print-mode` or during `window.print()`, columns that
+exceed the available width wrap across multiple plot rows.
+- `subinfo` -- Optional secondary text displayed beneath the chart label. Takes precedence
+over `config.subinfo`.
+
+**Accessibility:**
+
+- `config.label` is required -- used as the chart's `aria-label`.
+- Each column receives an `aria-label` composed of the category axis label, group name (if
+  grouped), bar legend, and display value.
+- The chart renders with `role="application"` and `aria-roledescription="Interactive chart"`.
+- In `print-mode`, keyboard interaction instructions are removed from the DOM.
+- **Keyboard:** - **Tab**: Enters the chart wrapper.
+- **Arrow Down / Right**: Focuses the first column; subsequent presses cycle to the next.
+- **Arrow Up / Left**: Cycles to the previous column.
+- **Enter**: Activates the popover button when the popover is open.
+- **Escape**: Closes the open popover.
+- **Tab** (from within): Exits the chart and clears focus.
+
+**Code example:**
+
+_Single-color column chart_
+
+```html
+<wm-chart-column id="enrollment-chart"></wm-chart-column>
+<script>
+const chart = document.querySelector('#enrollment-chart');
+chart.config = { label: 'Enrollment by term', gridMax: 'auto', valueFormat: 'amount',
+categoryAxisLabel: 'Term', valueAxisLabel: 'Students' };
+chart.data = [{ barLegend: 'Fall 2023', amount: 310 }, { barLegend: 'Spring 2024', amount: 280 }];
+</script>
+```
+
+_Single-color column chart_
+
+```react
+<WmChartColumn ref={chartRef} />
+// In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+```
+
+_Grouped column chart_
+
+```html
+<wm-chart-column id="grouped-chart"></wm-chart-column>
+<script>
+const chart = document.querySelector('#grouped-chart');
+chart.config = { label: 'Enrollment by term and program', gridMax: 'auto',
+showLegend: 'bottom' };
+chart.data = [
+{ barLegend: 'Biology', amount: 120, groupName: 'Fall 2023' },
+{ barLegend: 'English', amount: 95, groupName: 'Fall 2023' },
+];
+</script>
+```
+
+_Grouped column chart_
+
+```react
+<WmChartColumn ref={chartRef} />
+// In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+```

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

@@ -0,0 +1,67 @@
+### Chart Legend
+- **Element:** `<wm-chart-legend>`
+- **Status:** stable
+
+**Purpose:** External legend component for wm-chart-bar and wm-chart-column. Retrieves color and label
+data from one or more charts via element IDs, allowing a single legend to serve multiple
+charts. Hidden from screen readers -- relevant data is announced when the user interacts with
+the associated chart directly.
+
+For simple single-chart scenarios, the `config.showLegend` option on wm-chart-bar or
+wm-chart-column renders an internal legend without requiring this element. Use
+wm-chart-legend when sharing one legend across multiple charts or when external placement
+is required.
+
+**Variants / types:**
+
+- Assign an `id` to each chart and pass those IDs (space-separated) to `chart-ids`.
+- Clicking or hovering a legend item highlights the corresponding bar(s) in all associated
+  charts.
+
+**Props:**
+- `chart-ids` -- Space-separated list of element IDs of the wm-chart-bar or wm-chart-column
+elements this legend serves. The legend derives its color swatches and labels from these
+charts automatically.
+- `orientation` -- Layout orientation of legend items.
+- `print-mode` -- When true, the print value for each item is shown next to its swatch in the
+legend -- suitable for printed output.
+
+**Events:**
+- `wmLegendItemClick`
+- `wmLegendItemHover`
+
+**Code example:**
+
+_Shared legend for two charts_
+
+```html
+<wm-chart-legend chart-ids="chart-a chart-b"></wm-chart-legend>
+<wm-chart-bar id="chart-a"></wm-chart-bar>
+<wm-chart-bar id="chart-b"></wm-chart-bar>
+```
+
+_Shared legend for two charts_
+
+```react
+const [activeIdx, setActiveIdx] = useState(null);
+
+const handleClick = (event) => {
+setActiveIdx(event.detail.idx);
+};
+
+<WmChartLegend chartIds="chart-a chart-b" onWmLegendItemClick={handleClick} />
+<WmChartBar id="chart-a" />
+<WmChartBar id="chart-b" />
+```
+
+_Vertical orientation_
+
+```html
+<wm-chart-legend chart-ids="my-chart" orientation="vertical"></wm-chart-legend>
+```
+
+_Vertical orientation_
+
+```react
+<WmChartLegend chartIds="my-chart" orientation="vertical" />
+```

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

@@ -0,0 +1,55 @@
+### Chart Slice
+- **Element:** `<wm-chart-slice>`
+- **Status:** stable
+
+**Purpose:** Data slice for a wm-chart composition chart. Each slice represents one segment of the whole.
+Always used as a direct child of wm-chart.
+
+**Variants / types:**
+
+- A `legend` is required unless `amount` is `0` or omitted -- the component throws if a
+  non-zero amount is provided without a legend.
+- Slices without an `amount` are not rendered but still occupy a color slot, preserving
+  consistent color assignment when some data points are conditionally absent.
+- Use `popover-title`, `popover-text`, and `popover-button-text` to surface additional
+  context when a segment is focused or clicked.
+
+**Props:**
+- `amount` -- Numeric value for this slice as a string. Slices with no amount (or `0`) are
+not rendered but still occupy a color slot.
+- `legend` -- Label for this slice in the legend and popovers. Required when `amount` is
+greater than zero.
+- `popover-button-text` -- Label for the action button in the data popover. When set, the popover
+renders a button and fires `wmChartPopoverButtonTriggered` when clicked.
+- `popover-text` -- Body text shown in the data popover when this segment is focused or clicked.
+- `popover-title` -- Title text shown in the data popover when this segment is focused or clicked.
+
+**Code example:**
+
+_Basic slice_
+
+```html
+<wm-chart-slice legend="Enrolled" amount="310"></wm-chart-slice>
+```
+
+_Basic slice_
+
+```react
+<WmChartSlice legend="Enrolled" amount="310" />
+```
+
+_Slice with popover_
+
+```html
+<wm-chart-slice legend="At risk" amount="45"
+popover-title="45 students" popover-text="Flagged for early intervention"
+popover-button-text="View students"></wm-chart-slice>
+```
+
+_Slice with popover_
+
+```react
+<WmChartSlice legend="At risk" amount="45"
+popoverTitle="45 students" popoverText="Flagged for early intervention"
+popoverButtonText="View students" />
+```