@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,101 @@
+### Chart Slice
+- **Element:** `<wm-chart-slice>`
+
+**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.
+
+**When to use:**
+
+- **Showing a single composition as a doughnut** -- when the data points are segments of a single total (they sum to 100%), the goal is to communicate that breakdown rather than compare independent values, and the layout needs to be compact/circular, or where a doughnut is the established pattern for that context -- a design decision, not inferable from the data. For most single- or multi-group compositions, prefer `wm-chart-stack` instead -- it reads faster and covers both cases; this component's own bar subtypes (`bar2`-`bar5`) are legacy (see note below).
+- **Qualitative status or proficiency breakdowns, shown as a doughnut** -- when the segments represent qualitative states (e.g., Not Started / In Progress / Met / Not Met, or a proficiency scale from Exceeded to Not Met) and a doughnut fits the context, pick the doughnut subtype whose capacity matches the number of states (see Variants / Types).
+- **A limited set of categories** -- each subtype has a fixed palette sized for a small number of segments; keep the number of slices within the subtype's palette size so colors stay distinct.
+
+**Do not use for:**
+
+- **General comparison of independent values across categories** -- prefer the dedicated `wm-chart-bar` or `wm-chart-column`, the recommended data-driven comparison components. (The simple-bar subtypes `bar6`/`bar7` can compare discrete categories, but the stacked `bar2`-`bar5` subtypes are composition patterns, not general-purpose bar charts.)
+- **Frequency distribution across numeric ranges (histograms)** -- use `wm-chart-column`.
+- **Data changing over time (trends)** -- use `wm-line-chart`.
+- **Binary completion tracking (exactly two states, done vs. not done)** -- use `wm-progress-monitor`.
+- **Any composition that would read better as a bar, single-group or multi-group** -- prefer `wm-chart-stack` as the default; it's the only composition component with a grouped/multi-group layout, and reads faster than a doughnut even for a single group. Use this component's doughnut only for the compact/circular or established-pattern exception (see When to Use).
+
+**Variants / types:**
+
+The subtype is set with the `chart-type` prop (default `doughnut1`). Colors are assigned automatically by the subtype from a fixed palette -- the application does not choose per-slice colors on this component.
+
+**Doughnut subtypes**
+
+- **`doughnut1`** (default) -- simple part-to-whole with up to three segments.
+- **`doughnut2`** -- qualitative multi-state composition that can include a neutral / "not started" state (e.g., Met / Not Met / Not started); palette supports up to five segments.
+- **`doughnut3`** -- nominal categories with no inherent qualitative meaning; palette supports up to seven segments.
+
+**Stacked bar subtypes** (composition -- segments of a single total)
+
+- **`bar2`** -- qualitative outcome breakdown across several states (e.g., Not Started / In Progress / Met / Not Met); palette supports up to six segments.
+- **`bar3`** -- a performance or proficiency scale (e.g., Exceeded / Met / Approached / Not Met); also used for a two-state Met / Not Met split. Supports two to four segments.
+- **`bar4`** -- three-state completion (Not started / In Progress / Completed).
+- **`bar5`** -- many nominal categories (up to seven); set `not-started-color` to render a leading gray "not started" segment.
+
+**Simple bar subtypes** (non-stacked -- compare values across categories)
+
+- **`bar6`** -- a single-color simple bar chart for comparing discrete categorical values (not a part-to-whole); supports `show-grid` and `label-width`.
+- **`bar7`** -- a multi-color simple bar chart for comparing discrete categorical values, with an optional y-axis bar legend (`show-bar-legend`).
+
+> For new work, prefer the dedicated `wm-chart-bar` and `wm-chart-column` components for comparing categorical values. They are the recommended, data-driven comparison charts and effectively supersede the `bar6`/`bar7` simple-bar subtypes, which predate them. For new work needing a bar-shaped composition -- single-group or multi-group -- prefer the dedicated `wm-chart-stack`. It is the recommended, data-driven composition chart and supersedes the `bar2`/`bar3`/`bar4`/`bar5` stacked bar subtypes, which predate it. This component's doughnut subtypes remain the recommended path only when a doughnut is specifically wanted.
+
+> The precise design intent for each subtype is owned by the design system team; the scenarios above reflect each subtype's canonical usage as exercised by the component's own visual tests. Confirm with the design team before repurposing a subtype for a new scenario.
+
+**Usage notes:**
+
+- 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. _(required)_
+- `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.
+
+**Related components:**
+
+- `<wm-chart-slice>` -- required child; one per segment of the whole.
+- `<wm-chart-bar>` / `<wm-chart-column>` -- for comparing independent values across categories rather than showing composition.
+- `<wm-chart-stack>` -- the default composition component for both single-group and multi-group part-to-whole breakdowns shown as a bar; use this component (doughnut) only for the compact/circular or established-pattern exception.
+- `<wm-progress-monitor>` -- for binary (two-state) completion tracking.
+
+**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" />
+```

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

@@ -0,0 +1,147 @@
+### Chart Stack
+- **Element:** `<wm-chart-stack>`
+
+**Purpose:** Renders a horizontal stacked bar chart: each stack's segments are sized as a percentage of
+that stack's total. Supports any number of stacks and segments, each occupying their own row.
+Data and configuration are set via JavaScript properties (`chart.config` and `chart.data`) -- not
+HTML attributes.
+
+**When to use:**
+
+- **Any part-to-whole composition -- single-group or multi-group (default choice)**, except binary completion tracking (see Do Not Use For) -- a single stack renders without a stack label; multiple stacks (via distinct `stackName` values) each render as their own labeled row. Prefer this over `wm-chart` doughnut in both cases -- a bar reads faster than a doughnut for most viewers.
+- **Comparing composition across multiple groups** -- when several groups each have their own part-to-whole breakdown and the goal is to compare those breakdowns side by side (each row normalized to 100%). This is the only composition component with a grouped layout; `wm-chart` doughnut has no multi-group variant.
+- **Keeping a category's color consistent across stacks** -- segment color follows the order each `legend` first appears in the data, so a legend keeps the same color across every stack.
+
+**Do not use for:**
+
+- **Comparing absolute values across categories** -- use `wm-chart-bar` or `wm-chart-column`; stack segments show percentages of each stack's total, not absolute magnitudes.
+- **A single composition that must fit a compact, circular footprint, or where a doughnut is the established pattern for that context** -- a design decision, not inferable from the data -- use `wm-chart` doughnut instead. This is the only case where a single-group composition should skip this component.
+- **Data changing over time (trends)** -- use `wm-line-chart`.
+- **Binary completion tracking** -- use `wm-progress-monitor`.
+
+**Variants / types:**
+
+- **Single-stack** -- one distinct `stackName`; renders without a stack label.
+- **Grouped (multi-stack)** -- multiple distinct `stackName` values; each renders as its own labeled row.
+- **Discrete palette** (`colors: "discrete"`, default) -- gives each segment (legend) its own visually distinct color. Use when the segments are nominal parts with no inherent good/bad meaning and color is only there to tell them apart. Limited to 7 segments based on the discrete color palette.
+- **Semantic palette** (`colors: "semantic"`) -- maps color to meaning rather than to identity. Use when the segments carry positive / negative / status meaning (e.g., a proficiency scale, or Met vs. Not Met) and the color should reinforce that meaning. Avoid it for merely nominal segments. Limited to 8 segments based on the semantic color palette.
+- **Print mode** -- shortens the bars, enlarges percentage labels, hides the interactive legend, and renders a data table per stack.
+
+**Usage notes:**
+
+- Segments are grouped into stacks by each segment's `stackName`; one distinct `stackName` renders
+  the single-stack layout (no stack label), multiple render the grouped variant.
+- Color follows the order each `legend` first appears in `data`, so a legend keeps a consistent
+  color across stacks. A per-segment `color` overrides the palette; legends beyond the palette
+  fall back to the default color.
+- Set `id` on the element to pair it with an external `wm-chart-legend` via `chart-ids`.
+- Print mode (`printMode` prop, `config.printMode`, or an active browser print) shortens the bars,
+  enlarges the percentage labels, hides the interactive legend, and renders a data table per stack.
+
+**Props:**
+- `config` -- Chart configuration object. Set via JavaScript property -- not an HTML attribute.
+Fields:
+- `label` (string, required): the chart's title, also used as its `aria-label`.
+- `subinfo` (string): secondary text shown beneath the label.
+- `colors` (`"discrete"` | `"semantic"`, default `"discrete"`): palette for the segments.
+`"semantic"` maps to the meaning-based palette (gray/purples/teals/coral).
+- `showLabel` (boolean, default `true`): whether the chart label and subinfo are rendered.
+- `showLegend` (`"left"` | `"right"` | `"top"` | `"bottom"` | `"none"`, default `"none"`):
+placement of the interactive legend (hidden in print, where the data table replaces it).
+- `showGrid` (boolean, default `false`): renders a `0%`-`100%` axis and a vertical baseline.
+- `valueFormat` (`"percentage"` | `"none"`, default `"percentage"`): whether each segment shows
+its percentage label above the bar.
+- `printMode` / `patternMode` (boolean, default `false`): same as the props of the same name;
+the props take precedence when both are set.
+- `popoverTitle` / `popoverText` / `popoverButtonText` (string): default popover content applied
+to every segment, each overridable per-segment in `data`. When unset, the popover title
+defaults to `amount/total`, the text to the segment's legend, and no button is shown. _(type: `undefined | { label: string; subinfo?: string; popoverTitle?: string; popoverText?: string; popoverButtonText?: string; colors?: "discrete" | "semantic"; showLabel?: boolean; showLegend?: "top" | "bottom" | "left" | "right" | "none"; showGrid?: boolean; valueFormat?: "percentage" | "none"; printMode?: boolean; patternMode?: boolean; }`)_
+- `data` -- Array of segments to render. Set via JavaScript property -- not an HTML attribute.
+Each segment's fields:
+- `stackName` (string, required): groups segments into the same stack (row); the set of distinct
+stackNames determines whether the single or grouped layout is used.
+- `legend` (string, required): the segment's category, shown in the legend and used to assign a
+consistent color across stacks.
+- `amount` (number, required): the raw value; the segment's width is `amount / stackTotal`.
+- `color` (string): a `wmcolor` token overriding the palette color for this segment.
+- `popoverTitle` / `popoverText` / `popoverButtonText` (string): popover content for this segment,
+overriding the corresponding `config` defaults. _(type: `StackSegmentData[]`)_
+- `pattern-mode` -- When true, applies a hatching pattern fill to segments and enlarges the legend
+tiles, in addition to color -- improving distinguishability for users with color vision
+deficiencies. Takes precedence over `config.patternMode`.
+- `print-mode` -- When true, renders the print layout: shorter bars, larger bold percentage labels,
+and a data table beneath each stack (legend, percentage, amount/total, popover text) in place of
+the interactive legend. Also activated automatically while the browser is printing. 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`.
+- The chart renders with `role="application"` and `aria-roledescription="Interactive chart"`.
+- When a percentage label is hidden for lack of space, a "click a segment to see values" hint is
+  shown; it is removed when printing, where clicking isn't available and the data table lists
+  every value.
+- **Keyboard:**
+  - **Tab**: Enters the chart wrapper.
+  - **Arrow Down / Right**: Focuses the first segment.
+  - **Arrow Left / Right**: Moves to the previous / next segment within the stack, wrapping at the ends.
+  - **Arrow Up / Down**: Moves to the previous / next stack (focusing its first segment), wrapping at the ends.
+  - **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>` -- for a single composition shown as a doughnut.
+- `<wm-chart-bar>` / `<wm-chart-column>` -- for comparing absolute values rather than normalized composition.
+- `<wm-chart-legend>` -- external/shared legend paired via `chart-ids`.
+
+**Code example:**
+
+_Single stack_
+
+```html
+<wm-chart-stack id="submission-status"></wm-chart-stack>
+<script>
+const chart = document.querySelector('#submission-status');
+chart.config = { label: 'Submission status', colors: 'semantic', showLegend: 'top' };
+chart.data = [
+{ stackName: 'Status', legend: 'Not Submitted', amount: 2 },
+{ stackName: 'Status', legend: 'Awaiting Review', amount: 4 },
+{ stackName: 'Status', legend: 'Met', amount: 10 },
+{ stackName: 'Status', legend: 'Not Met', amount: 4 },
+];
+</script>
+```
+
+_Single stack_
+
+```react
+<WmChartStack ref={chartRef} />
+// In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+```
+
+_Grouped (multiple stacks)_
+
+```html
+<wm-chart-stack id="status-by-requirement"></wm-chart-stack>
+<script>
+const chart = document.querySelector('#status-by-requirement');
+chart.config = { label: 'Status by requirement', colors: 'semantic', showLegend: 'top' };
+chart.data = [
+{ stackName: 'Requirement 01', legend: 'Met', amount: 12 },
+{ stackName: 'Requirement 01', legend: 'Not Met', amount: 12 },
+{ stackName: 'Requirement 02', legend: 'Met', amount: 33 },
+{ stackName: 'Requirement 02', legend: 'Not Met', amount: 67 },
+];
+</script>
+```
+
+_Grouped (multiple stacks)_
+
+```react
+<WmChartStack ref={chartRef} />
+// In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+```

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

@@ -0,0 +1,139 @@
+### Chart
+- **Element:** `<wm-chart>`
+
+**Purpose:** Composition chart component rendering doughnut or stacked bar charts. Composed of a parent
+wm-chart element and wm-chart-slice children. Has 3 doughnut subtypes and 5 bar subtypes,
+each designed for a specific composition use case.
+
+**Important:** The bar subtypes (`bar2`-`bar7`) are COMPOSITION patterns -- they show parts
+of a whole for specific qualitative use cases. They are NOT general-purpose bar charts. For
+general comparison or distribution bar charts, use wm-chart-bar or wm-chart-column instead.
+
+**When to use:**
+
+- **Showing a single composition as a doughnut** -- when the data points are segments of a single total (they sum to 100%), the goal is to communicate that breakdown rather than compare independent values, and the layout needs to be compact/circular, or where a doughnut is the established pattern for that context -- a design decision, not inferable from the data. For most single- or multi-group compositions, prefer `wm-chart-stack` instead -- it reads faster and covers both cases; this component's own bar subtypes (`bar2`-`bar5`) are legacy (see note below).
+- **Qualitative status or proficiency breakdowns, shown as a doughnut** -- when the segments represent qualitative states (e.g., Not Started / In Progress / Met / Not Met, or a proficiency scale from Exceeded to Not Met) and a doughnut fits the context, pick the doughnut subtype whose capacity matches the number of states (see Variants / Types).
+- **A limited set of categories** -- each subtype has a fixed palette sized for a small number of segments; keep the number of slices within the subtype's palette size so colors stay distinct.
+
+**Do not use for:**
+
+- **General comparison of independent values across categories** -- prefer the dedicated `wm-chart-bar` or `wm-chart-column`, the recommended data-driven comparison components. (The simple-bar subtypes `bar6`/`bar7` can compare discrete categories, but the stacked `bar2`-`bar5` subtypes are composition patterns, not general-purpose bar charts.)
+- **Frequency distribution across numeric ranges (histograms)** -- use `wm-chart-column`.
+- **Data changing over time (trends)** -- use `wm-line-chart`.
+- **Binary completion tracking (exactly two states, done vs. not done)** -- use `wm-progress-monitor`.
+- **Any composition that would read better as a bar, single-group or multi-group** -- prefer `wm-chart-stack` as the default; it's the only composition component with a grouped/multi-group layout, and reads faster than a doughnut even for a single group. Use this component's doughnut only for the compact/circular or established-pattern exception (see When to Use).
+
+**Variants / types:**
+
+The subtype is set with the `chart-type` prop (default `doughnut1`). Colors are assigned automatically by the subtype from a fixed palette -- the application does not choose per-slice colors on this component.
+
+**Doughnut subtypes**
+
+- **`doughnut1`** (default) -- simple part-to-whole with up to three segments.
+- **`doughnut2`** -- qualitative multi-state composition that can include a neutral / "not started" state (e.g., Met / Not Met / Not started); palette supports up to five segments.
+- **`doughnut3`** -- nominal categories with no inherent qualitative meaning; palette supports up to seven segments.
+
+**Stacked bar subtypes** (composition -- segments of a single total)
+
+- **`bar2`** -- qualitative outcome breakdown across several states (e.g., Not Started / In Progress / Met / Not Met); palette supports up to six segments.
+- **`bar3`** -- a performance or proficiency scale (e.g., Exceeded / Met / Approached / Not Met); also used for a two-state Met / Not Met split. Supports two to four segments.
+- **`bar4`** -- three-state completion (Not started / In Progress / Completed).
+- **`bar5`** -- many nominal categories (up to seven); set `not-started-color` to render a leading gray "not started" segment.
+
+**Simple bar subtypes** (non-stacked -- compare values across categories)
+
+- **`bar6`** -- a single-color simple bar chart for comparing discrete categorical values (not a part-to-whole); supports `show-grid` and `label-width`.
+- **`bar7`** -- a multi-color simple bar chart for comparing discrete categorical values, with an optional y-axis bar legend (`show-bar-legend`).
+
+> For new work, prefer the dedicated `wm-chart-bar` and `wm-chart-column` components for comparing categorical values. They are the recommended, data-driven comparison charts and effectively supersede the `bar6`/`bar7` simple-bar subtypes, which predate them. For new work needing a bar-shaped composition -- single-group or multi-group -- prefer the dedicated `wm-chart-stack`. It is the recommended, data-driven composition chart and supersedes the `bar2`/`bar3`/`bar4`/`bar5` stacked bar subtypes, which predate it. This component's doughnut subtypes remain the recommended path only when a doughnut is specifically wanted.
+
+> The precise design intent for each subtype is owned by the design system team; the scenarios above reflect each subtype's canonical usage as exercised by the component's own visual tests. Confirm with the design team before repurposing a subtype for a new scenario.
+
+**Usage notes:**
+
+- Slices without an `amount` are not rendered but still occupy a color slot, allowing
+  consistent color assignment when some data points are missing.
+- The `show-legend` prop controls legend visibility but the legend is always read by screen
+  readers regardless of visibility.
+- For data-driven bar charts (comparison, distribution), prefer wm-chart-bar or
+  wm-chart-column.
+
+**Props:**
+- `chart-type` -- Chart subtype. Doughnut subtypes (`doughnut1`-`doughnut3`) and bar composition
+subtypes (`bar2`-`bar7`) -- each tailored to a specific composition use case. _(type: `"bar" | "bar2" | "bar3" | "bar4" | "bar5" | "bar6" | "bar7" | "doughnut" | "doughnut1" | "doughnut2" | "doughnut3"`; default: `"doughnut1"`)_
+- `label` -- Accessible label for the chart. Required -- the component throws an error if
+omitted. Used as the `aria-label` on the chart container and as the visual chart label. _(required)_
+- `label-position` -- Position of the chart label relative to the chart. When `"none"`, no label is
+rendered -- an external label matching `label` must be visually grouped with the chart. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `label-width` -- Controls the bar label width. Only applies to `bar6` and `bar7` subtypes. _(default: `"150px"`)_
+- `not-started-color` -- When true, applies a gray color to the first slice to represent a
+"not started" state. Only applies to `bar5`. _(default: `false`)_
+- `print-mode` -- When true, slice values are included in the legend and keyboard interaction
+instructions are removed from the DOM -- suitable for printed output. _(default: `false`)_
+- `print-mode-format` -- Format for legend values when `print-mode` is enabled. _(type: `"amount" | "percentage"`; default: `"amount"`)_
+- `show-bar-legend` -- Show or hide the y-axis bar legend. Only applies to `bar7`. _(default: `false`)_
+- `show-grid` -- Show or hide the value grid lines. Only applies to `bar6`. _(default: `true`)_
+- `show-legend` -- Show or hide the legend below the chart. The legend is still read by screen
+readers regardless of this setting. _(default: `true`)_
+- `subinfo` -- Optional secondary text displayed beneath the chart label. Not shown when
+`label-position` is `"none"`.
+- `value-format` -- Controls how individual segment values are displayed on the chart. _(type: `"amount" | "none" | "percentage"`; default: `"none"`)_
+
+**Accessibility:**
+
+- `label` is required for accessibility -- the chart throws if omitted.
+- The chart renders with `role="application"` and an `aria-roledescription` of
+  "Interactive chart". Each segment is individually focusable with an `aria-label`.
+- `print-mode` removes keyboard interaction instructions for printed output.
+- **Keyboard:**
+  - **Tab**: Enters the chart. Subsequent Tab exits the chart.
+  - **Arrow keys**: Navigate between slices/segments.
+  - **Enter / Space**: Opens the data popover for the focused segment.
+  - **Escape**: Closes the popover and returns to the chart container.
+
+**Related components:**
+
+- `<wm-chart-slice>` -- required child; one per segment of the whole.
+- `<wm-chart-bar>` / `<wm-chart-column>` -- for comparing independent values across categories rather than showing composition.
+- `<wm-chart-stack>` -- the default composition component for both single-group and multi-group part-to-whole breakdowns shown as a bar; use this component (doughnut) only for the compact/circular or established-pattern exception.
+- `<wm-progress-monitor>` -- for binary (two-state) completion tracking.
+
+**Code example:**
+
+_Doughnut chart_
+
+```html
+<wm-chart label="Enrollment by status">
+<wm-chart-slice legend="Enrolled" amount="310"></wm-chart-slice>
+<wm-chart-slice legend="Not enrolled" amount="90"></wm-chart-slice>
+</wm-chart>
+```
+
+_Doughnut chart_
+
+```react
+<WmChart label="Enrollment by status">
+<WmChartSlice legend="Enrolled" amount="310" />
+<WmChartSlice legend="Not enrolled" amount="90" />
+</WmChart>
+```
+
+_Bar composition chart_
+
+```html
+<wm-chart label="Completion by cohort" chart-type="bar5">
+<wm-chart-slice legend="Completed" amount="200"></wm-chart-slice>
+<wm-chart-slice legend="In progress" amount="75"></wm-chart-slice>
+<wm-chart-slice legend="Not started" amount="25"></wm-chart-slice>
+</wm-chart>
+```
+
+_Bar composition chart_
+
+```react
+<WmChart label="Completion by cohort" chartType="bar5">
+<WmChartSlice legend="Completed" amount="200" />
+<WmChartSlice legend="In progress" amount="75" />
+<WmChartSlice legend="Not started" amount="25" />
+</WmChart>
+```

package/dist/docs/skill/wm-date-range.md

@@ -0,0 +1,176 @@
+### Date Range
+- **Element:** `<wm-date-range>`
+
+**Purpose:** Two linked date inputs (start and end) with a shared calendar popup for selecting a date
+range. Users can type or click to set each date. Provides separate error states for start
+and end, and emits distinct blur events for each input. Use instead of two native
+`<input type="date">` elements when a range is required.
+
+**When to use:**
+
+- **Collecting a bounded time period with a start and end** -- when a user needs to define a window of time (a reporting period, an enrollment window, a project timeline), use Date Range to capture both boundary dates as a single, semantically linked input rather than two independent Datepickers.
+- **Filtering data by a date range** -- when a user is narrowing results by a time window (e.g., "show records between these two dates"), Date Range provides the right interaction model with a shared calendar that highlights the selected span visually.
+- **Enforcing range integrity at the form level** -- when the application needs to validate that the start date precedes the end date, Date Range exposes the right blur events and standardized error messages to handle all range validation scenarios consistently.
+- **Allowing range selection via a shared calendar popup** -- when users benefit from seeing both dates in context on a calendar, Date Range's shared popup highlights the full selected range, which two independent Datepickers cannot do.
+
+**Do not use for:**
+
+- **Two separate dates that happen to be related** -- if the two dates are logically a range, use Date Range; two independent Datepickers have no shared calendar, no range highlighting, and no built-in mechanism to enforce that start precedes end.
+- **Selecting a single point in time** -- if the user is selecting one date rather than a span, use wm-datepicker; Date Range always manages two values and two validation states, which is unnecessary overhead for a single date.
+
+**Variants / types:**
+
+_None documented_
+
+**Usage notes:**
+
+- Set `value-start` and `value-end` in the format specified by `date-format` (default
+  `mm/dd/yyyy`). For programmatic pre-population, prefer ISO format via `preselected` and
+  convert with the `reformatDate` method.
+- `wmRangeSelection` emits a detail object with `startDate` and `endDate`, each in ISO, US,
+  and INT formats.
+- The same-date re-selection rule: clicking the same date as `date1` a second time resets the
+  range selection so the user can pick a new `date1`.
+
+**Props:**
+- `date-format` -- The date format shown in the input placeholders and announced to screen readers. _(default: `"mm/dd/yyyy"`)_
+- `disabled` -- Disables the entire date range component, preventing all interaction. _(default: `false`)_
+- `error-message` -- Puts the component in an error state and displays this message below both
+inputs. Use with `invalid-start` and/or `invalid-end` to highlight specific fields.
+- `invalid-end` -- Puts the end date input in an error state (red border). Use with
+`error-message`. _(default: `false`)_
+- `invalid-start` -- Puts the start date input in an error state (red border). Use with
+`error-message`. _(default: `false`)_
+- `label-end` -- Visible label for the end date input. Required for accessibility. _(required; default: `""`)_
+- `label-start` -- Visible label for the start date input. Required for accessibility. _(required; default: `""`)_
+- `preselected` -- The ISO date (YYYY-MM-DD) the calendar popup opens to when first opened and
+no `value-start` is set. Falls back to today's date if omitted.
+- `required-field` -- Displays a required-field asterisk (*) next to each label. _(default: `false`)_
+- `value-end` -- The value of the end date input, in the format specified by `date-format`.
+Updated as the user types or picks from the calendar. _(default: `""`)_
+- `value-start` -- The value of the start date input, in the format specified by `date-format`.
+Updated as the user types or picks from the calendar. _(default: `""`)_
+
+**Events:**
+- `wmEndInputBlur` -- Fires when the end date input loses focus.
+- `wmRangeSelection` -- Fires when the user completes a range selection from the calendar popup. Detail: `{{ startDate: { iso: string, us: string, int: string }, endDate: { iso: string, us: string, int: string } }}
+startDate and endDate -- each formatted in ISO (YYYY-MM-DD), US (mm/dd/yyyy), and INT
+(dd/mm/yyyy). The dates are always returned in chronological order regardless of the order
+they were clicked.`
+- `wmStartInputBlur` -- Fires when the start date input loses focus.
+
+**Methods:**
+- `isValidISO(input?: string) => Promise<boolean>` -- Validates whether a string is a well-formed, calendar-correct ISO date
+(YYYY-MM-DD). Accounts for invalid day-of-month values and leap years.
+  - `input` -- - The string to validate.
+  - **Returns:** `true` if the string is a valid ISO date, `false` otherwise.
+- `reformatDate(inputFormat: string, outputFormat: string, date?: string) => Promise<string>` -- Converts a date string between `"US"` (mm/dd/yyyy), `"INT"` (dd/mm/yyyy),
+and `"ISO"` (YYYY-MM-DD). Direct US ↔ INT conversion is not supported -- route through
+ISO as an intermediate step.
+  - `inputFormat` -- - Format of the input date string (`"US"`, `"INT"`, or `"ISO"`).
+  - `outputFormat` -- - Desired output format (`"US"`, `"INT"`, or `"ISO"`).
+  - `date` -- - The date string to reformat.
+  - **Returns:** The reformatted date string, an empty string if `date` is omitted, or the original
+string unchanged if it cannot be parsed.
+
+**Accessibility:**
+
+- `label-start` and `label-end` are required for accessibility -- always provide both even if
+  visually implied by context.
+- The calendar toggle announces "Select range" to screen readers and reflects `aria-expanded`.
+- Validation errors are announced via an `aria-live` region when `error-message` changes.
+- The calendar popup hides its toggle when there is no room to display it; users can still
+  type dates directly into the inputs.
+- **Keyboard:**
+  - **Input fields**: Tab moves focus between start input, end input, and the calendar toggle.
+  - **Calendar toggle**: Space / Enter opens the calendar; Escape closes it and returns focus.
+  - **Day grid**: Arrow keys navigate dates; Enter selects. After selecting the first date,
+  the calendar resets for a second selection. Selecting a date earlier than the first date
+  automatically swaps start and end.
+  - **Month/year selectors**: Arrow keys cycle values; Tab/Shift+Tab move focus through controls.
+
+**Related components:**
+
+- `<wm-datepicker>` -- if only a single date is needed rather than a start-and-end pair, use Datepicker; Date Range always manages two values and is only appropriate when both are required together.
+- `<wm-timepicker>` -- if the range also needs to capture times of day, Date Range has no time input; pair it with Timepicker fields for the start and end times separately.
+- `<wm-select>` -- if the user is choosing from a predefined list of named time periods (e.g., "Q1 2025", "Fall Semester") rather than specifying arbitrary dates, Select is more appropriate; Date Range is for open-ended date entry.
+
+**Code example:**
+
+_Basic date range_
+
+```html
+<wm-date-range label-start="Start date" label-end="End date"></wm-date-range>
+```
+
+_Basic date range_
+
+```react
+// The component does not update its own values after a calendar selection --
+// the app must call reformatDate and set valueStart/valueEnd imperatively via a ref.
+const ref = useRef(null);
+
+function getFormatName(format) {
+const map = { 'mm/dd/yyyy': 'US', 'dd/mm/yyyy': 'INT', 'yyyy/mm/dd': 'ISO' };
+return format ? map[format] : 'US';
+}
+
+// event.detail is { startDate: { iso, us, int }, endDate: { iso, us, int } }
+const handleRangeSelection = async (event) => {
+const dr = ref.current;
+const fmt = getFormatName(dr.getAttribute('date-format'));
+dr.valueStart = await dr.reformatDate('ISO', fmt, event.detail.startDate.iso);
+dr.valueEnd = await dr.reformatDate('ISO', fmt, event.detail.endDate.iso);
+dr.errorMessage = '';
+};
+
+const handleInputBlurred = async (field) => {
+const dr = ref.current;
+const fmt = getFormatName(dr.getAttribute('date-format'));
+const value = field === 'start' ? dr.valueStart : dr.valueEnd;
+if (value) {
+const iso = await dr.reformatDate(fmt, 'ISO', value);
+if (await dr.isValidISO(iso)) {
+const display = await dr.reformatDate('ISO', fmt, iso);
+if (field === 'start') dr.valueStart = display;
+else dr.valueEnd = display;
+dr.errorMessage = '';
+dr.invalidStart = false;
+dr.invalidEnd = false;
+} else {
+dr.errorMessage = `Please enter a valid date in the format ${dr.getAttribute('date-format') ?? 'mm/dd/yyyy'}`;
+if (field === 'start') dr.invalidStart = true;
+else dr.invalidEnd = true;
+}
+}
+};
+
+<WmDateRange
+ref={ref}
+labelStart="Start date"
+labelEnd="End date"
+onWmRangeSelection={handleRangeSelection}
+onWmStartInputBlur={() => handleInputBlurred('start')}
+onWmEndInputBlur={() => handleInputBlurred('end')}
+/>
+```
+
+_Required fields with validation_
+
+```html
+<wm-date-range label-start="From" label-end="To" required-field></wm-date-range>
+```
+
+_Required fields with validation_
+
+```react
+<WmDateRange
+ref={ref}
+labelStart="From"
+labelEnd="To"
+requiredField={true}
+onWmRangeSelection={handleRangeSelection}
+onWmStartInputBlur={() => handleInputBlurred('start')}
+onWmEndInputBlur={() => handleInputBlurred('end')}
+/>
+```