@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/docs/skill/index.md

@@ -0,0 +1,33 @@
+## 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 |
+| **Stack Chart** | `wm-chart-stack` | `wm-chart-stack.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,116 @@
+### Action Menu
+- **Element:** `<wm-action-menu>`
+
+**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
+
+**Usage notes:**
+
+- The default type is `icon` (three-dot "more options" button). Use `text` for a labelled trigger, `selector` or `selector-primary` for a select-box appearance.
+- `button-text` is required when `action-menu-type` is `text`, `selector`, or `selector-primary`.
+- `tooltip` is required when `action-menu-type` is `icon`.
+- `icon` is optional for `text`, `selector`, and `selector-primary` types, rendered alongside `button-text`. For `icon` type, `icon` overrides the default "more options" icon.
+
+**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. _(type: `"icon" | "selector" | "selector-primary" | "text"`; default: `"icon"`)_
+- `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. _(default: `false`)_
+- `icon` -- Icon to display alongside `button-text` for `text`, `selector`, and `selector-primary`
+types, or in place of the default "more options" icon for the `icon` type. Formats: `'#icon-name'`
+for a Ripple icon (e.g. `'#edit'`), or `'/path/to/file.svg#symbol-id'` for a local SVG sprite symbol.
+- `icon-flip` -- Flips the icon along the specified axis. For use with the icon property. _(type: `"horizontal" | "vertical"`)_
+- `icon-rotate` -- Rotates the icon by the given number of degrees. For use with the icon property.
+- `icon-size` -- Change size of the icon to fine tune the visual rendering if it appears too large or small. Not
+intended for general sizing. Accepts any valid CSS size value, e.g. '22px' or '1.3rem'.
+- `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.
+- `max-width` -- Maximum width of the dropdown. Accepts any valid CSS width value (e.g. "300px", "20rem", "50%"). The dropdown may still render narrower to fit its content or the space available. _(default: `"25.875rem"`)_
+- `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. _(type: `"bottom" | "bottom-left" | "bottom-right" | "left" | "right" | "top" | "top-left" | "top-right"`)_
+
+**Slots:**
+- _(default)_ -- One or more wm-menuitem elements.
+
+**Events:**
+- `menuLoaded` -- Fires when the component finishes loading. _(deprecated: Use wmActionMenuLoaded instead.)_
+- `wmActionMenuLoaded` -- Fires when the component finishes loading and child wm-menuitem elements are ready.
+
+**Required setup:**
+
+- Wire each item's action: attach an `onclick` handler to each wm-menuitem.
+- Slot one wm-menuitem per action as a child.
+
+**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 onclick="editRecord()">Edit</wm-menuitem>
+<wm-menuitem onclick="deleteRecord()">Delete</wm-menuitem>
+</wm-action-menu>
+```
+
+_Icon action menu_
+
+```react
+<WmActionMenu tooltip="More options">
+<WmMenuitem onClick={editRecord}>Edit</WmMenuitem>
+<WmMenuitem onClick={deleteRecord}>Delete</WmMenuitem>
+</WmActionMenu>
+```
+
+_Icon action menu with a custom icon_
+
+```html
+<wm-action-menu icon="#filter" tooltip="Filter options">
+<wm-menuitem>All</wm-menuitem>
+<wm-menuitem>Unread</wm-menuitem>
+</wm-action-menu>
+```
+
+_Icon action menu with a custom icon_
+
+```react
+<WmActionMenu icon="#filter" tooltip="Filter options">
+<WmMenuitem>All</WmMenuitem>
+<WmMenuitem>Unread</WmMenuitem>
+</WmActionMenu>
+```

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

@@ -0,0 +1,121 @@
+### Button
+- **Element:** `<wm-button>`
+
+**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
+
+**Usage notes:**
+
+- **primary**: Use sparingly -- ideally once per page or section -- for the single most
+  important action.
+- **pairpositive / pairnegative**: Must always be used together for binary choices where
+  neither option is preferred (e.g. Approve / Reject). Do not use one without the other.
+- **AI variants** (`primary-ai`, `secondary-ai`, etc.): Do not set the `icon` prop --
+  the AI icon is applied automatically.
+- **icononly / navigational**: Both `icon` and `tooltip` are required.
+- Do not use slotted text (emoji, Unicode glyphs, or characters styled to look like an icon)
+  to simulate an icon. Use the `icon` prop so the icon is rendered as a proper SVG/MDI glyph
+  with correct sizing, color, and accessibility treatment.
+
+**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. _(type: `"icononly" | "icononly-ai" | "navigational" | "navigational-ai" | "pairnegative" | "pairpositive" | "primary" | "primary-ai" | "secondary" | "secondary-ai" | "selector" | "selector-primary" | "textonly" | "textonly-ai"`; default: `"secondary"`)_
+- `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. _(default: `false`)_
+- `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. _(type: `"horizontal" | "vertical"`)_
+- `icon-rotate` -- Rotates the icon by the given number of degrees. For use with the icon property.
+- `icon-size` -- Change size of the icon to fine tune the visual rendering if it appears too large or small. Not
+intended for general sizing. 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. _(default: `false`)_
+- `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. _(default: `false`)_
+- `text-wrap` -- For 'textonly' buttons only. When false, text is truncated with an ellipsis and a tooltip reveals the full text on hover. _(default: `true`)_
+- `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. _(type: `"bottom" | "bottom-left" | "bottom-right" | "left" | "right" | "top" | "top-left" | "top-right"`; default: `"bottom-right"`)_
+
+**Slots:**
+- _(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.
+
+**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,156 @@
+### Chart Bar
+- **Element:** `<wm-chart-bar>`
+
+**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*">`.
+
+**When to use:**
+
+- **Comparing values across nominal categories** -- when the goal is to compare independent quantities across a set of categories (e.g., enrollment by program), this is the primary comparison component.
+- **Many categories or long category labels** -- the horizontal orientation gives labels room to read, so prefer Bar Chart over Column Chart when there are many categories or the labels are long.
+- **Grouped comparison** -- when each category has sub-series to compare side by side, provide a `groupName` on each data item for grouped bars.
+
+**Do not use for:**
+
+- **Composition / parts of a whole** -- use `wm-chart` (for a doughnut chart) or `wm-chart-stack` (for a stacked bar chart). Bars show independent magnitudes, not segments of a total.
+- **Data changing over time (trends)** -- use `wm-line-chart`.
+- **Binary completion tracking** -- use `wm-progress-monitor`.
+- **Vertical orientation or fewer categories** -- consider `wm-chart-column`.
+
+**Variants / types:**
+
+- **Single-color** -- one color for every bar; best for a single series where the categories carry no qualitative meaning and the goal is simply to compare magnitudes.
+- **Discrete palette** (`colors: "discrete"`) -- cycles a set of visually distinct colors so each category reads as its own thing. Use when the categories are nominal -- no inherent order or good/bad meaning (e.g., departments, courses, activity types) -- and color is only there to tell them apart.
+- **Semantic palette** (`colors: "semantic"`) -- maps color to meaning rather than to identity. Use when the categories carry positive / negative / status meaning (e.g., Met vs. Not Met, Exceeded vs. Below, or a progress state) and the color should reinforce that meaning. Avoid it for merely nominal categories -- applying good/bad colors to neutral data misleads the reader.
+- **Grouped** -- multiple series per category, provided via a `groupName` on each data item.
+
+**Usage notes:**
+
+- 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.). _(type: `undefined | { label: string; showLabel: boolean; valueAxisLabel: string; categoryAxisLabel: string; printMode: boolean; printModeFormat: "amount" | "percentage"; gridMax: number | "auto"; sort?: "ascending" | "descending" | "none"; showLegend?: "top" | "bottom" | "left" | "right" | "none"; showGrid?: boolean; subinfo?: string; valueFormat?: "amount" | "percentage" | "none"; colors?: string; popoverTitle?: string; popoverText?: string; popoverButtonText?: string; decimalPlaces?: number; patternMode?: boolean; }`)_
+- `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. _(type: `ChartData[]`)_
+- `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.
+
+**Related components:**
+
+- `<wm-chart-column>` -- the vertical equivalent; prefer it for fewer categories or when vertical orientation reads better.
+- `<wm-chart-legend>` -- external/shared legend for one or more bar or column charts.
+- `<wm-chart>` -- for composition (parts of a whole) in a doughnut chart rather than comparison.
+- `<wm-chart-stack>` -- for composition (parts of a whole) in a stacked bar chart rather than comparison.
+
+**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,122 @@
+### Chart Column
+- **Element:** `<wm-chart-column>`
+
+**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.
+
+**When to use:**
+
+- **Comparing values across a small number of categories** -- when comparing independent quantities and the categories are few or short-labeled, the vertical orientation reads well.
+- **Frequency distribution across numeric ranges such as time (histogram)** -- when showing how often values fall into ordered numeric bins, use a column chart with `sort: "none"` to preserve bin order and a single color so the bins read as one series.
+- **Grouped comparison** -- when each category has sub-series to compare side by side, provide a `groupName` on each data item.
+
+**Do not use for:**
+
+- **Composition / parts of a whole** -- use `wm-chart-stack` for a stacked bar chart or `wm-chart` for a doughnut chart.
+- **Many categories or long labels** -- prefer `wm-chart-bar` (horizontal) so labels have room.
+- **Binary completion tracking** -- use `wm-progress-monitor`.
+
+**Variants / types:**
+
+- **Single-color** -- one color for every column; use for a single series, or for a frequency distribution / histogram where the bins are one series (pair with `sort: "none"` to preserve bin order).
+- **Discrete palette** (`colors: "discrete"`) -- cycles a set of visually distinct colors so each category reads as its own thing. Use when the categories are nominal -- no inherent order or good/bad meaning (e.g., departments, terms, activity types) -- and color is only there to tell them apart.
+- **Semantic palette** (`colors: "semantic"`) -- maps color to meaning rather than to identity. Use when the categories carry positive / negative / status meaning (e.g., Met vs. Not Met, Exceeded vs. Below, or a progress state) and the color should reinforce that meaning. Avoid it for merely nominal categories -- applying good/bad colors to neutral data misleads the reader.
+- **Grouped** -- multiple series per category, provided via a `groupName` on each data item.
+
+**Usage notes:**
+
+- 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.). _(type: `undefined | { label: string; showLabel: boolean; valueAxisLabel: string; categoryAxisLabel: string; printMode: boolean; printModeFormat: "amount" | "percentage"; gridMax: number | "auto"; sort?: "ascending" | "descending" | "none"; showLegend?: "top" | "bottom" | "left" | "right" | "none"; showGrid?: boolean; subinfo?: string; valueFormat?: "amount" | "percentage" | "none"; colors?: string; popoverTitle?: string; popoverText?: string; popoverButtonText?: string; decimalPlaces?: number; patternMode?: boolean; }`)_
+- `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. _(type: `ChartData[]`)_
+- `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.
+
+**Related components:**
+
+- `<wm-chart-bar>` -- the horizontal equivalent; prefer it for many categories or long labels.
+- `<wm-chart-legend>` -- external/shared legend for one or more bar or column charts.
+- `<wm-chart>` -- for composition (parts of a whole) in a doughnut chart rather than comparison or distribution.
+- `<wm-chart-stack>` - for composition (parts of a whole) in a stacked bar chart rather than comparison or distribution.
+
+**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,91 @@
+### Chart Legend
+- **Element:** `<wm-chart-legend>`
+
+**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.
+
+**When to use:**
+
+- **Sharing one legend across multiple charts** -- when several bar/column charts use the same categories and should be read through a single shared legend.
+- **Placing the legend outside the chart** -- when layout requires the legend to sit somewhere the chart's internal legend cannot.
+- **Interactive highlighting** -- clicking or hovering a legend item highlights the corresponding bars across all associated charts.
+
+**Do not use for:**
+
+- **A single chart with a built-in legend** -- use the `config.showLegend` option on `wm-chart-bar` or `wm-chart-column` instead; no separate element is needed.
+- **Doughnut, line, or progress components** -- this legend derives its data from bar and column charts only.
+
+**Variants / types:**
+
+- **Horizontal orientation** (default) -- legend items laid out in a row.
+- **Vertical orientation** -- legend items stacked, for side placement.
+- **Print mode** -- shows each item's print value beside its swatch.
+
+**Usage notes:**
+
+- 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. _(required; default: `""`)_
+- `orientation` -- Layout orientation of legend items. _(type: `"horizontal" | "vertical"`; default: `"horizontal"`)_
+- `print-mode` -- When true, the print value for each item is shown next to its swatch in the
+legend -- suitable for printed output. _(default: `false`)_
+
+**Events:**
+- `wmLegendItemClick` -- Fires when the user clicks a legend item. The associated chart highlights
+the corresponding bar(s) and fades all others. Detail: `{{ idx: number }} idx -- zero-based index of the clicked legend item, or
+`-1` to clear all highlights.`
+- `wmLegendItemHover` -- Fires when the user hovers over a legend item. The associated chart
+highlights the corresponding bar(s) and fades all others. Detail: `{{ idx: number }} idx -- zero-based index of the hovered legend item, or
+`-1` to clear all highlights.`
+
+**Related components:**
+
+- `<wm-chart-bar>` / `<wm-chart-column>` -- the charts this legend serves, paired via `chart-ids`.
+
+**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" />
+```