@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -1,18 +1,130 @@
 import { ChartType, SliceDetails, SliceElement } from "../../../global/interfaces";
+/**
+ * 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.
+ *
+ * @category Data Visualization
+ *
+ * @keyboardInteraction
+ * - **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.
+ *
+ * @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.
+ *
+ * @usageNotes
+ * - 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.
+ *
+ * @example {html} Doughnut chart
+ * <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>
+ *
+ * @example {react} Doughnut chart
+ * <WmChart label="Enrollment by status">
+ *   <WmChartSlice legend="Enrolled" amount="310" />
+ *   <WmChartSlice legend="Not enrolled" amount="90" />
+ * </WmChart>
+ *
+ * @example {html} Bar composition chart
+ * <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>
+ *
+ * @example {react} Bar composition chart
+ * <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>
+ *
+ */
 export declare class Chart {
     el: HTMLWmChartElement;
     private componentWrapperEl;
+    /**
+     * @description Chart subtype. Doughnut subtypes (`doughnut1`–`doughnut3`) and bar composition
+     * subtypes (`bar2`–`bar7`) — each tailored to a specific composition use case.
+     * @default "doughnut1"
+     */
     chartType: ChartType;
+    /**
+     * @description 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?: string;
+    /**
+     * @description Controls the bar label width. Only applies to `bar6` and `bar7` subtypes.
+     * @default "150px"
+     */
     labelWidth: string;
+    /**
+     * @description Optional secondary text displayed beneath the chart label. Not shown when
+     * `label-position` is `"none"`.
+     */
     subinfo?: string;
+    /**
+     * @description Controls how individual segment values are displayed on the chart.
+     * @default "none"
+     */
     valueFormat: "percentage" | "amount" | "none";
+    /**
+     * @description Show or hide the value grid lines. Only applies to `bar6`.
+     * @default true
+     */
     showGrid?: boolean;
+    /**
+     * @description Show or hide the legend below the chart. The legend is still read by screen
+     * readers regardless of this setting.
+     * @default true
+     */
     showLegend: boolean;
+    /**
+     * @description Show or hide the y-axis bar legend. Only applies to `bar7`.
+     * @default false
+     */
     showBarLegend: boolean;
+    /**
+     * @description When true, applies a gray color to the first slice to represent a
+     * "not started" state. Only applies to `bar5`.
+     * @default false
+     */
     notStartedColor: 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: "percentage" | "amount";
+    /**
+     * @description 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.
+     * @default "top"
+     */
     labelPosition: "left" | "top" | "none";
     isTabbing: boolean;
     userIsNavigating: boolean;
@@ -20,7 +132,7 @@ export declare class Chart {
     private uid;
     private total;
     private slicesDetails;
-    get popoverEl(): HTMLPrivChartPopoverElement | null;
+    get popoverEl(): HTMLPrivChartPopoverOldElement | null;
     get sliceEls(): SliceElement[];
     get currentChartType(): ChartType;
     get chartDetails(): import("../../../global/interfaces").ChartDetails;

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

@@ -0,0 +1,195 @@
+import { EventEmitter } from "../../../stencil-public-runtime";
+import { ChartConfig, ChartData, ProcessedChartData, ChartGridInfo, ProcessedChartDataGrouped } from "../../../global/interfaces";
+/**
+ * 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*">`.
+ *
+ * @category Data Visualization
+ * @displayName Bar Chart
+ *
+ * @keyboardInteraction
+ * - **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.
+ *
+ * @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.
+ *
+ * @usageNotes
+ * - 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.
+ *
+ * @example {html} Single-color bar chart
+ * <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>
+ *
+ * @example {react} Single-color bar chart
+ * // 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} />
+ *
+ * @example {html} Grouped bar chart
+ * <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>
+ *
+ * @example {react} Grouped bar chart
+ * // 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} />
+ *
+ */
+export declare class ChartBar {
+    el: HTMLWmChartBarElement;
+    private barAreaEl;
+    private popoverEl;
+    private componentWrapperEl;
+    private gridMax;
+    private isGrouped;
+    private legendData;
+    /**
+     * @description 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.).
+     */
+    config?: ChartConfig;
+    /**
+     * @description 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.
+     */
+    data?: ChartData[];
+    /**
+     * @description 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`.
+     * @default false
+     */
+    printMode?: boolean;
+    /**
+     * @description 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`.
+     * @default false
+     */
+    patternMode?: boolean;
+    /**
+     * @description Optional secondary text displayed beneath the chart label. Takes precedence
+     * over `config.subinfo`.
+     */
+    subinfo?: string;
+    processedData: ProcessedChartDataGrouped;
+    gridInfo?: ChartGridInfo;
+    isKeying: boolean;
+    /**
+     * @internal
+     * @description Internal signal used to synchronize bar highlight state with an external
+     * wm-chart-legend — not for application use.
+     */
+    wmChartBarHighlighted: EventEmitter<{
+        idx: number;
+    }>;
+    get colorPalette(): string[];
+    get sort(): "ascending" | "descending" | "none";
+    get showLegend(): "left" | "right" | "top" | "bottom" | "none";
+    get subinfoText(): string;
+    get gridVisible(): boolean;
+    get flattenedData(): ProcessedChartData[];
+    componentDidLoad(): void;
+    handleConfigDataChange(): void;
+    buildProcessedData(): ProcessedChartDataGrouped;
+    propagateExternalLegendData(): void;
+    calculateGridInfo(): ChartGridInfo;
+    handleChartKeyDown(ev: KeyboardEvent): void;
+    handleBarKeyDown(ev: KeyboardEvent, item: ProcessedChartData): void;
+    handleBarClick(ev: MouseEvent, item: ProcessedChartData): void;
+    handleLegendItemClick(ev: CustomEvent<{
+        idx: number;
+    }>): void;
+    handleDocumentClick(_ev: MouseEvent): void;
+    handleUserIsKeying(): void;
+    handleUserIsNotKeying(): void;
+    handleComponentBlur(ev: FocusEvent): void;
+    focusBar(barIdx: number): void;
+    handlePopoverToggled(_ev: CustomEvent): void;
+    openPopover(clickedProcessedData: ProcessedChartData, coords: {
+        x: number;
+        y: number;
+    }): void;
+    clearHighlights(): void;
+    highlightBar(item: ProcessedChartData): void;
+    highlightBarsByLegend(barLegend: string): void;
+    clearFocus(): void;
+    renderBarValue(item: ProcessedChartData, barPercent: number): any;
+    renderBarLegends(): HTMLDivElement[];
+    renderBar(item: ProcessedChartData, effectiveGridMax: number): any;
+    renderBars(): HTMLDivElement[] | undefined;
+    renderGroupLegends(): HTMLDivElement[];
+    renderGroupedBars(): HTMLDivElement[] | undefined;
+    renderXAxis(): any;
+    renderGrid(): any;
+    renderLegend(orientation: "horizontal" | "vertical"): any;
+    render(): any;
+}

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

@@ -0,0 +1,184 @@
+import { EventEmitter } from "../../../stencil-public-runtime";
+import { ChartConfig, ChartData, ProcessedChartData, ChartGridInfo, ProcessedChartDataGrouped } from "../../../global/interfaces";
+/**
+ * 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.
+ *
+ * @category Data Visualization
+ * @displayName Column Chart
+ *
+ * @keyboardInteraction
+ * - **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.
+ *
+ * @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.
+ *
+ * @usageNotes
+ * - 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.
+ *
+ * @example {html} Single-color column chart
+ * <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>
+ *
+ * @example {react} Single-color column chart
+ * <WmChartColumn ref={chartRef} />
+ * // In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+ *
+ * @example {html} Grouped column chart
+ * <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>
+ *
+ * @example {react} Grouped column chart
+ * <WmChartColumn ref={chartRef} />
+ * // In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+ *
+ */
+export declare class ChartColumn {
+    el: HTMLWmChartColumnElement;
+    private popoverEl;
+    private componentWrapperEl;
+    private gridMax;
+    private isGrouped;
+    private legendData;
+    private plotColumnWidth;
+    /**
+     * @description 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.).
+     */
+    config?: ChartConfig;
+    /**
+     * @description 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.
+     */
+    data?: ChartData[];
+    /**
+     * @description 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.
+     */
+    printWidth?: string;
+    /**
+     * @description 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`.
+     * @default false
+     */
+    printMode?: boolean;
+    /**
+     * @description 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`.
+     * @default false
+     */
+    patternMode?: boolean;
+    /**
+     * @description Optional secondary text displayed beneath the chart label. Takes precedence
+     * over `config.subinfo`.
+     */
+    subinfo?: string;
+    processedData: ProcessedChartDataGrouped;
+    gridInfo?: ChartGridInfo;
+    isKeying: boolean;
+    private plotDivisions;
+    private userIsPrinting;
+    /**
+     * @internal
+     * @description Internal signal used to synchronize column highlight state with an external
+     * wm-chart-legend — not for application use.
+     */
+    wmChartBarHighlighted: EventEmitter<{
+        idx: number;
+    }>;
+    get colorPalette(): string[];
+    get sort(): "ascending" | "descending" | "none";
+    get showLegend(): "left" | "right" | "top" | "bottom" | "none";
+    get subinfoText(): string;
+    get gridVisible(): boolean;
+    get flattenedData(): ProcessedChartData[];
+    get columnCount(): number;
+    get isPlotWidthLimited(): boolean;
+    get printWidthPx(): number;
+    getAvailablePlotWidth(padding: number): number;
+    componentDidLoad(): void;
+    updateSpacing(): void;
+    handleConfigDataChange(): void;
+    buildProcessedData(): ProcessedChartDataGrouped;
+    propagateExternalLegendData(): void;
+    calculateGridInfo(): ChartGridInfo;
+    determinePlotDivisions(divisionWidth: number, divisionGap: number, availableWidth: number): number;
+    determinePlots(): void;
+    handleChartKeyDown(ev: KeyboardEvent): void;
+    handleBarKeyDown(ev: KeyboardEvent, item: ProcessedChartData): void;
+    handleBarClick(ev: MouseEvent, item: ProcessedChartData): void;
+    handleLegendItemClick(ev: CustomEvent<{
+        idx: number;
+    }>): void;
+    handleLegendItemHover(ev: CustomEvent<{
+        idx: number;
+    }>): void;
+    handleBeforePrint(): void;
+    handleAfterPrint(): void;
+    handleLegendFocus(idx: number): void;
+    handleDocumentClick(_ev: MouseEvent): void;
+    updateScrollFade(plotAreaEl: HTMLDivElement): void;
+    debouncedAdjustLayout: (this: any) => void;
+    handleUserIsKeying(): void;
+    handleUserIsNotKeying(): void;
+    handleComponentBlur(ev: FocusEvent): void;
+    focusBar(barIdx: number): void;
+    scrollToBar(barIdx: number): void;
+    handlePopoverToggled(_ev: CustomEvent): void;
+    openPopover(clickedProcessedData: ProcessedChartData, coords: {
+        x: number;
+        y: number;
+    }): void;
+    clearHighlights(): void;
+    highlightBar(item: ProcessedChartData): void;
+    highlightBarsByLegend(barLegend: string): void;
+    clearFocus(): void;
+    renderBarValue(item: ProcessedChartData, barPercent: number): any;
+    renderGrid(): any;
+    renderYAxis(): any;
+    renderLegend(orientation: "horizontal" | "vertical"): any;
+    renderPlotContainers(): any;
+    renderPlot(plotIdx: number, totalDivisions: number): any;
+    renderCategoryAxisLabel(): any;
+    renderColumns(indices: number[]): HTMLDivElement[];
+    renderBar(item: ProcessedChartData, idx: number): any;
+    renderXAxis(indices: number[]): HTMLDivElement[];
+    render(): any;
+}

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

@@ -0,0 +1,110 @@
+import { EventEmitter } from "../../../stencil-public-runtime";
+import { ProcessedChartData } from "../../../global/interfaces";
+/**
+ * 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.
+ *
+ * @category Data Visualization
+ *
+ * @usageNotes
+ * - 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.
+ *
+ * @example {html} Shared legend for two charts
+ * <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>
+ *
+ * @example {react} Shared legend for two charts
+ * 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" />
+ *
+ * @example {html} Vertical orientation
+ * <wm-chart-legend chart-ids="my-chart" orientation="vertical"></wm-chart-legend>
+ *
+ * @example {react} Vertical orientation
+ * <WmChartLegend chartIds="my-chart" orientation="vertical" />
+ *
+ */
+export declare class ChartLegend {
+    el: HTMLWmChartLegendElement;
+    /**
+     * @description 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
+     */
+    chartIds: string;
+    /**
+     * @description Layout orientation of legend items.
+     * @default "horizontal"
+     */
+    orientation: "horizontal" | "vertical";
+    /**
+     * @internal
+     * @description Processed chart data injected by the associated chart — not for application
+     * use.
+     */
+    processedData: ProcessedChartData[];
+    /**
+     * @description When true, the print value for each item is shown next to its swatch in the
+     * legend — suitable for printed output.
+     * @default false
+     */
+    printMode: boolean;
+    /**
+     * @internal
+     * @description Pattern orientation injected by the associated chart to align swatch hatching
+     * with bar orientation — not for application use.
+     */
+    patternMode?: "vertical" | "horizontal";
+    private persistentHighlightIdx;
+    /**
+     * @description Fires when the user clicks a legend item. The associated chart highlights
+     * the corresponding bar(s) and fades all others.
+     * @eventDetails {{ idx: number }} idx — zero-based index of the clicked legend item, or
+     * `-1` to clear all highlights.
+     */
+    wmLegendItemClick: EventEmitter<{
+        idx: number;
+    }>;
+    /**
+     * @description Fires when the user hovers over a legend item. The associated chart
+     * highlights the corresponding bar(s) and fades all others.
+     * @eventDetails {{ idx: number }} idx — zero-based index of the hovered legend item, or
+     * `-1` to clear all highlights.
+     */
+    wmLegendItemHover: EventEmitter<{
+        idx: number;
+    }>;
+    handleChartBarHighlighted(ev: CustomEvent<{
+        idx: number;
+    }>): void;
+    handleDocumentClick(_ev: MouseEvent): void;
+    highlightLegendItem(highlightedIdx: number): void;
+    handleLegendItemClick(idx: number): void;
+    handleLegendItemMouseEnter(idx: number): void;
+    handleLegendItemMouseLeave(): void;
+    getSwatchClassMap(item: ProcessedChartData): {
+        color: boolean;
+        patterned: boolean;
+        horizontal: boolean;
+    };
+    renderLegendItems(): any[];
+    render(): any;
+}