@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/types/components/charts/wm-chart-stack/wm-chart-stack.d.ts

@@ -0,0 +1,194 @@
+import { EventEmitter } from "../../../stencil-public-runtime";
+import { StackChartConfig, StackSegmentData, ProcessedChartData, ProcessedStackData } from "../../../global/interfaces";
+/**
+ * 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.
+ *
+ * @displayName Stack Chart
+ * @category Data Visualization
+ *
+ * @keyboardInteraction
+ * - **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.
+ *
+ * @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.
+ *
+ * @usageNotes
+ * - 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.
+ *
+ * @example {html} Single stack
+ * <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>
+ *
+ * @example {react} Single stack
+ * <WmChartStack ref={chartRef} />
+ * // In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+ *
+ * @example {html} Grouped (multiple stacks)
+ * <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>
+ *
+ * @example {react} Grouped (multiple stacks)
+ * <WmChartStack ref={chartRef} />
+ * // In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+ */
+export declare class ChartStack {
+    el: HTMLWmChartStackElement;
+    private popoverEl;
+    private componentWrapperEl;
+    private stacksEl;
+    private legendData;
+    private stackTotals;
+    private measurePending;
+    /**
+     * @description 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.
+     */
+    config?: StackChartConfig;
+    /**
+     * @description 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.
+     */
+    data?: StackSegmentData[];
+    /**
+     * @description 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`.
+     * @default false
+     */
+    printMode?: boolean;
+    /**
+     * @description 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`.
+     * @default false
+     */
+    patternMode?: boolean;
+    /**
+     * @description Optional secondary text displayed beneath the chart label. Takes precedence over
+     * `config.subinfo`.
+     */
+    subinfo?: string;
+    processedStacks: ProcessedStackData;
+    isKeying: boolean;
+    hasHiddenValues: boolean;
+    userIsPrinting: boolean;
+    /**
+     * @internal
+     * @description Internal signal used to synchronize segment highlight state with an external
+     * wm-chart-legend — not for application use.
+     */
+    wmChartStackHighlighted: EventEmitter<{
+        idx: number;
+    }>;
+    get colorPalette(): string[];
+    get showLegend(): "left" | "right" | "top" | "bottom" | "none";
+    get showGrid(): boolean;
+    get valueFormat(): "percentage" | "none";
+    get isPrintMode(): boolean;
+    get isPatternMode(): boolean;
+    get subinfoText(): string;
+    get isSingleStack(): boolean;
+    get flattenedData(): ProcessedChartData[];
+    get segmentWrappers(): NodeListOf<HTMLElement>;
+    getPatternClass(item: ProcessedChartData): string;
+    componentDidLoad(): void;
+    componentDidRender(): void;
+    handleConfigDataChange(): void;
+    buildProcessedStacks(): ProcessedStackData;
+    buildLegendData(): ProcessedChartData[];
+    countStackTotals(processedStacks: ProcessedStackData): Map<string, number>;
+    propagateExternalLegendData(): void;
+    handleChartKeyDown(ev: KeyboardEvent): void;
+    handleSegmentKeyDown(ev: KeyboardEvent, stackIdx: number, segmentIdx: number): void;
+    handleSegmentClick(ev: MouseEvent, segmentData: ProcessedChartData): void;
+    handleLegendItemClick(ev: CustomEvent<{
+        idx: number;
+    }>): void;
+    handleDocumentClick(_ev: MouseEvent): void;
+    handleUserIsKeying(): void;
+    handleUserIsNotKeying(): void;
+    handleBeforePrint(): void;
+    handleAfterPrint(): void;
+    handleComponentBlur(ev: FocusEvent): void;
+    segmentCount(stackIdx: number): number;
+    segmentAt(stackIdx: number, segmentIdx: number): ProcessedChartData | undefined;
+    focusSegment(stackIdx: number, segmentIdx: number): void;
+    openPopover(item: ProcessedChartData, coords: {
+        x: number;
+        y: number;
+    }): void;
+    handlePopoverToggled(_ev: CustomEvent): void;
+    highlightSegment(item: ProcessedChartData): void;
+    highlightSegmentsByLegend(legend: string): void;
+    clearHighlights(): void;
+    clearFocus(): void;
+    updateHiddenValues(): void;
+    renderValue(item: ProcessedChartData): any;
+    renderSegment(item: ProcessedChartData, stackIdx: number, segmentIdx: number): any;
+    renderStacks(): any[][];
+    renderPrintTable(stackName: string, segments: ProcessedChartData[]): any;
+    renderLegend(orientation: "horizontal" | "vertical"): any;
+    render(): any;
+}

package/dist/types/components/charts/wm-line-chart/wm-line-chart.d.ts

@@ -1,4 +1,63 @@
-import { DataPointDetails, Line, LineChartData } from "../../../global/interfaces";
+import { DataPointDetails, Line, LineChartData, SpotlightData } from "../../../global/interfaces";
+/**
+ * Visualizes how data changes over time. Ideal for trend analysis — tracking one or more
+ * metrics across chronological intervals such as semesters, academic years, or months.
+ * Supports up to 7 lines, each differentiated by both color and symbol. Data is set via the
+ * `line-data` prop (JSON string or object). Minimum width of 562 px; horizontally scrollable
+ * at smaller viewports.
+ *
+ * @category Data Visualization
+ *
+ * @keyboardInteraction
+ * - **Tab** (into chart): If `visibility-toggles` is enabled, focuses the first toggle button;
+ *   otherwise focuses the first data point.
+ * - **Tab** (on toggle button): Moves to the first data point of the first visible line.
+ * - **Shift+Tab** (on first data point, with toggles): Returns focus to the toggle buttons.
+ * - **Arrow Up / Down** (on data point): Moves focus vertically to the same x-interval on
+ *   the previous/next line.
+ * - **Arrow Left / Right** (on data point): Moves focus to the previous/next data point on
+ *   the same line.
+ * - **Arrow Left / Right** (on toggle button): Cycles between toggle buttons.
+ *
+ * @accessibility
+ * - `label`, `x-axis-label`, and `y-axis-label` are required for accessibility.
+ * - Each data point renders as `role="img"` with a detailed `aria-label` including the line
+ *   name, x-value, y-value, units, and (if `show-deltas`) the percentage change from the
+ *   previous point.
+ * - An `aria-live` region announces the line name and data point count when keyboard focus
+ *   moves to a new line.
+ * - The `description` prop is appended to the chart instructions read to screen readers —
+ *   use it to summarize the key takeaway.
+ *
+ * @usageNotes
+ * - `line-data` expects a JSON object where keys are line labels and values are objects mapping
+ *   x-axis values (strings) to y-axis values (numbers or `null` for missing data points).
+ *   In HTML, set it as a JSON string attribute; in JavaScript/React, set it as an object.
+ * - Up to 7 lines are supported — each is automatically assigned a color and symbol from
+ *   the built-in palette.
+ * - `spotlight-data` adds a single reference line spanning the whole chart. Provide an object
+ *   with a `label` key and one x-value key mapping to the y-value.
+ *
+ * @example {html} Basic line chart
+ * <wm-line-chart label="Enrollment trend" x-axis-label="Term" y-axis-label="Students"
+ *   line-data='{"Biology": {"Fall 2022": 310, "Fall 2023": 340}}'></wm-line-chart>
+ *
+ * @example {react} Basic line chart
+ * <WmLineChart label="Enrollment trend" xAxisLabel="Term" yAxisLabel="Students"
+ *   lineData={{ Biology: { "Fall 2022": 310, "Fall 2023": 340 } }} />
+ *
+ * @example {html} Multi-line with delta comparisons
+ * <wm-line-chart label="Retention rates" x-axis-label="Year" y-axis-label="Rate"
+ *   units="null,percent" show-deltas
+ *   line-data='{"Biology": {"2022": 85, "2023": 88}, "English": {"2022": 79, "2023": 82}}'>
+ * </wm-line-chart>
+ *
+ * @example {react} Multi-line with delta comparisons
+ * <WmLineChart label="Retention rates" xAxisLabel="Year" yAxisLabel="Rate"
+ *   units="null,percent" showDeltas={true}
+ *   lineData={{ Biology: { "2022": 85, "2023": 88 }, English: { "2022": 79, "2023": 82 } }} />
+ *
+ */
 export declare class LineChart {
     el: HTMLWmLineChartElement;
     private plotAreaEl;
@@ -6,35 +65,118 @@ export declare class LineChart {
     private popoverEl;
     private yIntervalsEl;
     private liveRegionEl;
+    /**
+     * @description Accessible label for the chart, used as the `aria-label` on the chart
+     * container. Required for accessibility.
+     * @required
+     */
     label: string;
+    /**
+     * @description Accessible description appended to the keyboard instructions read to screen
+     * readers. Recommended — use it to summarize the key takeaway of the chart.
+     * @default ""
+     */
     description: string;
+    /**
+     * @description Label for the x-axis (the time dimension, e.g. `"Term"`, `"Academic Year"`).
+     * Required for accessibility.
+     * @required
+     */
     xAxisLabel: string;
+    /**
+     * @description Label for the y-axis (the measured value, e.g. `"Enrollment"`, `"Score"`).
+     * Required for accessibility.
+     * @required
+     */
     yAxisLabel: string;
-    lineData: string;
+    /**
+     * @description When true, renders horizontal and vertical grid lines.
+     * @default true
+     */
+    showGrid: boolean;
+    /**
+     * @description Chart data. Each key is a line label (shown in the legend); each value is an
+     * object mapping x-axis values (strings) to y-axis values (numbers or `null` for missing
+     * data points). Can be set as a JSON string (HTML attribute) or as an object (JavaScript).
+     * Example: `{ "Biology": { "2022–23": 310, "2023–24": 420 } }`.
+     * @required
+     */
+    lineData: string | LineChartData;
+    /**
+     * @description Two comma-separated unit labels for the x and y axes, shown in parentheses
+     * after axis labels and inside popovers. Use `null` for no unit.
+     * Example: `"null,students"` or `"semester,percent"`.
+     * @default "null,null"
+     */
     units: string;
+    /**
+     * @description CSS width of the y-axis interval label column.
+     * @default "120px"
+     */
     labelWidth: string;
+    /**
+     * @description Screen reader qualifier appended to the `aria-label` of data points that fall
+     * within a highlighted section (e.g. `"projected"`).
+     */
     highlightQualifier: string;
+    /**
+     * @description x-axis value where the highlighted background area begins. If used without
+     * `highlight-end`, the highlight extends to the right edge of the chart.
+     */
     highlightStart?: string;
+    /**
+     * @description x-axis value where the highlighted background area ends.
+     */
     highlightEnd?: string;
+    /**
+     * @description When true, renders hide/show toggle buttons in the legend, allowing users to
+     * hide individual lines.
+     * @default false
+     */
     visibilityToggles: boolean;
+    /**
+     * @description When true, a "Change since [previous x-value]" column appears in each data
+     * point's popover, showing the percentage change from the preceding data point.
+     * @default false
+     */
     showDeltas: boolean;
+    /**
+     * @description Comma-separated numbers that explicitly define the y-axis tick values.
+     * Overrides automatic range and interval calculation.
+     * Example: `"0,100,200,300"`.
+     */
     yRange?: string;
+    /**
+     * @description Adds a reference data point and a spanning horizontal line across the chart.
+     * Must include a `label` key and exactly one x-value key mapping to the y-value.
+     * Example: `{ label: "Target", "2024–25": 500 }`.
+     */
+    spotlightData?: SpotlightData;
+    /**
+     * @description Number of decimal places for data point values and y-axis interval labels.
+     * If omitted, the component infers an appropriate number from the data.
+     */
+    decimalPlaces?: number;
     parsedLineData: LineChartData;
     popoverIndex: number;
     focusedLine: number;
     hiddenLines: number[];
     isTabbing: boolean;
-    intervalSkip: number;
     announcement: string;
     private minTickWidth;
-    private popoverData;
-    private dataPointMatrix;
-    private xIntervals;
-    private displayedXIntervals;
-    private yIntervals;
     private lineStyles;
+    get xIntervals(): string[];
+    get yIntervals(): number[];
+    get intervalInfo(): {
+        skipInterval: number;
+        skippedList: string[];
+    };
+    get displayedXIntervals(): string[];
+    get dataPointMatrix(): DataPointDetails[][];
+    get popoverData(): DataPointDetails[][];
+    get spotlightXValue(): string | undefined;
+    get spotlightYValue(): number | undefined;
     parseData(): void;
-    handleIntervalSkip(): void;
     get hasPartialInterval(): boolean;
     get parsedUnits(): (string | null)[];
     get visibilityToggleEls(): NodeListOf<HTMLWmButtonElement>;
@@ -53,8 +195,8 @@ export declare class LineChart {
     announce(message: string): void;
     lineFocusMessage(lineIdx: number): string;
     focusDataPointByEl(pointEl: HTMLElement): void;
-    calcYIntervals(): number[];
-    determineDisplayedXIntervals(): any[];
+    formatDisplayYValue(yValue: number): string;
+    formatYAxisIntervalLabel(intervalValue: number): string;
     buildLineDataPointDetails(lineLabel: string, line: Line): DataPointDetails[];
     toggleLineVisibility(lineIdx: number): void;
     resetDataPointFocus(): void;
@@ -67,11 +209,14 @@ export declare class LineChart {
     renderData(): any[];
     renderPoints(lineIdx: number): any;
     renderLines(lineIdx: number): any;
+    renderSpotlight(): any;
     renderHoverAreas(): any;
     renderPopover(): any;
     renderPopoverTable(): any;
     renderDeltas(dataPoint: DataPointDetails, prevDataPoint: DataPointDetails): any;
     renderHoverIndicator(): any;
+    renderVerticalGridlines(): any;
+    renderHorizontalGridlines(): any;
     renderHighlight(): any;
     render(): any;
 }

package/dist/types/components/charts/wm-progress-monitor/wm-progress-indicator.d.ts

@@ -1,12 +1,64 @@
 import { ChartDetails } from "../../../global/interfaces";
+/**
+ * Single progress indicator used inside a wm-progress-monitor. Renders the binary completion
+ * data for one category as either a doughnut chart (wide layout) or a horizontal bar (narrow
+ * layout), switching automatically based on the parent monitor's breakpoint.
+ *
+ * Must contain EXACTLY TWO wm-progress-slice children — one for the "complete" state and one
+ * for the "incomplete" state.
+ *
+ * @usageNotes
+ * - Always used as a direct child of wm-progress-monitor.
+ * - `label` is required for accessibility.
+ * - The optional `completion-message` is displayed inside the doughnut when the first slice
+ *   reaches 100%.
+ *
+ * @example {html} Progress indicator
+ * <wm-progress-indicator label="Biology completion">
+ *   <wm-progress-slice legend="Completed" amount="200"></wm-progress-slice>
+ *   <wm-progress-slice legend="Not Completed" amount="100"></wm-progress-slice>
+ * </wm-progress-indicator>
+ *
+ * @example {react} Progress indicator
+ * <WmProgressIndicator label="Biology completion">
+ *   <WmProgressSlice legend="Completed" amount="200" />
+ *   <WmProgressSlice legend="Not Completed" amount="100" />
+ * </WmProgressIndicator>
+ */
 export declare class ProgressIndicator {
     el: HTMLWmProgressIndicatorElement;
     private componentWrapperEl;
+    /**
+     * @description Accessible label for this indicator. Required for accessibility — used as the
+     * `aria-label` on the chart container and as the visual chart label.
+     * @required
+     */
     label?: string;
+    /**
+     * @description Optional secondary text displayed beneath the label.
+     */
     subinfo?: string;
+    /**
+     * @description Text displayed inside the doughnut ring when the completion slice reaches
+     * 100%.
+     */
     completionMessage?: string;
+    /**
+     * @description Show or hide the legend. The legend is still read by screen readers
+     * regardless of this setting.
+     * @default true
+     */
     showLegend: boolean;
+    /**
+     * @description When true, slice values are included in the legend and keyboard interaction
+     * instructions are removed from the DOM — suitable for printed output.
+     * @default false
+     */
     printMode: boolean;
+    /**
+     * @description Format for legend values when `print-mode` is enabled.
+     * @default "amount"
+     */
     printModeFormat: "amount" | "percentage";
     isTabbing: boolean;
     mode?: "doughnut" | "bar";
@@ -15,7 +67,7 @@ export declare class ProgressIndicator {
     private uid;
     private total;
     private slicesDetails;
-    get popoverEl(): HTMLPrivChartPopoverElement | null;
+    get popoverEl(): HTMLPrivChartPopoverOldElement | null;
     get sliceEls(): (SVGElement | HTMLElement)[] | undefined;
     get chartDetails(): ChartDetails | undefined;
     get ariaLabelText(): string;

package/dist/types/components/charts/wm-progress-monitor/wm-progress-monitor.d.ts

@@ -1,9 +1,94 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Container for one or more wm-progress-indicator elements, each showing binary completion
+ * progress (e.g. "Completed" vs "Not Completed"). Above the layout breakpoint, indicators
+ * render as doughnuts in a horizontal row; below it, they collapse into horizontal bars in a
+ * vertical stack.
+ *
+ * **Strict constraints:**
+ * 1. Each wm-progress-indicator must have EXACTLY TWO wm-progress-slice children — one for
+ *    the "complete" state and one for the "incomplete" state.
+ * 2. This component is ONLY suitable for binary completion tracking. For more than two states,
+ *    general comparisons, composition breakdowns, or distributions, use wm-chart,
+ *    wm-chart-bar, or wm-chart-column.
+ *
+ * @category Data Visualization
+ *
+ * @usageNotes
+ * - The `wmProgressMonitorModeChange` event fires once on load and again whenever the layout
+ *   switches between `"doughnut"` and `"bar"`. Listen to it to synchronize any external UI
+ *   that depends on the current layout mode.
+ * - `group-legend` is only shown in bar mode. Provide two comma-separated keys in
+ *   complete/incomplete order (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
+ *
+ * @example {html} Progress monitor
+ * <wm-progress-monitor group-legend="Completed,Not Completed">
+ *   <wm-progress-indicator label="Biology">
+ *     <wm-progress-slice legend="Completed" amount="200"
+ *       popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+ *     <wm-progress-slice legend="Not Completed" amount="100"
+ *       popover-title="100 students" popover-text="Have not completed all requirements"></wm-progress-slice>
+ *   </wm-progress-indicator>
+ * </wm-progress-monitor>
+ *
+ * @example {react} Progress monitor
+ * // wmProgressMonitorModeChange fires on load and whenever the layout switches.
+ * // event.detail is "doughnut" | "bar".
+ * const [layoutMode, setLayoutMode] = useState("");
+ *
+ * <WmProgressMonitor
+ *   groupLegend="Completed,Not Completed"
+ *   onWmProgressMonitorModeChange={(e) => setLayoutMode(e.detail)}
+ * >
+ *   <WmProgressIndicator label="Biology">
+ *     <WmProgressSlice legend="Completed" amount="200"
+ *       popoverTitle="200 students" popoverText="Completed all requirements" />
+ *     <WmProgressSlice legend="Not Completed" amount="100"
+ *       popoverTitle="100 students" popoverText="Have not completed all requirements" />
+ *   </WmProgressIndicator>
+ *   <WmProgressIndicator label="English">
+ *     <WmProgressSlice legend="Completed" amount="160"
+ *       popoverTitle="160 students" popoverText="Completed all requirements" />
+ *     <WmProgressSlice legend="Not Completed" amount="40"
+ *       popoverTitle="40 students" popoverText="Have not completed all requirements" />
+ *   </WmProgressIndicator>
+ * </WmProgressMonitor>
+ *
+ * @example {html} Custom breakpoint
+ * <wm-progress-monitor breakpoint="600px" group-legend="Done,Pending">
+ *   <!-- indicators -->
+ * </wm-progress-monitor>
+ *
+ * @example {react} Custom breakpoint
+ * <WmProgressMonitor breakpoint="600px" groupLegend="Done,Pending">
+ *   {/* indicators *\/}
+ * </WmProgressMonitor>
+ *
+ */
 export declare class ProgressMonitor {
     el: HTMLWmProgressMonitorElement;
+    /**
+     * @description Controls when indicators switch between doughnut (horizontal row) and bar
+     * (vertical stack) layouts. Accepts a unit-less number (minimum number of indicators to
+     * show side-by-side — e.g. `4` → 1200 px) or an exact pixel value (e.g. `"900px"`).
+     * Defaults to the sum of all indicator widths — the component tries to fit all on one row
+     * and collapses to bars when it cannot.
+     */
     breakpoint?: number | string;
+    /**
+     * @description Two comma-separated legend keys in complete/incomplete order, displayed only
+     * in bar layout mode (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
+     */
     groupLegend?: string;
+    /**
+     * @description CSS width of the indicator labels when in bar layout mode (e.g. `"180px"`).
+     */
     barLabelsWidth?: string;
+    /**
+     * @description Fires once on load and again whenever the layout switches between `"doughnut"`
+     * and `"bar"` modes. Use this to synchronize external UI that depends on the current layout.
+     * @eventDetails `"doughnut" | "bar"` — the new layout mode.
+     */
     wmProgressMonitorModeChange: EventEmitter;
     private doughnutWidth;
     private prevMode?;

package/dist/types/components/charts/wm-progress-monitor/wm-progress-slice.d.ts

@@ -1,10 +1,54 @@
 import { EventEmitter } from "../../../stencil-public-runtime";
+/**
+ * Data slice for a wm-progress-indicator. Represents one state (complete or incomplete) in
+ * a binary progress chart. Always used as a direct child of wm-progress-indicator.
+ *
+ * Each wm-progress-indicator must contain EXACTLY TWO wm-progress-slice elements.
+ *
+ * @usageNotes
+ * - The first slice is treated as the "complete" state and the second as the "incomplete"
+ *   state for color and layout purposes.
+ * - Use `popover-title`, `popover-text`, and `popover-button-text` to surface additional
+ *   context when the segment is focused or clicked.
+ *
+ * @example {html} Complete/incomplete pair
+ * <wm-progress-slice legend="Completed" amount="200"
+ *   popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+ * <wm-progress-slice legend="Not Completed" amount="100"></wm-progress-slice>
+ *
+ * @example {react} Complete/incomplete pair
+ * <WmProgressSlice legend="Completed" amount="200"
+ *   popoverTitle="200 students" popoverText="Completed all requirements" />
+ * <WmProgressSlice legend="Not Completed" amount="100" />
+ */
 export declare class ProgressSlice {
+    /**
+     * @description Label for this slice in the legend and popovers.
+     * @required
+     */
     legend?: string;
+    /**
+     * @description Numeric value for this slice as a string.
+     */
     amount?: string;
+    /**
+     * @description Title text shown in the data popover when this segment is focused or clicked.
+     */
     popoverTitle?: string;
+    /**
+     * @description Body text shown in the data popover when this segment is focused or clicked.
+     */
     popoverText?: string;
+    /**
+     * @description Label for the action button in the data popover. When set, fires
+     * `wmProgressIndicatorButtonTriggered` when clicked.
+     */
     popoverButtonText?: string;
+    /**
+     * @internal
+     * @description Internal signal notifying the parent wm-progress-indicator to re-read slice
+     * data after a prop update — not for application use.
+     */
     wmProgressSliceUpdated: EventEmitter<void>;
     componentDidUpdate(): void;
 }