@internetstiftelsen/charts 0.11.0 → 0.13.0

package/dist/tooltip.js

@@ -6,9 +6,15 @@ const TOOLTIP_VIEWPORT_PADDING_PX = 10;
 const TOOLTIP_CONNECTOR_INSET_PX = 14;
 const TOOLTIP_CONNECTOR_PADDING_PX = 4;
 const TOOLTIP_CONNECTOR_ELBOW_RATIO = 0.45;
+const TOOLTIP_BORDER_WIDTH_PX = 1;
 const TOOLTIP_BOX_ARROW_LENGTH_PX = 10;
 const TOOLTIP_BOX_ARROW_HALF_HEIGHT_PX = 6;
 const TOOLTIP_CONNECTOR_ALIGNMENT_TOLERANCE_PX = 1;
+const TOOLTIP_CONNECTOR_Z_INDEX = 3;
+const TOOLTIP_ARROW_BORDER_Z_INDEX = 4;
+const TOOLTIP_ARROW_FILL_Z_INDEX = 5;
+const TOOLTIP_BODY_Z_INDEX = 6;
+const TOOLTIP_TOTAL_BORDER_WIDTH_PX = TOOLTIP_BORDER_WIDTH_PX * 2;
 const SPLIT_TOOLTIP_GAP_PX = 8;
 const DEFAULT_TOOLTIP_TRANSITION = {
     show: false,
@@ -706,7 +712,7 @@ export class Tooltip {
         tooltip
             .style('position', 'absolute')
             .style('background-color', theme.tooltip.background)
-            .style('border', `1px solid ${theme.tooltip.border}`)
+            .style('border', `${TOOLTIP_BORDER_WIDTH_PX}px solid ${theme.tooltip.border}`)
             .style('border-radius', '4px')
             .style('padding', '8px')
             .style('box-shadow', '0 2px 4px rgba(0,0,0,0.1)')
@@ -762,6 +768,7 @@ export class Tooltip {
             return;
         }
         this.appendTooltipConnector(tooltip, connectorLayout);
+        this.appendTooltipArrow(tooltip, connectorLayout);
         this.showTooltipAt(tooltip, left, top);
     }
     renderTooltipWithoutConnector(tooltip, left, top) {
@@ -806,10 +813,9 @@ export class Tooltip {
         if (body.empty()) {
             return;
         }
-        body.style('position', 'relative').style('z-index', '1');
+        body.style('position', 'relative').style('z-index', String(TOOLTIP_BODY_Z_INDEX));
     }
     appendTooltipConnector(tooltip, connectorLayout) {
-        const tooltipBackground = this.tooltipTheme?.background ?? '#ffffff';
         const tooltipBorder = this.tooltipTheme?.border ?? '#dddddd';
         const connector = tooltip
             .append('svg')
@@ -824,7 +830,7 @@ export class Tooltip {
             .style('top', `${connectorLayout.top}px`)
             .style('pointer-events', 'none')
             .style('overflow', 'visible')
-            .style('z-index', '0');
+            .style('z-index', String(TOOLTIP_CONNECTOR_Z_INDEX));
         connector
             .append('path')
             .attr('data-chart-tooltip-connector-path', 'true')
@@ -834,29 +840,76 @@ export class Tooltip {
             .attr('stroke-width', 1.25)
             .attr('stroke-linecap', 'round')
             .attr('stroke-linejoin', 'round');
-        connector
-            .append('path')
-            .attr('data-chart-tooltip-arrow', 'true')
-            .attr('d', connectorLayout.arrowPath)
-            .attr('fill', tooltipBackground)
-            .attr('stroke', 'none');
-        connector
-            .append('path')
-            .attr('data-chart-tooltip-arrow-base-mask', 'true')
-            .attr('d', connectorLayout.arrowBaseMaskPath)
-            .attr('fill', 'none')
-            .attr('stroke', tooltipBackground)
-            .attr('stroke-width', 2)
-            .attr('stroke-linecap', 'butt');
-        connector
-            .append('path')
-            .attr('data-chart-tooltip-arrow-border', 'true')
-            .attr('d', connectorLayout.arrowBorderPath)
-            .attr('fill', 'none')
-            .attr('stroke', tooltipBorder)
-            .attr('stroke-width', 1)
-            .attr('stroke-linecap', 'round')
-            .attr('stroke-linejoin', 'round');
+    }
+    appendTooltipArrow(tooltip, connectorLayout) {
+        const tooltipBackground = this.tooltipTheme?.background ?? '#ffffff';
+        const tooltipBorder = this.tooltipTheme?.border ?? '#dddddd';
+        this.appendTooltipArrowTriangle(tooltip, connectorLayout, 'data-chart-tooltip-arrow', tooltipBorder, TOOLTIP_BOX_ARROW_LENGTH_PX, TOOLTIP_BOX_ARROW_HALF_HEIGHT_PX, TOOLTIP_ARROW_BORDER_Z_INDEX);
+        this.appendTooltipArrowTriangle(tooltip, connectorLayout, 'data-chart-tooltip-arrow-fill', tooltipBackground, TOOLTIP_BOX_ARROW_LENGTH_PX - 1, TOOLTIP_BOX_ARROW_HALF_HEIGHT_PX - 1, TOOLTIP_ARROW_FILL_Z_INDEX);
+    }
+    appendTooltipArrowTriangle(tooltip, connectorLayout, dataAttribute, color, length, halfHeight, zIndex) {
+        const position = this.resolveTooltipArrowPosition(connectorLayout.arrowEdge, connectorLayout.arrowX, connectorLayout.arrowY, length, halfHeight);
+        const arrow = tooltip
+            .append('div')
+            .attr(dataAttribute, 'true')
+            .attr('data-chart-tooltip-arrow-edge', connectorLayout.arrowEdge)
+            .attr('aria-hidden', 'true')
+            .style('position', 'absolute')
+            .style('left', `${position.left}px`)
+            .style('top', `${position.top}px`)
+            .style('width', '0')
+            .style('height', '0')
+            .style('pointer-events', 'none')
+            .style('z-index', String(zIndex));
+        if (connectorLayout.arrowEdge === 'left') {
+            arrow
+                .style('border-top', `${halfHeight}px solid transparent`)
+                .style('border-bottom', `${halfHeight}px solid transparent`)
+                .style('border-right', `${length}px solid ${color}`);
+            return;
+        }
+        if (connectorLayout.arrowEdge === 'right') {
+            arrow
+                .style('border-top', `${halfHeight}px solid transparent`)
+                .style('border-bottom', `${halfHeight}px solid transparent`)
+                .style('border-left', `${length}px solid ${color}`);
+            return;
+        }
+        if (connectorLayout.arrowEdge === 'top') {
+            arrow
+                .style('border-left', `${halfHeight}px solid transparent`)
+                .style('border-right', `${halfHeight}px solid transparent`)
+                .style('border-bottom', `${length}px solid ${color}`);
+            return;
+        }
+        arrow
+            .style('border-left', `${halfHeight}px solid transparent`)
+            .style('border-right', `${halfHeight}px solid transparent`)
+            .style('border-top', `${length}px solid ${color}`);
+    }
+    resolveTooltipArrowPosition(arrowEdge, boxX, boxY, length, halfHeight) {
+        switch (arrowEdge) {
+            case 'left':
+                return {
+                    left: boxX - length,
+                    top: boxY - halfHeight,
+                };
+            case 'right':
+                return {
+                    left: boxX,
+                    top: boxY - halfHeight,
+                };
+            case 'top':
+                return {
+                    left: boxX - halfHeight,
+                    top: boxY - length,
+                };
+            case 'bottom':
+                return {
+                    left: boxX - halfHeight,
+                    top: boxY,
+                };
+        }
     }
     resolveBarTooltipAnchor(svgNode, dataKey, index) {
         const barNode = svgNode.querySelector(`.bar-${sanitizeForCSS(dataKey)}[data-index="${index}"]`);
@@ -1050,25 +1103,21 @@ export class Tooltip {
             return null;
         }
         const boxArrowPosition = this.resolveTooltipBoxArrowPosition(arrowEdge, tooltipLeft, tooltipTop, tooltipWidth, tooltipHeight, targetX, targetY);
-        const arrow = this.resolveTooltipBoxArrow(arrowEdge, boxArrowPosition.x, boxArrowPosition.y);
-        const minX = Math.min(arrow.tipX, arrow.baseStartX, arrow.baseEndX, localTargetX) - TOOLTIP_CONNECTOR_PADDING_PX;
-        const maxX = Math.max(arrow.tipX, arrow.baseStartX, arrow.baseEndX, localTargetX) + TOOLTIP_CONNECTOR_PADDING_PX;
-        const minY = Math.min(arrow.tipY, arrow.baseStartY, arrow.baseEndY, localTargetY) - TOOLTIP_CONNECTOR_PADDING_PX;
-        const maxY = Math.max(arrow.tipY, arrow.baseStartY, arrow.baseEndY, localTargetY) + TOOLTIP_CONNECTOR_PADDING_PX;
+        const arrowTip = this.resolveTooltipArrowTip(arrowEdge, boxArrowPosition.x, boxArrowPosition.y, TOOLTIP_BOX_ARROW_LENGTH_PX);
+        const minX = Math.min(arrowTip.x, localTargetX) - TOOLTIP_CONNECTOR_PADDING_PX;
+        const maxX = Math.max(arrowTip.x, localTargetX) + TOOLTIP_CONNECTOR_PADDING_PX;
+        const minY = Math.min(arrowTip.y, localTargetY) - TOOLTIP_CONNECTOR_PADDING_PX;
+        const maxY = Math.max(arrowTip.y, localTargetY) + TOOLTIP_CONNECTOR_PADDING_PX;
         const width = Math.max(1, maxX - minX);
         const height = Math.max(1, maxY - minY);
         const boxX = boxArrowPosition.x - minX;
         const boxY = boxArrowPosition.y - minY;
-        const startX = arrow.tipX - minX;
-        const startY = arrow.tipY - minY;
-        const arrowBaseStartX = arrow.baseStartX - minX;
-        const arrowBaseStartY = arrow.baseStartY - minY;
-        const arrowBaseEndX = arrow.baseEndX - minX;
-        const arrowBaseEndY = arrow.baseEndY - minY;
+        const startX = arrowTip.x - minX;
+        const startY = arrowTip.y - minY;
         const endX = localTargetX - minX;
         const endY = localTargetY - minY;
         const connectorPath = this.resolveTooltipConnectorPath(arrowEdge, startX, startY, endX, endY);
-        if (!this.hasFiniteNumbers(width, height, boxX, boxY, startX, startY, arrowBaseStartX, arrowBaseStartY, arrowBaseEndX, arrowBaseEndY, endX, endY)) {
+        if (!this.hasFiniteNumbers(width, height, boxX, boxY, startX, startY, endX, endY)) {
             return null;
         }
         return {
@@ -1078,12 +1127,15 @@ export class Tooltip {
             width,
             height,
             path: connectorPath,
-            arrowPath: `M ${startX},${startY} L ${arrowBaseStartX},${arrowBaseStartY} L ${arrowBaseEndX},${arrowBaseEndY} Z`,
-            arrowBaseMaskPath: this.resolveTooltipArrowBaseMaskPath(arrowEdge, boxX, boxY, arrowBaseStartX, arrowBaseStartY, arrowBaseEndX, arrowBaseEndY),
-            arrowBorderPath: `M ${arrowBaseStartX},${arrowBaseStartY} L ${startX},${startY} L ${arrowBaseEndX},${arrowBaseEndY}`,
+            arrowX: boxArrowPosition.x,
+            arrowY: boxArrowPosition.y,
         };
     }
     resolveTooltipBoxArrowPosition(arrowEdge, tooltipLeft, tooltipTop, tooltipWidth, tooltipHeight, targetX, targetY) {
+        // Arrow offsets are relative to the padding box, while measured
+        // tooltip dimensions include both borders.
+        const rightInnerBorderX = tooltipWidth - TOOLTIP_TOTAL_BORDER_WIDTH_PX;
+        const bottomInnerBorderY = tooltipHeight - TOOLTIP_TOTAL_BORDER_WIDTH_PX;
         switch (arrowEdge) {
             case 'left':
                 return {
@@ -1092,7 +1144,7 @@ export class Tooltip {
                 };
             case 'right':
                 return {
-                    x: tooltipWidth,
+                    x: rightInnerBorderX,
                     y: this.getTooltipConnectorOffset(tooltipTop, tooltipHeight, targetY),
                 };
             case 'top':
@@ -1103,22 +1155,10 @@ export class Tooltip {
             case 'bottom':
                 return {
                     x: this.getTooltipConnectorOffset(tooltipLeft, tooltipWidth, targetX),
-                    y: tooltipHeight,
+                    y: bottomInnerBorderY,
                 };
         }
     }
-    resolveTooltipArrowBaseMaskPath(arrowEdge, boxX, boxY, startX, startY, endX, endY) {
-        if (arrowEdge === 'top') {
-            return `M ${startX - 1},${boxY + 1} L ${endX + 1},${boxY + 1}`;
-        }
-        if (arrowEdge === 'bottom') {
-            return `M ${startX - 1},${boxY - 1} L ${endX + 1},${boxY - 1}`;
-        }
-        if (arrowEdge === 'left') {
-            return `M ${boxX + 1},${startY - 1} L ${boxX + 1},${endY + 1}`;
-        }
-        return `M ${boxX - 1},${startY - 1} L ${boxX - 1},${endY + 1}`;
-    }
     resolveTooltipConnectorPath(arrowEdge, startX, startY, endX, endY) {
         if (arrowEdge === 'left' || arrowEdge === 'right') {
             if (Math.abs(endY - startY) <=
@@ -1134,32 +1174,16 @@ export class Tooltip {
         const elbowY = startY + (endY - startY) * TOOLTIP_CONNECTOR_ELBOW_RATIO;
         return `M ${startX},${startY} L ${startX},${elbowY} L ${endX},${endY}`;
     }
-    resolveTooltipBoxArrow(arrowEdge, boxX, boxY) {
+    resolveTooltipArrowTip(arrowEdge, boxX, boxY, length) {
         if (arrowEdge === 'left' || arrowEdge === 'right') {
-            const baseX = boxX;
-            const tipX = arrowEdge === 'left'
-                ? baseX - TOOLTIP_BOX_ARROW_LENGTH_PX
-                : baseX + TOOLTIP_BOX_ARROW_LENGTH_PX;
             return {
-                tipX,
-                tipY: boxY,
-                baseStartX: baseX,
-                baseStartY: boxY - TOOLTIP_BOX_ARROW_HALF_HEIGHT_PX,
-                baseEndX: baseX,
-                baseEndY: boxY + TOOLTIP_BOX_ARROW_HALF_HEIGHT_PX,
+                x: arrowEdge === 'left' ? boxX - length : boxX + length,
+                y: boxY,
             };
         }
-        const baseY = boxY;
-        const tipY = arrowEdge === 'top'
-            ? baseY - TOOLTIP_BOX_ARROW_LENGTH_PX
-            : baseY + TOOLTIP_BOX_ARROW_LENGTH_PX;
         return {
-            tipX: boxX,
-            tipY,
-            baseStartX: boxX - TOOLTIP_BOX_ARROW_HALF_HEIGHT_PX,
-            baseStartY: baseY,
-            baseEndX: boxX + TOOLTIP_BOX_ARROW_HALF_HEIGHT_PX,
-            baseEndY: baseY,
+            x: boxX,
+            y: arrowEdge === 'top' ? boxY - length : boxY + length,
         };
     }
     hasFiniteNumbers(...values) {

package/dist/types.d.ts

@@ -69,6 +69,9 @@ export type ChartTheme = {
         itemSpacingX: number;
         itemSpacingY: number;
     };
+    text: {
+        variants: Record<string, TextVariantStyle>;
+    };
     tooltip: {
         background: string;
         border: string;
@@ -333,13 +336,43 @@ export type LegendItem = {
     color: string;
     visible: boolean;
 };
+export type TextPosition = 'top' | 'bottom';
+export type TextAlign = 'left' | 'center' | 'right';
+export type TextVariantStyle = {
+    fontSize?: number;
+    fontWeight?: string;
+    fontFamily?: string;
+    color?: string;
+    lineHeight?: number;
+    marginTop?: number;
+    marginBottom?: number;
+};
+export type TextConfigBase = {
+    display?: boolean;
+    text: string;
+    position?: TextPosition;
+    variant?: string;
+    align?: TextAlign;
+    fontSize?: number;
+    fontWeight?: string;
+    fontFamily?: string;
+    color?: string;
+    lineHeight?: number;
+    marginTop?: number;
+    marginBottom?: number;
+};
+export type TextConfig = TextConfigBase & {
+    exportHooks?: ExportHooks<TextConfigBase>;
+};
 export type TitleConfigBase = {
     display?: boolean;
     text: string;
     fontSize?: number;
     fontWeight?: string;
     fontFamily?: string;
-    align?: 'left' | 'center' | 'right';
+    align?: TextAlign;
+    color?: string;
+    lineHeight?: number;
     marginTop?: number;
     marginBottom?: number;
 };

package/dist/xy-chart.js

@@ -263,7 +263,7 @@ export class XYChart extends BaseChart {
     setScaleConfigOverride(override, rerender = true) {
         this.scaleConfigOverride = override;
         if (rerender) {
-            this.rerender();
+            this.rerender('component');
         }
         return this;
     }

package/docs/chart-group.md

@@ -18,7 +18,7 @@ new ChartGroup(config: ChartGroupConfig)
 | `syncY`       | `boolean`                         | `false`                | Sync the Y domain across visible vertical `XYChart` children                |
 | `height`      | `number`                          | container height       | Fixed total group height. Omit it to size from the container                |
 | `chartHeight` | `number`                          | `DEFAULT_CHART_HEIGHT` | Fallback child height when neither the child nor container provides one     |
-| `theme`       | `DeepPartial<ChartTheme>`         | -                      | Theme override for the shared group legend and title                        |
+| `theme`       | `DeepPartial<ChartTheme>`         | -                      | Theme override for the shared group legend and text                         |
 | `responsive`  | `ChartGroupResponsiveConfig`      | -                      | Declarative responsive overrides for group-level `cols` and `gap`           |
 
 `ChartGroup` manages child widths. If a child chart has an explicit `width`,
@@ -32,6 +32,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 });
@@ -53,6 +54,13 @@ const group = new ChartGroup({
 
 group
     .addChild(new Title({ text: 'Revenue vs Expenses' }))
+    .addChild(
+        new Text({
+            text: 'Source: finance team',
+            position: 'bottom',
+            variant: 'caption',
+        }),
+    )
     .addChart(barChart, { span: 1 })
     .addChart(lineChart, { span: 2 })
     .addChild(new Legend());
@@ -165,13 +173,21 @@ After a breakpoint's `maxWidth`, that breakpoint stops matching. Use the base
 group config plus `minWidth` breakpoints for mobile-first layouts, or the base
 group config plus `maxWidth` breakpoints for desktop-down layouts.
 
-## Title
+## Text and Title
 
-`ChartGroup` accepts `Title` via `addChild()` and renders it above the grouped
-chart layout:
+`ChartGroup` accepts `Text` and `Title` via `addChild()`. Top text renders above
+the grouped chart layout. Bottom text renders below the grouped chart layout and
+shared legend:
 
 ```typescript
 group.addChild(new Title({ text: 'Revenue vs Expenses' }));
+group.addChild(
+    new Text({
+        text: 'Source: finance team',
+        position: 'bottom',
+        variant: 'caption',
+    }),
+);
 ```
 
 ## Legend
@@ -208,6 +224,9 @@ await group.export('pdf');
 
 - Export width can be overridden with `options.width`
 - Export height is layout-derived in v1 and cannot be overridden
-- Group titles are included in the combined export
+- Group text is included in the combined export
+- Group-level `Text` and `Title` export hooks run during visual export, so text
+  can be hidden live with `display: false` and included only in export by
+  returning `{ display: true }` from `beforeRender`
 - Child chart legends are suppressed in the combined export
 - Non-visual exports (`json`, `csv`, `xlsx`) are not supported in v1

package/docs/components.md

@@ -224,34 +224,116 @@ charts from one shared legend.
 
 ---
 
-## Title
+## Text
 
-Renders a title for the chart.
+Renders layout-aware text above or below the chart. Use it for titles,
+subtitles, captions, source notes, and other short chart copy.
 
 ```typescript
-new Title({
-    display?: boolean,      // Render title and reserve layout space (default: true)
-    text: string,            // Title text (required)
-    fontSize?: number,       // Font size in pixels (default: 18)
-    fontWeight?: string,     // Font weight (default: 'bold')
-    align?: 'left' | 'center' | 'right',  // Alignment (default: 'center')
-    marginTop?: number,      // Space above title (default: 10)
-    marginBottom?: number,   // Space below title (default: 15)
+new Text({
+    display?: boolean,       // Render text and reserve layout space (default: true)
+    text: string,             // Text content (required)
+    position?: 'top' | 'bottom', // Layout position (default: 'top')
+    variant?: string,         // Theme variant (default: 'caption')
+    align?: 'left' | 'center' | 'right', // Alignment (default: 'center')
+    fontSize?: number,        // Override variant font size
+    fontWeight?: string,      // Override variant font weight
+    fontFamily?: string,      // Override variant font family
+    color?: string,           // Override variant text color
+    lineHeight?: number,      // Override variant line height
+    marginTop?: number,       // Override variant top spacing
+    marginBottom?: number,    // Override variant bottom spacing
 })
 ```
 
 ### Example
 
 ```javascript
+import { Text } from '@internetstiftelsen/charts/text';
+
+chart
+    .addChild(
+        new Text({
+            text: 'Monthly Revenue',
+            variant: 'title',
+            align: 'left',
+        }),
+    )
+    .addChild(
+        new Text({
+            text: 'Revenue by month, SEK',
+            variant: 'subtitle',
+            align: 'left',
+        }),
+    )
+    .addChild(
+        new Text({
+            text: 'Source: Internal reporting',
+            position: 'bottom',
+            variant: 'caption',
+            align: 'left',
+        }),
+    );
+```
+
+Text variants come from `theme.text.variants`. Built-in variants are `title`,
+`subtitle`, and `caption`. Component config overrides the selected variant.
+
+```javascript
+const chart = new XYChart({
+    data,
+    theme: {
+        text: {
+            variants: {
+                source: {
+                    fontSize: 10,
+                    color: '#64748b',
+                    marginTop: 6,
+                    marginBottom: 0,
+                },
+            },
+        },
+    },
+});
+
 chart.addChild(
-    new Title({
-        text: 'Monthly Revenue',
-        align: 'left',
-        fontSize: 20,
+    new Text({
+        text: 'Source: Internetstiftelsen',
+        position: 'bottom',
+        variant: 'source',
     }),
 );
 ```
 
+## Title
+
+`Title` remains available as a compatibility shortcut for top title text:
+
+```typescript
+new Title({
+    display?: boolean,
+    text: string,
+    fontSize?: number,
+    fontWeight?: string,
+    fontFamily?: string,
+    align?: 'left' | 'center' | 'right',
+    color?: string,
+    lineHeight?: number,
+    marginTop?: number,
+    marginBottom?: number,
+})
+```
+
+It maps to the same rendering and layout behavior as:
+
+```javascript
+new Text({
+    text: 'Monthly Revenue',
+    position: 'top',
+    variant: 'title',
+});
+```
+
 ---
 
 ## Export Hooks
@@ -346,12 +428,14 @@ Components are rendered in the order they're added. A typical order:
 
 ```javascript
 chart
-    .addChild(new Title({ text: 'Chart Title' }))
+    .addChild(new Text({ text: 'Chart Title', variant: 'title' }))
+    .addChild(new Text({ text: 'Subtitle', variant: 'subtitle' }))
     .addChild(new Grid({ value: true }))
     .addChild(new XAxis({ dataKey: 'date' }))
     .addChild(new YAxis())
     .addChild(new Tooltip())
     .addChild(new Legend({ position: 'bottom' }))
+    .addChild(new Text({ text: 'Source note', position: 'bottom' }))
     .addChild(new Line({ dataKey: 'value1' }))
     .addChild(new Line({ dataKey: 'value2' }));
 ```

package/docs/donut-chart.md

@@ -176,7 +176,8 @@ new DonutCenterContent({
 DonutChart supports the following components via `addChild()`:
 
 - `DonutCenterContent` - Center text content
-- `Title` - Chart title
+- `Text` - Chart text, captions, and source notes
+- `Title` - Shortcut for top title text
 - `Legend` - Interactive legend (click to toggle segments)
 - `Tooltip` - Hover tooltips with segment info
 

package/docs/gauge-chart.md

@@ -170,6 +170,7 @@ const chart = new GaugeChart({
 
 GaugeChart supports the following components via `addChild()`:
 
-- `Title` - Chart title
+- `Text` - Chart text, captions, and source notes
+- `Title` - Shortcut for top title text
 - `Tooltip` - Hover tooltip (value, target)
 - `Legend` - Segment legend with visibility toggles

package/docs/getting-started.md

@@ -57,6 +57,30 @@ chart.update(newData);
 chart.destroy();
 ```
 
+## Lifecycle Events
+
+Charts support lifecycle listeners with `on()` and `off()`.
+
+```javascript
+const handleReady = (event) => {
+    console.log(event.reason);
+};
+
+chart.on('ready', handleReady);
+chart.off('ready', handleReady);
+```
+
+All event payloads include `type` and `chart`.
+
+| Name            | Description                                                               | Params                                                     |
+| --------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `render:start`  | A render pass is starting, before the SVG is recreated.                   | `reason`                                                   |
+| `render`        | Synchronous rendering has completed.                                      | `reason`                                                   |
+| `ready`         | The current render has fully settled, matching `chart.whenReady()`.       | `reason`                                                   |
+| `data`          | `chart.update(data)` has accepted new data, before the update render.     | `data`, `previousData`                                     |
+| `legend:change` | Legend visibility changed.                                                | -                                                          |
+| `destroy`       | The chart is being destroyed, before DOM and internal state are cleaned up. | -                                                          |
+
 ## Sizing
 
 By default, charts size themselves from the render container.
@@ -342,5 +366,5 @@ directly when laying out and rendering the cloud.
 - [DonutChart API](./donut-chart.md) - Donut/pie charts
 - [PieChart API](./pie-chart.md) - Pie charts
 - [GaugeChart API](./gauge-chart.md) - Gauge charts
-- [Components](./components.md) - Axes, Grid, Tooltip, Legend, Title
+- [Components](./components.md) - Axes, Grid, Tooltip, Legend, Text, Title
 - [Theming](./theming.md) - Customize colors and styles

package/docs/pie-chart.md

@@ -108,7 +108,8 @@ fit inside its slice is hidden. In `auto` mode, labels that are too tight (based
 
 PieChart supports the following components via `addChild()`:
 
-- `Title` - Chart title
+- `Text` - Chart text, captions, and source notes
+- `Title` - Shortcut for top title text
 - `Legend` - Interactive legend (click to toggle slices)
 - `Tooltip` - Hover/focus tooltips with slice info
 

package/docs/theming.md

@@ -111,6 +111,41 @@ const data = [
 
 ---
 
+## Text Variants
+
+`Text` uses `theme.text.variants` for reusable typography and spacing. Built-in
+variants are `title`, `subtitle`, and `caption`; add custom keys when a chart
+needs another text style.
+
+```javascript
+theme: {
+    text: {
+        variants: {
+            title: {
+                fontSize: 18,
+                fontWeight: 'bold',
+                color: '#1f2a36',
+                lineHeight: 1.2,
+                marginTop: 10,
+                marginBottom: 15,
+            },
+            source: {
+                fontSize: 10,
+                color: '#64748b',
+                lineHeight: 1.3,
+                marginTop: 6,
+                marginBottom: 0,
+            },
+        },
+    },
+}
+```
+
+Component config overrides the chosen variant, so a one-off chart can adjust
+`fontSize`, `color`, or spacing without changing the theme.
+
+---
+
 ## Donut Theme Defaults
 
 DonutChart has additional theme defaults: