@internetstiftelsen/charts 0.11.0 → 0.13.0

package/README.md

@@ -139,6 +139,19 @@ await chart.whenReady();
 Animation is off by default, applies to XY series marks only, and visual
 exports always render the final static state.
 
+## Lifecycle Events
+
+Charts expose `on()` and `off()` for lifecycle subscriptions.
+
+```typescript
+chart.on('ready', (event) => {
+    console.log(event.reason);
+});
+```
+
+See [Getting Started](./docs/getting-started.md#lifecycle-events) for the
+supported events and payloads.
+
 ## Lazy Loading
 
 Use `mountChartWhenVisible` when you want the page to wait until a chart is
@@ -185,6 +198,7 @@ import { XYChart } from '@internetstiftelsen/charts/xy-chart';
 import { Line } from '@internetstiftelsen/charts/line';
 import { Bar } from '@internetstiftelsen/charts/bar';
 import { Legend } from '@internetstiftelsen/charts/legend';
+import { Text } from '@internetstiftelsen/charts/text';
 import { Title } from '@internetstiftelsen/charts/title';
 
 const lineChart = new XYChart({ data: lineData });
@@ -202,6 +216,14 @@ const group = new ChartGroup({
 
 group
     .addChild(new Title({ text: 'Revenue vs Expenses' }))
+    .addChild(
+        new Text({
+            text: 'Source: finance team',
+            position: 'bottom',
+            variant: 'caption',
+            align: 'left',
+        }),
+    )
     .addChart(barChart)
     .addChart(lineChart)
     .addChild(new Legend());
@@ -413,7 +435,7 @@ Grouped parsing rules:
 - [DonutChart](./docs/donut-chart.md) - Donut/pie charts API
 - [PieChart](./docs/pie-chart.md) - Pie chart API
 - [GaugeChart](./docs/gauge-chart.md) - Gauge chart API
-- [Components](./docs/components.md) - Axes, Grid, Tooltip, Legend, Title
+- [Components](./docs/components.md) - Axes, Grid, Tooltip, Legend, Text, Title
 - [Theming](./docs/theming.md) - Colors, fonts, and styling
 
 ## Browser Support

package/dist/base-chart.d.ts

@@ -1,5 +1,5 @@
 import { type Selection } from 'd3';
-import type { ChartData, DataItem, ChartTheme, ResolvedChartTheme, AxisScaleConfig, ExportFormat, ExportOptions, D3Scale, ExportHookContext, ExportRenderContext, LegendItem, LegendMode, LegendSeries, ResponsiveConfig, ResponsiveRenderContext, DeepPartial } from './types.js';
+import type { ChartData, DataItem, ChartTheme, ResolvedChartTheme, AxisScaleConfig, ExportFormat, ExportOptions, D3Scale, ExportHookContext, ExportRenderContext, LegendItem, LegendMode, LegendSeries, ResponsiveConfig, ResponsiveRenderContext, DeepPartial, TextPosition } from './types.js';
 import type { ChartComponentBase, LayoutAwareComponentBase } from './chart-interface.js';
 import type { XAxis } from './x-axis.js';
 import type { YAxis } from './y-axis.js';
@@ -34,6 +34,33 @@ type BaseExportComponentsOptions = {
     tooltip?: boolean;
     legend?: boolean;
 };
+export type ChartRenderReason = 'initial' | 'manual' | 'update' | 'resize' | 'legend' | 'component';
+export type ChartRenderEventName = 'render:start' | 'render' | 'ready';
+type ChartEventBase<TEventName extends string> = {
+    type: TEventName;
+    chart: BaseChart;
+};
+export type ChartRenderEvent<TEventName extends ChartRenderEventName> = ChartEventBase<TEventName> & {
+    reason: ChartRenderReason;
+};
+export type ChartDataEvent = ChartEventBase<'data'> & {
+    data: ChartData;
+    previousData: ChartData;
+};
+export type ChartLegendChangeEvent = ChartEventBase<'legend:change'>;
+export type ChartDestroyEvent = ChartEventBase<'destroy'>;
+export type ChartEventMap = {
+    'render:start': ChartRenderEvent<'render:start'>;
+    render: ChartRenderEvent<'render'>;
+    ready: ChartRenderEvent<'ready'>;
+    data: ChartDataEvent;
+    'legend:change': ChartLegendChangeEvent;
+    destroy: ChartDestroyEvent;
+};
+export type ChartEventName = keyof ChartEventMap;
+export type ChartEventListener<TEventName extends ChartEventName> = (event: ChartEventMap[TEventName]) => void;
+type ChartEventPayload<TEventName extends ChartEventName> = Omit<ChartEventMap[TEventName], 'type' | 'chart'>;
+type ChartEventPayloadArgs<TEventName extends ChartEventName> = keyof ChartEventPayload<TEventName> extends never ? [payload?: ChartEventPayload<TEventName>] : [payload: ChartEventPayload<TEventName>];
 export type BaseLayoutContext = {
     svg: Selection<SVGSVGElement, undefined, null, undefined>;
     svgNode: SVGSVGElement;
@@ -48,6 +75,13 @@ type ComponentSlot<TComponent extends ChartComponentBase = ChartComponentBase> =
     set: (component: TComponent | null) => void;
     onRegister?: (component: TComponent) => void;
 };
+type TextLayoutComponent = LayoutAwareComponentBase & ChartComponentBase & {
+    display: boolean;
+    text: string;
+    position: TextPosition;
+    variant: string;
+    render: (svg: Selection<SVGSVGElement, undefined, null, undefined>, theme: ChartTheme, width: number, x?: number, y?: number) => void;
+};
 export type BaseChartConfig = {
     data: ChartData;
     width?: number;
@@ -75,6 +109,7 @@ export declare abstract class BaseChart {
     protected tooltip: Tooltip | null;
     protected legend: Legend | null;
     protected title: Title | null;
+    protected textComponents: TextLayoutComponent[];
     protected svg: Selection<SVGSVGElement, undefined, null, undefined> | null;
     protected plotGroup: Selection<SVGGElement, undefined, null, undefined> | null;
     protected container: HTMLElement | null;
@@ -88,8 +123,12 @@ export declare abstract class BaseChart {
     private disconnectedLegendContainer;
     private renderThemeOverride;
     private renderSizeOverride;
-    private readonly renderCallbacks;
     private legendModeOverride;
+    private readonly eventListeners;
+    private renderId;
+    private readyEventVersion;
+    private isPerformingRender;
+    private currentRenderReason;
     protected constructor(config: BaseChartConfig);
     /**
      * Adds a component (axis, grid, tooltip, etc.) to the chart
@@ -108,6 +147,7 @@ export declare abstract class BaseChart {
     private pushIfIncluded;
     private resolveAccessibleLabel;
     private syncAccessibleLabelFromSvg;
+    private resolvePrimaryTextLabel;
     protected resolveResponsiveContext(context: {
         width: number;
         height: number;
@@ -126,14 +166,19 @@ export declare abstract class BaseChart {
         height?: number;
     };
     setLegendModeOverride(mode: LegendMode | null, rerender?: boolean): this;
+    on<TEventName extends ChartEventName>(eventName: TEventName, listener: ChartEventListener<TEventName>): this;
+    off<TEventName extends ChartEventName>(eventName: TEventName, listener: ChartEventListener<TEventName>): this;
     onRender(callback: () => void): () => void;
+    protected emit<TEventName extends ChartEventName>(eventName: TEventName, ...[payload]: ChartEventPayloadArgs<TEventName>): void;
     private notifyRendered;
+    private createRenderEventPayload;
     /**
      * Get layout-aware components in order
      * Override in subclasses to provide chart-specific components
      */
     protected getLayoutComponents(): LayoutAwareComponentBase[];
     protected getBaseLayoutComponents(options: BaseLayoutComponentsOptions): LayoutAwareComponentBase[];
+    private getTextComponents;
     protected getExportComponents(): ChartComponentBase[];
     protected getOverrideableComponents(): ChartComponentBase[];
     protected getBaseExportComponents(options: BaseExportComponentsOptions): ChartComponentBase[];
@@ -160,6 +205,7 @@ export declare abstract class BaseChart {
      * Setup ResizeObserver for automatic resize handling
      */
     private setupResizeObserver;
+    private notifyLegendChanged;
     /**
      * Subclasses must implement this method to define their rendering logic
      */
@@ -186,10 +232,11 @@ export declare abstract class BaseChart {
     private resolveDisconnectedLegendHost;
     private cleanupDisconnectedLegendContainer;
     protected parseValue(value: unknown): number;
-    protected rerender(): void;
+    protected rerender(reason?: ChartRenderReason): void;
     protected tryRegisterComponent(component: ChartComponentBase, slots: readonly ComponentSlot[]): boolean;
     protected applySlotOverrides(overrides: Map<ChartComponentBase, ChartComponentBase>, slots: readonly ComponentSlot[]): () => void;
     protected applyArrayComponentOverrides<TComponent extends ChartComponentBase>(components: TComponent[], overrides: Map<ChartComponentBase, ChartComponentBase>, isComponent: (component: ChartComponentBase) => component is TComponent): () => void;
+    private isTextComponent;
     private getBaseComponentSlots;
     /**
      * Exports the chart in the specified format

package/dist/base-chart.js

@@ -135,6 +135,12 @@ export class BaseChart {
             writable: true,
             value: null
         });
+        Object.defineProperty(this, "textComponents", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
         Object.defineProperty(this, "svg", {
             enumerable: true,
             configurable: true,
@@ -213,17 +219,41 @@ export class BaseChart {
             writable: true,
             value: null
         });
-        Object.defineProperty(this, "renderCallbacks", {
+        Object.defineProperty(this, "legendModeOverride", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: new Set()
+            value: null
         });
-        Object.defineProperty(this, "legendModeOverride", {
+        Object.defineProperty(this, "eventListeners", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: null
+            value: new Map()
+        });
+        Object.defineProperty(this, "renderId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "readyEventVersion", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "isPerformingRender", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "currentRenderReason", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'manual'
         });
         const normalized = normalizeChartData(config.data);
         ChartValidator.validateData(normalized.data);
@@ -238,7 +268,8 @@ export class BaseChart {
         this.responsiveConfig = config.responsive;
         this.legendState = new LegendStateController();
         this.legendState.subscribe(() => {
-            this.rerender();
+            this.notifyLegendChanged();
+            this.rerender('legend');
         });
         this.layoutManager = new LayoutManager(this.resolvedRenderTheme);
     }
@@ -253,12 +284,13 @@ export class BaseChart {
      * Renders the chart to the specified target element
      */
     render(target) {
+        const reason = this.container ? 'manual' : 'initial';
         const container = this.resolveContainer(target);
         this.cleanupDisconnectedLegendContainer();
         this.container = container;
         container.innerHTML = '';
         // Perform initial render
-        this.performRender();
+        this.performRender(reason);
         // Set up ResizeObserver for automatic resize handling
         this.setupResizeObserver();
         return container;
@@ -279,11 +311,13 @@ export class BaseChart {
     /**
      * Performs the actual rendering logic
      */
-    performRender() {
+    performRender(reason) {
         if (!this.container) {
             return;
         }
-        const dimensions = this.resolveRenderDimensions(this.container.getBoundingClientRect());
+        const container = this.container;
+        this.renderId += 1;
+        const dimensions = this.resolveRenderDimensions(container.getBoundingClientRect());
         this.width = dimensions.width;
         this.height = dimensions.height;
         const sizeContext = {
@@ -297,17 +331,24 @@ export class BaseChart {
         const overrideComponents = this.createOverrideComponents(mergedComponentOverrides);
         const restoreComponents = this.applyComponentOverrides(overrideComponents);
         const restoreTheme = this.applyRenderTheme(renderTheme);
+        let renderCompleted = false;
         try {
+            this.currentRenderReason = reason;
+            this.isPerformingRender = true;
             this.setReadyPromise(Promise.resolve());
+            this.svg = null;
+            this.plotGroup = null;
+            this.plotArea = null;
+            this.emit('render:start', this.createRenderEventPayload(reason));
             // Clear and setup SVG
-            this.container.innerHTML = '';
+            container.innerHTML = '';
             this.svg = create('svg')
                 .attr('width', dimensions.svgWidthAttr)
                 .attr('height', dimensions.svgHeightAttr)
                 .attr('role', 'img')
                 .attr('aria-label', this.resolveAccessibleLabel())
                 .style('display', 'block');
-            this.container.appendChild(this.svg.node());
+            container.appendChild(this.svg.node());
             const svgNode = this.svg.node();
             if (!svgNode) {
                 throw new Error('Failed to initialize chart SVG');
@@ -332,9 +373,14 @@ export class BaseChart {
                 plotArea,
             });
             this.renderDisconnectedLegend();
-            this.notifyRendered();
+            this.notifyRendered(reason);
+            renderCompleted = true;
         }
         finally {
+            if (!renderCompleted) {
+                this.readyEventVersion += 1;
+            }
+            this.isPerformingRender = false;
             restoreComponents();
             restoreTheme();
         }
@@ -370,20 +416,31 @@ export class BaseChart {
         }
     }
     resolveAccessibleLabel() {
-        const titleText = this.title?.text.trim();
+        const titleText = this.resolvePrimaryTextLabel();
         if (titleText) {
             return titleText;
         }
         return 'Chart';
     }
     syncAccessibleLabelFromSvg(svg) {
-        const titleText = svg.querySelector('.title text')?.textContent?.trim();
+        const titleText = svg
+            .querySelector('.title text, .text--title text')
+            ?.textContent?.trim();
         if (titleText) {
             svg.setAttribute('aria-label', titleText);
             return;
         }
         svg.setAttribute('aria-label', this.resolveAccessibleLabel());
     }
+    resolvePrimaryTextLabel() {
+        return this.textComponents
+            .find((component) => {
+            return (component.display &&
+                (component.type === 'title' ||
+                    component.variant === 'title'));
+        })
+            ?.text.trim();
+    }
     resolveResponsiveContext(context) {
         const activeBreakpoints = this.resolveActiveBreakpoints(context.width).map(({ name }) => name);
         return {
@@ -465,21 +522,61 @@ export class BaseChart {
         }
         this.legendModeOverride = mode;
         if (rerender) {
-            this.rerender();
+            this.rerender('component');
+        }
+        return this;
+    }
+    on(eventName, listener) {
+        let listeners = this.eventListeners.get(eventName);
+        if (!listeners) {
+            listeners = new Set();
+            this.eventListeners.set(eventName, listeners);
+        }
+        listeners.add(listener);
+        return this;
+    }
+    off(eventName, listener) {
+        const listeners = this.eventListeners.get(eventName);
+        if (!listeners) {
+            return this;
+        }
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+            this.eventListeners.delete(eventName);
         }
         return this;
     }
     onRender(callback) {
-        this.renderCallbacks.add(callback);
+        const listener = () => {
+            callback();
+        };
+        this.on('render', listener);
         return () => {
-            this.renderCallbacks.delete(callback);
+            this.off('render', listener);
         };
     }
-    notifyRendered() {
-        this.renderCallbacks.forEach((callback) => {
-            callback();
+    emit(eventName, ...[payload]) {
+        const listeners = this.eventListeners.get(eventName);
+        if (!listeners) {
+            return;
+        }
+        const event = {
+            ...(payload ?? {}),
+            type: eventName,
+            chart: this,
+        };
+        [...listeners].forEach((listener) => {
+            listener(event);
         });
     }
+    notifyRendered(reason) {
+        this.emit('render', this.createRenderEventPayload(reason));
+    }
+    createRenderEventPayload(reason) {
+        return {
+            reason,
+        };
+    }
     /**
      * Get layout-aware components in order
      * Override in subclasses to provide chart-specific components
@@ -494,8 +591,8 @@ export class BaseChart {
     }
     getBaseLayoutComponents(options) {
         const components = [];
-        if (options.title && this.title) {
-            components.push(this.title);
+        if (options.title) {
+            components.push(...this.getTextComponents('top'));
         }
         if (options.xAxis && this.xAxis) {
             components.push(this.xAxis);
@@ -506,8 +603,16 @@ export class BaseChart {
         if (options.inlineLegend && this.legend && this.hasInlineLegend()) {
             components.push(this.legend);
         }
+        if (options.title) {
+            components.push(...this.getTextComponents('bottom'));
+        }
         return components;
     }
+    getTextComponents(position) {
+        return this.textComponents.filter((component) => {
+            return component.position === position;
+        });
+    }
     getExportComponents() {
         return this.getBaseExportComponents({
             title: true,
@@ -523,7 +628,9 @@ export class BaseChart {
     }
     getBaseExportComponents(options) {
         const components = [];
-        this.pushIfIncluded(components, options.title, this.title);
+        if (options.title) {
+            components.push(...this.textComponents);
+        }
         this.pushIfIncluded(components, options.grid, this.grid);
         this.pushIfIncluded(components, options.xAxis, this.xAxis);
         this.pushIfIncluded(components, options.yAxis, this.yAxis);
@@ -532,6 +639,13 @@ export class BaseChart {
         return components;
     }
     registerBaseComponent(component) {
+        if (this.isTextComponent(component)) {
+            this.textComponents.push(component);
+            if (component.type === 'title' && !this.title) {
+                this.title = component;
+            }
+            return true;
+        }
         return this.tryRegisterComponent(component, this.getBaseComponentSlots());
     }
     collectExportOverrides(context) {
@@ -659,7 +773,18 @@ export class BaseChart {
         return overrideComponents;
     }
     applyComponentOverrides(overrides) {
-        return this.applySlotOverrides(overrides, this.getBaseComponentSlots());
+        const previousTitle = this.title;
+        const restoreSlots = this.applySlotOverrides(overrides, this.getBaseComponentSlots());
+        const restoreText = this.applyArrayComponentOverrides(this.textComponents, overrides, this.isTextComponent);
+        this.title =
+            this.textComponents.find((component) => {
+                return component.type === 'title';
+            }) ?? null;
+        return () => {
+            restoreText();
+            restoreSlots();
+            this.title = previousTitle;
+        };
     }
     renderExportChart(chart, width, height) {
         const container = document.createElement('div');
@@ -690,11 +815,10 @@ export class BaseChart {
         });
     }
     renderTitle(svg) {
-        if (!this.title) {
-            return;
-        }
-        const position = this.layoutManager.getComponentPosition(this.title);
-        this.title.render(svg, this.renderTheme, this.width, position.x, position.y);
+        this.textComponents.forEach((component) => {
+            const position = this.layoutManager.getComponentPosition(component);
+            component.render(svg, this.renderTheme, this.width, position.x, position.y);
+        });
     }
     renderInlineLegend(svg) {
         if (!this.legend || !this.hasInlineLegend()) {
@@ -732,8 +856,9 @@ export class BaseChart {
      * Setup ResizeObserver for automatic resize handling
      */
     setupResizeObserver() {
-        if (!this.container)
+        if (!this.container) {
             return;
+        }
         if (this.resizeObserver) {
             this.resizeObserver.disconnect();
         }
@@ -746,12 +871,32 @@ export class BaseChart {
                 nextDimensions.height === this.height) {
                 return;
             }
-            this.rerender();
+            this.rerender('resize');
         });
         this.resizeObserver.observe(this.container);
     }
+    notifyLegendChanged() {
+        this.emit('legend:change');
+    }
     setReadyPromise(promise) {
         this.readyPromise = promise;
+        if (!this.isPerformingRender || !this.container) {
+            return;
+        }
+        const renderId = this.renderId;
+        const reason = this.currentRenderReason;
+        const container = this.container;
+        const readyVersion = ++this.readyEventVersion;
+        void promise
+            .then(() => {
+            if (readyVersion !== this.readyEventVersion ||
+                renderId !== this.renderId ||
+                container !== this.container) {
+                return;
+            }
+            this.emit('ready', this.createRenderEventPayload(reason));
+        })
+            .catch(() => undefined);
     }
     whenReady() {
         return this.readyPromise;
@@ -796,16 +941,23 @@ export class BaseChart {
         this.validateSourceData(data);
         const normalized = normalizeChartData(data);
         ChartValidator.validateData(normalized.data);
+        const previousSourceData = this.sourceData;
         const previousData = this.data;
         this.sourceData = data;
         this.data = normalized.data;
         this.syncDerivedState(previousData);
-        this.rerender();
+        this.emit('data', {
+            data: this.sourceData,
+            previousData: previousSourceData,
+        });
+        this.rerender('update');
     }
     /**
      * Destroys the chart and cleans up resources
      */
     destroy() {
+        this.readyEventVersion += 1;
+        this.emit('destroy');
         this.tooltip?.cleanup();
         if (this.resizeObserver) {
             this.resizeObserver.disconnect();
@@ -900,11 +1052,11 @@ export class BaseChart {
         }
         return 0;
     }
-    rerender() {
+    rerender(reason = 'manual') {
         if (!this.container) {
             return;
         }
-        this.performRender();
+        this.performRender(reason);
     }
     tryRegisterComponent(component, slots) {
         const slot = slots.find((entry) => entry.type === component.type);
@@ -952,15 +1104,11 @@ export class BaseChart {
             components.splice(0, components.length, ...previousState);
         };
     }
+    isTextComponent(component) {
+        return component.type === 'text' || component.type === 'title';
+    }
     getBaseComponentSlots() {
         return [
-            {
-                type: 'title',
-                get: () => this.title,
-                set: (component) => {
-                    this.title = component;
-                },
-            },
             {
                 type: 'grid',
                 get: () => this.grid,

package/dist/chart-group.d.ts

@@ -56,7 +56,7 @@ export declare class ChartGroup {
     private readonly warnedColorConflicts;
     private container;
     private legend;
-    private title;
+    private readonly textComponents;
     private resizeObserver;
     private readyPromise;
     private childLegendSnapshot;
@@ -69,6 +69,7 @@ export declare class ChartGroup {
     addChild(component: {
         type: string;
     }): this;
+    private isTextComponent;
     render(target: string | HTMLElement): HTMLElement | null;
     refresh(): HTMLElement | null;
     whenReady(): Promise<void>;
@@ -79,6 +80,7 @@ export declare class ChartGroup {
     toggleLegendSeries(dataKey: string): this;
     setLegendVisibility(visibility: Record<string, boolean>): this;
     onLegendChange(callback: () => void): () => void;
+    private resolveAccessibleLabel;
     export(format: ChartGroupExportFormat, options?: ExportOptions): Promise<string | Blob | void>;
     destroy(): void;
     private bindChartRenderCallback;
@@ -105,15 +107,19 @@ export declare class ChartGroup {
     private serializeChildLegendState;
     private serializeChildYDomains;
     private renderLegendIntoContainer;
-    private renderTitleSvg;
+    private renderTextSvg;
+    private renderTextSvgs;
     private renderLegendSvg;
     private setupResizeObserver;
     private exportSVG;
     private resolveChartOptions;
     private refreshIfMounted;
     private prepareRenderState;
+    private sumRenderedTextHeight;
     private createRenderHosts;
     private appendRenderedSection;
+    private appendRenderedTextSections;
+    private resolveTextSectionClassName;
     private renderLayoutItems;
     private createChartHost;
     private createReadyPromise;
@@ -122,9 +128,16 @@ export declare class ChartGroup {
     private createRasterExportOptions;
     private exportPdfContent;
     private resolveExportLayoutState;
+    private createExportLayoutState;
+    private createExportRenderContext;
+    private resolveBaseExportHeight;
+    private createExportComponent;
+    private runExportHooks;
     private resolveLiveChartHeightOverride;
     private exportLayoutItems;
     private composeExportSvg;
+    private syncAccessibleLabelFromSvg;
+    private appendExportTextSections;
     private validateResponsiveConfig;
     private validateItemResponsiveConfig;
     private resolveResponsiveConfigForWidth;