@internetstiftelsen/charts 0.12.0 → 0.13.0

package/dist/text.d.ts

@@ -0,0 +1,40 @@
+import { type Selection } from 'd3';
+import type { ChartTheme, ExportHooks, TextAlign, TextConfig, TextConfigBase, TextPosition } from './types.js';
+import type { ComponentSpace, LayoutAwareComponent } from './chart-interface.js';
+type TextComponentType = 'text' | 'title';
+type ResolvedTextStyle = {
+    fontSize: number;
+    fontWeight: string;
+    fontFamily: string;
+    color: string;
+    lineHeight: number;
+    marginTop: number;
+    marginBottom: number;
+};
+export declare class Text implements LayoutAwareComponent<TextConfigBase> {
+    readonly type: TextComponentType;
+    readonly display: boolean;
+    readonly text: string;
+    readonly position: TextPosition;
+    readonly variant: string;
+    readonly align: TextAlign;
+    readonly exportHooks?: ExportHooks<TextConfigBase>;
+    protected readonly fontSize?: number;
+    protected readonly fontWeight?: string;
+    protected readonly fontFamily?: string;
+    protected readonly color?: string;
+    protected readonly lineHeight?: number;
+    protected readonly marginTop?: number;
+    protected readonly marginBottom?: number;
+    constructor(config: TextConfig, componentType?: TextComponentType);
+    getExportConfig(): TextConfigBase;
+    createExportComponent(override?: Partial<TextConfigBase>): LayoutAwareComponent<TextConfigBase>;
+    getRequiredSpace(theme?: ChartTheme): ComponentSpace;
+    render(svg: Selection<SVGSVGElement, undefined, null, undefined>, theme: ChartTheme, width: number, x?: number, y?: number): void;
+    protected resolveStyle(theme?: ChartTheme): ResolvedTextStyle;
+    private resolveStyleValue;
+    private getLines;
+    private resolveTextPosition;
+    private resolveClassName;
+}
+export {};

package/dist/text.js

@@ -0,0 +1,217 @@
+import { mergeDeep, sanitizeForCSS } from './utils.js';
+export class Text {
+    constructor(config, componentType = 'text') {
+        Object.defineProperty(this, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "display", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "text", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "position", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "variant", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "align", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "exportHooks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fontSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fontWeight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fontFamily", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "color", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "lineHeight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "marginTop", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "marginBottom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.type = componentType;
+        this.display = config.display ?? true;
+        this.text = config.text;
+        this.position = config.position ?? 'top';
+        this.variant = config.variant ?? 'caption';
+        this.align = config.align ?? 'center';
+        this.fontSize = config.fontSize;
+        this.fontWeight = config.fontWeight;
+        this.fontFamily = config.fontFamily;
+        this.color = config.color;
+        this.lineHeight = config.lineHeight;
+        this.marginTop = config.marginTop;
+        this.marginBottom = config.marginBottom;
+        this.exportHooks = config.exportHooks;
+    }
+    getExportConfig() {
+        return {
+            display: this.display,
+            text: this.text,
+            position: this.position,
+            variant: this.variant,
+            align: this.align,
+            fontSize: this.fontSize,
+            fontWeight: this.fontWeight,
+            fontFamily: this.fontFamily,
+            color: this.color,
+            lineHeight: this.lineHeight,
+            marginTop: this.marginTop,
+            marginBottom: this.marginBottom,
+        };
+    }
+    createExportComponent(override) {
+        const merged = mergeDeep(this.getExportConfig(), override);
+        return new Text({
+            ...merged,
+            exportHooks: this.exportHooks,
+        }, this.type);
+    }
+    getRequiredSpace(theme) {
+        if (!this.display) {
+            return {
+                width: 0,
+                height: 0,
+                position: this.position,
+            };
+        }
+        const style = this.resolveStyle(theme);
+        const lineCount = this.getLines().length;
+        const textHeight = style.fontSize +
+            Math.max(0, lineCount - 1) * style.fontSize * style.lineHeight;
+        return {
+            width: 0,
+            height: style.marginTop + textHeight + style.marginBottom,
+            position: this.position,
+        };
+    }
+    render(svg, theme, width, x = 0, y = 0) {
+        if (!this.display) {
+            return;
+        }
+        const style = this.resolveStyle(theme);
+        const { textX, textAnchor } = this.resolveTextPosition(theme, width);
+        const textGroup = svg
+            .append('g')
+            .attr('class', this.resolveClassName())
+            .attr('transform', `translate(${x}, ${y})`);
+        const text = textGroup
+            .append('text')
+            .attr('x', textX)
+            .attr('text-anchor', textAnchor)
+            .attr('font-size', `${style.fontSize}px`)
+            .attr('font-weight', style.fontWeight)
+            .attr('font-family', style.fontFamily)
+            .attr('fill', style.color);
+        this.getLines().forEach((line, index) => {
+            const tspan = text.append('tspan').attr('x', textX).text(line);
+            if (index === 0) {
+                tspan.attr('y', style.marginTop + style.fontSize);
+                return;
+            }
+            tspan.attr('dy', `${style.lineHeight}em`);
+        });
+    }
+    resolveStyle(theme) {
+        const variant = theme?.text.variants[this.variant] ?? {};
+        return {
+            fontSize: this.resolveStyleValue(this.fontSize, variant.fontSize, 12),
+            fontWeight: this.resolveStyleValue(this.fontWeight, variant.fontWeight, 'normal'),
+            fontFamily: this.fontFamily ??
+                variant.fontFamily ??
+                theme?.fontFamily ??
+                '',
+            color: this.resolveStyleValue(this.color, variant.color, '#1f2a36'),
+            lineHeight: this.resolveStyleValue(this.lineHeight, variant.lineHeight, 1.2),
+            marginTop: this.resolveStyleValue(this.marginTop, variant.marginTop, 0),
+            marginBottom: this.resolveStyleValue(this.marginBottom, variant.marginBottom, 0),
+        };
+    }
+    resolveStyleValue(configured, variant, fallback) {
+        return configured ?? variant ?? fallback;
+    }
+    getLines() {
+        return this.text.split('\n');
+    }
+    resolveTextPosition(theme, width) {
+        if (this.align === 'left') {
+            return {
+                textX: theme.margins.left,
+                textAnchor: 'start',
+            };
+        }
+        if (this.align === 'right') {
+            return {
+                textX: width - theme.margins.right,
+                textAnchor: 'end',
+            };
+        }
+        return {
+            textX: width / 2,
+            textAnchor: 'middle',
+        };
+    }
+    resolveClassName() {
+        const classes = ['text', `text--${sanitizeForCSS(this.variant)}`];
+        if (this.type === 'title') {
+            classes.unshift('title');
+        }
+        return classes.join(' ');
+    }
+}

package/dist/theme.js

@@ -40,6 +40,34 @@ export const defaultTheme = {
         itemSpacingX: 20,
         itemSpacingY: 8,
     },
+    text: {
+        variants: {
+            title: {
+                fontSize: 18,
+                fontWeight: 'bold',
+                color: '#1f2a36',
+                lineHeight: 1.2,
+                marginTop: 10,
+                marginBottom: 15,
+            },
+            subtitle: {
+                fontSize: 14,
+                fontWeight: 'normal',
+                color: '#4b5563',
+                lineHeight: 1.35,
+                marginTop: 0,
+                marginBottom: 12,
+            },
+            caption: {
+                fontSize: 12,
+                fontWeight: 'normal',
+                color: '#6b7280',
+                lineHeight: 1.3,
+                marginTop: 8,
+                marginBottom: 0,
+            },
+        },
+    },
     tooltip: {
         background: '#ffffff',
         border: '#dddddd',
@@ -128,6 +156,34 @@ export const newspaperTheme = {
         itemSpacingX: 20,
         itemSpacingY: 8,
     },
+    text: {
+        variants: {
+            title: {
+                fontSize: 18,
+                fontWeight: 'bold',
+                color: '#1a1a1a',
+                lineHeight: 1.2,
+                marginTop: 10,
+                marginBottom: 15,
+            },
+            subtitle: {
+                fontSize: 14,
+                fontWeight: 'normal',
+                color: '#4a4a4a',
+                lineHeight: 1.35,
+                marginTop: 0,
+                marginBottom: 12,
+            },
+            caption: {
+                fontSize: 12,
+                fontWeight: 'normal',
+                color: '#6b6b6b',
+                lineHeight: 1.3,
+                marginTop: 8,
+                marginBottom: 0,
+            },
+        },
+    },
     tooltip: {
         background: '#111111',
         border: '#111111',

package/dist/title.d.ts

@@ -1,23 +1,17 @@
 import { type Selection } from 'd3';
-import type { TitleConfig, ChartTheme, ExportHooks, TitleConfigBase } from './types.js';
-import type { LayoutAwareComponent, ComponentSpace } from './chart-interface.js';
+import type { ChartTheme, ExportHooks, TitleConfig, TitleConfigBase } from './types.js';
+import type { ComponentSpace, LayoutAwareComponent } from './chart-interface.js';
 export declare class Title implements LayoutAwareComponent<TitleConfigBase> {
     readonly type: "title";
     readonly display: boolean;
     readonly text: string;
+    readonly position: "top";
+    readonly variant = "title";
     readonly exportHooks?: ExportHooks<TitleConfigBase>;
-    private readonly fontSize;
-    private readonly fontWeight;
-    private readonly fontFamily?;
-    private readonly align;
-    private readonly marginTop;
-    private readonly marginBottom;
+    private readonly textComponent;
     constructor(config: TitleConfig);
     getExportConfig(): TitleConfigBase;
     createExportComponent(override?: Partial<TitleConfigBase>): LayoutAwareComponent<TitleConfigBase>;
-    /**
-     * Returns the space required by the title
-     */
-    getRequiredSpace(): ComponentSpace;
+    getRequiredSpace(theme?: ChartTheme): ComponentSpace;
     render(svg: Selection<SVGSVGElement, undefined, null, undefined>, theme: ChartTheme, width: number, x?: number, y?: number): void;
 }

package/dist/title.js

@@ -1,3 +1,4 @@
+import { Text } from './text.js';
 import { mergeDeep } from './utils.js';
 export class Title {
     constructor(config) {
@@ -19,68 +20,53 @@ export class Title {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "exportHooks", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "fontSize", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "fontWeight", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "fontFamily", {
+        Object.defineProperty(this, "position", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
+            value: 'top'
         });
-        Object.defineProperty(this, "align", {
+        Object.defineProperty(this, "variant", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
+            value: 'title'
         });
-        Object.defineProperty(this, "marginTop", {
+        Object.defineProperty(this, "exportHooks", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "marginBottom", {
+        Object.defineProperty(this, "textComponent", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        this.display = config.display ?? true;
-        this.text = config.text;
-        this.fontSize = config.fontSize ?? 18;
-        this.fontWeight = config.fontWeight ?? 'bold';
-        this.fontFamily = config.fontFamily;
-        this.align = config.align ?? 'center';
-        this.marginTop = config.marginTop ?? 10;
-        this.marginBottom = config.marginBottom ?? 15;
+        this.textComponent = new Text({
+            ...config,
+            position: 'top',
+            variant: 'title',
+            exportHooks: config.exportHooks,
+        }, 'title');
+        this.display = this.textComponent.display;
+        this.text = this.textComponent.text;
         this.exportHooks = config.exportHooks;
     }
     getExportConfig() {
+        const config = this.textComponent.getExportConfig();
         return {
-            display: this.display,
-            text: this.text,
-            fontSize: this.fontSize,
-            fontWeight: this.fontWeight,
-            fontFamily: this.fontFamily,
-            align: this.align,
-            marginTop: this.marginTop,
-            marginBottom: this.marginBottom,
+            display: config.display,
+            text: config.text,
+            fontSize: config.fontSize,
+            fontWeight: config.fontWeight,
+            fontFamily: config.fontFamily,
+            align: config.align,
+            color: config.color,
+            lineHeight: config.lineHeight,
+            marginTop: config.marginTop,
+            marginBottom: config.marginBottom,
         };
     }
     createExportComponent(override) {
@@ -90,49 +76,10 @@ export class Title {
             exportHooks: this.exportHooks,
         });
     }
-    /**
-     * Returns the space required by the title
-     */
-    getRequiredSpace() {
-        if (!this.display) {
-            return {
-                width: 0,
-                height: 0,
-                position: 'top',
-            };
-        }
-        return {
-            width: 0, // Title spans full width
-            height: this.marginTop + this.fontSize + this.marginBottom,
-            position: 'top',
-        };
+    getRequiredSpace(theme) {
+        return this.textComponent.getRequiredSpace(theme);
     }
     render(svg, theme, width, x = 0, y = 0) {
-        if (!this.display) {
-            return;
-        }
-        const titleGroup = svg
-            .append('g')
-            .attr('class', 'title')
-            .attr('transform', `translate(${x}, ${y})`);
-        let textX = width / 2;
-        let textAnchor = 'middle';
-        if (this.align === 'left') {
-            textX = theme.margins.left;
-            textAnchor = 'start';
-        }
-        else if (this.align === 'right') {
-            textX = width - theme.margins.right;
-            textAnchor = 'end';
-        }
-        titleGroup
-            .append('text')
-            .attr('x', textX)
-            .attr('y', this.marginTop + this.fontSize)
-            .attr('text-anchor', textAnchor)
-            .attr('font-size', `${this.fontSize}px`)
-            .attr('font-weight', this.fontWeight)
-            .attr('font-family', this.fontFamily || theme.fontFamily)
-            .text(this.text);
+        this.textComponent.render(svg, theme, width, x, y);
     }
 }

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/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