chart-factory 0.1.2

package/src/core/d3-base.js

@@ -0,0 +1,249 @@
+/**
+ * Chart Factory - Shared Utilities
+ *
+ * Common utilities used across all D3 visualization components.
+ *
+ * @requires d3 v7+ (peer dependency)
+ */
+
+import * as d3 from 'd3';
+
+/**
+ * Get CSS variable value with fallback
+ * @param {string} name - CSS variable name (e.g., '--font-family')
+ * @param {string} fallback - Fallback value if variable not found
+ * @returns {string} The CSS variable value or fallback
+ */
+export function getCSSVar(name, fallback = '') {
+    const value = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+    return value || fallback;
+}
+
+/**
+ * Text measurement utility class
+ * Creates a hidden DOM element to measure text width accurately
+ */
+export class TextMeasurer {
+    constructor() {
+        this.element = null;
+    }
+
+    /**
+     * Initialize the hidden measurement element
+     * @private
+     */
+    init() {
+        if (!this.element) {
+            this.element = d3.select('body')
+                .append('div')
+                .style('position', 'absolute')
+                .style('visibility', 'hidden')
+                .style('white-space', 'nowrap')
+                .style('font-family', getCSSVar('--font-family', 'sans-serif'))
+                .style('font-size', getCSSVar('--font-size-lg', '13px'));
+        }
+        return this.element;
+    }
+
+    /**
+     * Measure the width of text
+     * @param {string} text - Text to measure
+     * @param {string} fontSize - Font size (optional)
+     * @param {string} fontWeight - Font weight (optional)
+     * @param {Object} options - Additional options
+     * @param {string} options.letterSpacing - Letter spacing
+     * @param {string} options.textTransform - Text transform (e.g., 'uppercase')
+     * @param {string} options.fontFamily - Font family override (else the
+     *     base --font-family; lets callers measure cells whose family a
+     *     theme retargets via a token, e.g. --table-primary-font)
+     * @returns {number} Width in pixels
+     */
+    measure(text, fontSize = null, fontWeight = null, options = {}) {
+        const el = this.init();
+        if (fontSize) el.style('font-size', fontSize);
+        if (fontWeight) el.style('font-weight', fontWeight);
+
+        // Reset optional styles
+        el.style('font-family', options.fontFamily || getCSSVar('--font-family', 'sans-serif'));
+        el.style('letter-spacing', options.letterSpacing || 'normal');
+        el.style('text-transform', options.textTransform || 'none');
+
+        el.text(text);
+        return el.node().getBoundingClientRect().width;
+    }
+
+    /**
+     * Clean up the measurement element
+     */
+    destroy() {
+        if (this.element) {
+            this.element.remove();
+            this.element = null;
+        }
+    }
+}
+
+/**
+ * Create a D3 sequential color scale
+ * @param {string} type - Scale type name (orange, blue, green, etc.)
+ * @param {Array} domain - [min, max] domain values
+ * @returns {Function} D3 color scale function
+ */
+export function createColorScale(type, domain) {
+    // Endpoints/stops are design tokens (themeable via --scale-* in
+    // tokens.css); the hex literals are fallbacks for token-less embeds.
+    const t = (name, fallback) => getCSSVar(name, fallback);
+    const scales = {
+        orange: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgb(t('--scale-orange-lo', '#fff5eb'), t('--scale-orange-hi', '#ff6b35'))),
+
+        orangeRed: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgb(t('--scale-orange-lo', '#fff5eb'), t('--scale-orange-red-hi', '#d7191c'))),
+
+        blue: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgb(t('--scale-blue-lo', '#e0f3f8'), t('--scale-blue-hi', '#4575b4'))),
+
+        teal: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgb(t('--scale-blue-lo', '#e0f3f8'), t('--scale-teal-hi', '#1a9988'))),
+
+        aqua: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgbBasis([
+                t('--scale-aqua-1', '#a4d7e1'), t('--scale-aqua-2', '#4ec1d4'),
+                t('--scale-aqua-3', '#0095b7'), t('--scale-aqua-4', '#005e8b')])),
+
+        grayscale: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgb(t('--scale-gray-lo', '#f5f5f5'), t('--scale-gray-hi', '#333333'))),
+
+        purple: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgbBasis([
+                t('--scale-purple-1', '#f3e5f5'), t('--scale-purple-2', '#ce93d8'),
+                t('--scale-purple-3', '#ab47bc'), t('--scale-purple-4', '#7b1fa2')])),
+
+        green: d3.scaleSequential()
+            .domain(domain)
+            .interpolator(d3.interpolateRgbBasis([
+                t('--scale-green-1', '#e8f5e9'), t('--scale-green-2', '#a5d6a7'),
+                t('--scale-green-3', '#66bb6a'), t('--scale-green-4', '#2e7d32')])),
+
+        diverging: d3.scaleDiverging()
+            .domain([domain[0], (domain[0] + domain[1]) / 2, domain[1]])
+            .interpolator(d3.interpolateRdBu)
+    };
+
+    return scales[type] || scales.orange;
+}
+
+/**
+ * Shared canvas-based text measurer. Returns a `measure(text, weight?, size?,
+ * family?)` function bound to one reused 2d context. This is THE text
+ * measurement utility — builders must not create their own canvases.
+ */
+let _measureCtx = null;
+export function createTextMeasurer(defaults = {}) {
+    if (!_measureCtx) {
+        _measureCtx = document.createElement('canvas').getContext('2d');
+    }
+    const baseFamily = defaults.family || getCSSVar('--font-family', 'system-ui, sans-serif');
+    const baseSize = defaults.size || getCSSVar('--font-size-md', '13px');
+    const baseWeight = defaults.weight || 'normal';
+    return function measure(text, weight = baseWeight, size = baseSize, family = baseFamily) {
+        _measureCtx.font = `${weight} ${size} ${family}`;
+        return _measureCtx.measureText(String(text)).width;
+    };
+}
+
+/**
+ * Calculate luminance for contrast detection
+ * @param {string} color - CSS color string
+ * @returns {number} Luminance value (0-1)
+ */
+export function getLuminance(color) {
+    const rgb = d3.rgb(color);
+    const r = rgb.r / 255;
+    const g = rgb.g / 255;
+    const b = rgb.b / 255;
+    const [rs, gs, bs] = [r, g, b].map(val =>
+        val <= 0.03928 ? val / 12.92 : Math.pow((val + 0.055) / 1.055, 2.4)
+    );
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+/**
+ * Get contrasting text color (black or white) based on background
+ * @param {string} bgColor - Background color
+ * @returns {string} '#000' or '#fff'
+ */
+export function getContrastColor(bgColor) {
+    return getLuminance(bgColor) > 0.5 ? '#000' : '#fff';
+}
+
+/**
+ * Format a numeric value based on format type
+ * @param {*} value - Value to format
+ * @param {string} format - Format type (decimal, decimal2, percentage, currency, integer)
+ * @returns {string} Formatted value
+ */
+export function formatValue(value, format) {
+    if (value === null || value === undefined) return '';
+
+    switch (format) {
+        case 'decimal':
+            const num = parseFloat(value);
+            return isNaN(num) ? '0.0' : num.toFixed(1);
+        case 'decimal2':
+            const num2 = parseFloat(value);
+            return isNaN(num2) ? '0.00' : num2.toFixed(2);
+        case 'percentage':
+            return `${value}%`;
+        case 'currency':
+            return `$${parseFloat(value).toLocaleString()}`;
+        case 'integer':
+            return parseInt(value).toLocaleString();
+        default:
+            return value;
+    }
+}
+
+/**
+ * Apply staggered entrance animation to a D3 selection
+ * @param {d3.Selection} selection - D3 selection to animate
+ * @param {number} duration - Animation duration in ms
+ * @param {number} staggerDelay - Delay between each element in ms
+ * @param {Object} fromStyles - Starting styles
+ * @param {Object} toStyles - Ending styles
+ */
+export function staggeredEntrance(selection, duration, staggerDelay, fromStyles, toStyles) {
+    // Apply initial styles
+    Object.entries(fromStyles).forEach(([key, value]) => {
+        selection.style(key, value);
+    });
+
+    // Animate to final styles
+    selection.transition()
+        .delay((d, i) => i * staggerDelay)
+        .duration(duration)
+        .ease(d3.easeCubicOut)
+        .call(transition => {
+            Object.entries(toStyles).forEach(([key, value]) => {
+                transition.style(key, value);
+            });
+        });
+}
+
+// Default export with all utilities
+export default {
+    getCSSVar,
+    TextMeasurer,
+    createColorScale,
+    getLuminance,
+    getContrastColor,
+    formatValue,
+    staggeredEntrance
+};