Charts

Usage & API Reference

This section documents the chart configuration format, dataset fields, options, and examples. The charts on this page are powered by the site chart module and initialized using McGowanStyle.chart.createChart(el, config) (the project also auto-initializes elements with data-ms="chart" on load).

How to provide data

• Inline with the element using the data-chart attribute (JSON string). Example: <div data-ms="chart" data-chart='{"type":"line","data":{...}}'></div>.
• Inside a child <script type="application/json"> inside the chart element (preferred for larger payloads).
• Programmatically using the JS API: McGowanStyle.chart.createChart(element, config). The created instance is stored on the element as element.__msChart.

Config shape (top-level)

{
  "type": "line" | "bar" | "pie",
  "data": { "labels": [...], "datasets": [ { "label": "...", "data": [...] }, ... ] },
  "options": { ... }
}

Dataset fields

• label: string shown in the legend.
• data: array of numbers (or values for pie).
• borderColor: line color for line charts.
• backgroundColor: fill color for areas/bars or array of colors for per-item coloring.
• fill: boolean, fill under line.
• borderWidth: numeric stroke width.
• pointBackgroundColor: circle fill color for line points.
• pointRadius: radius for data points.
• hidden: boolean (initial visibility). The legend toggle sets this flag and triggers an update.

Options

Common options under options:

• legend: boolean (show legend). When present, a legend is rendered into a .ms-chart-footer element associated with the chart and centered by the stylesheet (src/scss/chart/_legend.scss).
• padding: numeric padding around the plot (default 24).
• yTicksCount: number of Y ticks (default 4).
• gridColor, axisColor, font, fontColor, hoverColor: styling values applied by the renderer.
• barWidthRatio: fraction of the X slot used for bars (default 0.7).
• scales: object with optional x and y configuration. Example: options.scales.y.stacked = true for stacked bars; options.scales.x.label and options.scales.y.label set axis labels.
• tooltip: set to false to disable hover tooltips.

Examples

Line chart (with axes and axis labels)

{
  "type": "line",
  "data": { "labels": ["Jan","Feb","Mar"], "datasets": [{ "label": "Visitors", "data": [10,20,15], "borderColor": "#2196f3", "fill": true }] },
  "options": { "legend": true, "scales": { "x": { "label": "Month" }, "y": { "label": "Visits" } } }
}

Programmatic usage

Use the chart factory to create or update charts from JS. The returned instance is stored on the element as el.__msChart and has at least these methods:

• update(newConfig) — merge and redraw with new config or data.
• resize(width, height) — resize programmatically.
• destroy() — remove chart and any generated DOM like legend/tooltips.
• canvas — reference to the created <canvas>.

// create
const el = document.getElementById('chartLine_default');
McGowanStyle.chart.createChart(el, cfg);
// get the instance
const inst = el.__msChart;
// update
inst.update({ data: { datasets: [{ data: [1,2,3] }] } });

Legend behavior

• Legends are rendered into a .ms-chart-footer associated with the chart and centered by CSS.
• Legend items are interactive buttons: clicking them toggles the matching dataset's hidden flag and the chart instance is updated automatically.
• Legends are keyboard accessible (Tab to a legend button and press Enter/Space to toggle).

Accessibility

• Tooltips are announced using an ARIA live region to help screen readers.
• Legends use native buttons with aria-pressed to indicate visibility state.
• For full screen-reader support, the chart code includes helpers to create data tables (see src/js/chart/accessibility.js).

Troubleshooting

• If charts do not appear, confirm the project JS bundle is included (mcgowan scripts) and that the target element has data-ms="chart" or you created it programmatically.
• If legend placement looks wrong, ensure the stylesheet was rebuilt — the legend/footer placement and centering are provided by src/scss/chart/_legend.scss. Run npm run build to regenerate cdn/dist/mcgowan.css and then hard-refresh the browser.
• If legend toggles do not visually hide data, ensure the dataset includes a hidden flag and that the chart instance is updated (the legend toggle sets that flag and triggers instance.update()).

Tip: After making changes to SCSS, run your normal build (for example npm run build) so the compiled CSS includes the new legend/footer styles.

Default (legend + axes)

No legend

Minimal (no axes labels)

Grouped bars (two datasets)

Stacked bars

No legend

Default pie

Small pie (no legend)

Per-slice colors