layerchart 2.0.0-next.9 → 2.0.0

package/dist/components/Text/Text.shared.svelte.d.ts

@@ -0,0 +1,270 @@
+import type { SVGAttributes } from 'svelte/elements';
+import type { Without } from '../../utils/types.js';
+import type { DataDrivenStyleProps } from '../../utils/dataProp.js';
+import { type MotionProp } from '../../utils/motion.svelte.js';
+import { type FormatType, type FormatConfig } from '@layerstack/utils';
+import { type TruncateTextOptions } from '../../utils/string.js';
+import type { ChartState } from '../../states/chart.svelte.js';
+import type { GeoState } from '../../states/geo.svelte.js';
+/**
+ * Check if a Text prop value is a data-space prop.
+ * Functions are always data props.
+ * Strings are data props unless they look like CSS values (e.g. "50%", "1em").
+ */
+export declare function isTextDataProp(value: any): boolean;
+export type TextSegment = {
+    value: string | number;
+    class?: string;
+};
+export type TextPropsWithoutHTML = {
+    /**
+     * Text value to render.
+     * - `number`: direct value
+     * - `string`: in data mode, treated as a data property name (e.g. `"label"` → `d.label`);
+     *   in pixel mode, used as literal text
+     * - `function(d)`: accessor called per data item to get the text value
+     *
+     * @default 0
+     */
+    value?: string | number | ((d: any) => string | number);
+    /**
+     * Array of styled text segments for inline mixed styling.
+     * Each segment has its own value and optional class.
+     * Mutually exclusive with `value`.
+     */
+    segments?: TextSegment[];
+    /**
+     * Maximum width to occupy (approximate as words are not split)
+     */
+    width?: number;
+    /**
+     * x position of the text.
+     * - `number`: pixel value (direct)
+     * - `string` (CSS value like "50%"): SVG position value
+     * - `string` (property name like "date"): data property, resolved via xScale
+     * - `function(d)`: accessor called per data item, result passed through xScale
+     *
+     * @default 0
+     */
+    x?: string | number | ((d: any) => any);
+    /**
+     * Initial x position of the text (pixel mode only).
+     *
+     * @default x
+     */
+    initialX?: string | number;
+    /**
+     * y position of the text.
+     * - `number`: pixel value (direct)
+     * - `string` (CSS value like "50%"): SVG position value
+     * - `string` (property name like "value"): data property, resolved via yScale
+     * - `function(d)`: accessor called per data item, result passed through yScale
+     *
+     * @default 0
+     */
+    y?: string | number | ((d: any) => any);
+    /**
+     * Initial y position of the text (pixel mode only).
+     *
+     * @default y
+     */
+    initialY?: string | number;
+    /**
+     * dx offset of the text
+     *
+     * @default 0
+     */
+    dx?: string | number;
+    /**
+     * dy offset of the text
+     *
+     * @default 0
+     */
+    dy?: string | number;
+    /**
+     * Desired "line height" of the text, implemented as y offsets
+     *
+     * @default "1em"
+     */
+    lineHeight?: string;
+    /**
+     * Font size of the text. A number is treated as pixels; a string passes
+     * through (e.g. `'12px'`, `'1.25em'`). When set, vertical centering math
+     * derives `capHeight` from this value automatically (as `fontSize * 0.71`),
+     * so per-item scaled labels with `verticalAnchor="middle"` align correctly
+     * without an explicit `capHeight` override.
+     */
+    fontSize?: number | string;
+    /**
+     * Cap height of the text — used by vertical anchor math to align the text
+     * to its visual center (as opposed to the font box). Defaults to `0.71em`,
+     * but if `fontSize` is set, defaults to `fontSize * 0.71` so centering
+     * stays correct as text scales.
+     *
+     * @default '0.71em' (or `fontSize * 0.71` when `fontSize` is set)
+     */
+    capHeight?: string;
+    /**
+     * Whether to scale the fontSize to accommodate the specified width
+     *
+     * @default false
+     */
+    scaleToFit?: boolean;
+    /**
+     * Horizontal text anchor
+     *
+     * @default 'start'
+     */
+    textAnchor?: 'start' | 'middle' | 'end' | 'inherit';
+    /**
+     * Vertical text anchor
+     *
+     * @default 'end'
+     */
+    verticalAnchor?: 'start' | 'middle' | 'end' | 'inherit';
+    /**
+     * The dominant baseline of the text.  Useful for aligning text to the baseline of the axis.
+     *
+     * @default 'auto'
+     */
+    dominantBaseline?: 'auto' | 'text-before-edge' | 'text-after-edge' | 'middle' | 'hanging' | 'ideographic' | 'mathematical';
+    /**
+     * Rotational angle of the text
+     */
+    rotate?: number;
+    /**
+     * A bindable reference to the wrapping `<svg>` element.
+     *
+     * @bindable
+     */
+    svgRef?: SVGElement;
+    /**
+     * Props to pass to the wrapping `<svg>` element.
+     */
+    svgProps?: Omit<SVGAttributes<SVGElement>, 'children'>;
+    /**
+     * A bindable reference to the inner `<text>` element
+     *
+     * @bindable
+     */
+    ref?: SVGTextElement;
+    /**
+     * Format the displayed value. When set with `motion` and a numeric `value`,
+     * the number will tween smoothly and be formatted for display.
+     */
+    format?: FormatType | FormatConfig;
+    /** Motion configuration (pixel mode only). */
+    motion?: MotionProp;
+    /**
+     * Whether to enable text truncation
+     */
+    truncate?: boolean | TruncateTextOptions;
+    /**
+     * A unique identifier for the SVG path element.
+     * One is generated by default if not provided.
+     *
+     */
+    pathId?: string;
+    /**
+     * The path to render the text along.
+     */
+    path?: string | null;
+    /**
+     * Specify the offset for the start of the text along the path.
+     * Can be a percentage ('50%') or a length value.
+     *
+     * @default '0%'
+     */
+    startOffset?: string | number;
+    /**
+     * Data array to iterate over in data mode.
+     * Falls back to chart context data when not provided.
+     */
+    data?: any[];
+    /**
+     * Key function for keyed {#each} rendering in data mode.
+     *
+     * @default (d, i) => i
+     */
+    key?: (d: any, index: number) => any;
+} & DataDrivenStyleProps;
+export type TextProps = TextPropsWithoutHTML & Without<SVGAttributes<SVGTextElement>, TextPropsWithoutHTML>;
+export declare function getPathLength(pathRef: SVGPathElement | undefined): number;
+/**
+ * Convert css value to pixel value (ex. 0.71em => 11.36)
+ */
+export declare function getPixelValue(cssValue: number | string): number;
+/**
+ * Resolve the cap-height used by vertical-anchor math.
+ *
+ * Priority:
+ *   1. Explicit `capHeight` prop
+ *   2. `fontSize * 0.71` when `fontSize` is set (keeps centering correct as
+ *      labels scale per-item)
+ *   3. `'0.71em'` (legacy default — only correct for ~16px text since
+ *      `getPixelValue` resolves `em` against 16, not the actual font-size)
+ */
+export declare function resolveCapHeight(capHeight: string | undefined, fontSize: number | string | undefined): number | string;
+export declare function isValidXOrY(xOrY: string | number | undefined): boolean;
+/** Build the standard `markInfo` payload used by every Text variant. */
+export declare function textMarkInfo(props: TextProps, dataMode: boolean): {
+    data?: undefined;
+    x?: undefined;
+    y?: undefined;
+    color?: undefined;
+} | {
+    data: any[] | undefined;
+    x: string | undefined;
+    y: string | undefined;
+    color: string | undefined;
+};
+/**
+ * Reactive state shared by every per-layer Text variant. Instantiate from
+ * each `Text.svg.svelte` / `Text.canvas.svelte` / `Text.html.svelte`
+ * component setup, passing a getter for the props.
+ *
+ * Per-layer specific bits (SVG `bind:this` refs, canvas's `render` function,
+ * canvas-specific style measurement) stay in their respective `.svelte` files.
+ */
+export declare class TextState {
+    #private;
+    chartCtx: ChartState;
+    geo: GeoState;
+    pathRef: SVGPathElement | undefined;
+    dataMode: boolean;
+    resolvedItems: {
+        d: any;
+        key: any;
+        x: number;
+        y: number;
+    }[];
+    resolveTextPosition(d: any): {
+        x: number;
+        y: number;
+    };
+    resolveTextValue(d: any): string;
+    get motionX(): any;
+    get motionY(): any;
+    resolvedWidth: number | undefined;
+    truncateConfig: TruncateTextOptions | boolean;
+    rawText: string;
+    textValue: string;
+    wordsByLines: {
+        words: string[];
+        width?: number;
+    }[];
+    lineCount: number;
+    startDy: number;
+    dataModeStartDy: number;
+    scaleTransform: string;
+    rotateTransform: string;
+    transform: string;
+    staticFill: string | undefined;
+    staticFillOpacity: number | undefined;
+    staticStroke: string | undefined;
+    staticStrokeWidth: number | undefined;
+    staticOpacity: number | undefined;
+    staticClassName: string | undefined;
+    constructor(getProps: () => TextProps);
+}
+export type { TruncateTextOptions } from '../../utils/string.js';

package/dist/components/Text/Text.shared.svelte.js

@@ -0,0 +1,350 @@
+import { untrack } from 'svelte';
+import { resolveDataProp, resolveGeoDataPair, } from '../../utils/dataProp.js';
+import { chartDataArray } from '../../utils/common.js';
+import { createMotion, createDataMotionMap } from '../../utils/motion.svelte.js';
+import { get } from '@layerstack/utils';
+import { format as formatValue } from '@layerstack/utils';
+import { getStringWidth, truncateText } from '../../utils/string.js';
+import { getChartContext } from '../../contexts/chart.js';
+import { getGeoContext } from '../../contexts/geo.js';
+/**
+ * Check if a string looks like a CSS/SVG value (percentage, em, px, etc.)
+ * rather than a data property accessor.
+ */
+function isCSSValue(value) {
+    return /^-?[\d.]+(%|em|rem|px|pt|cm|mm|in)?$/.test(value);
+}
+/**
+ * Check if a Text prop value is a data-space prop.
+ * Functions are always data props.
+ * Strings are data props unless they look like CSS values (e.g. "50%", "1em").
+ */
+export function isTextDataProp(value) {
+    if (typeof value === 'function')
+        return true;
+    if (typeof value === 'string' && !isCSSValue(value))
+        return true;
+    return false;
+}
+const defaultKey = (_, i) => i;
+export function getPathLength(pathRef) {
+    if (pathRef && typeof pathRef.getTotalLength === 'function') {
+        try {
+            return pathRef.getTotalLength();
+        }
+        catch (e) {
+            console.error('Error getting path length:', e);
+            return 0;
+        }
+    }
+    return 0;
+}
+/**
+ * Convert css value to pixel value (ex. 0.71em => 11.36)
+ */
+export function getPixelValue(cssValue) {
+    // TODO: Properly measure pixel values using DOM (handle inherited font size, zoom, etc)
+    if (typeof cssValue === 'number')
+        return cssValue;
+    const result = cssValue.match(/([\d.]+)(\D+)/);
+    const number = Number(result?.[1]);
+    switch (result?.[2]) {
+        case 'px':
+            return number;
+        case 'em':
+        case 'rem':
+            return number * 16;
+        default:
+            return 0;
+    }
+}
+/**
+ * Resolve the cap-height used by vertical-anchor math.
+ *
+ * Priority:
+ *   1. Explicit `capHeight` prop
+ *   2. `fontSize * 0.71` when `fontSize` is set (keeps centering correct as
+ *      labels scale per-item)
+ *   3. `'0.71em'` (legacy default — only correct for ~16px text since
+ *      `getPixelValue` resolves `em` against 16, not the actual font-size)
+ */
+export function resolveCapHeight(capHeight, fontSize) {
+    if (capHeight != null)
+        return capHeight;
+    if (fontSize != null)
+        return getPixelValue(fontSize) * 0.71;
+    return '0.71em';
+}
+export function isValidXOrY(xOrY) {
+    return ((typeof xOrY === 'number' && Number.isFinite(xOrY)) ||
+        typeof xOrY === 'string');
+}
+/** Build the standard `markInfo` payload used by every Text variant. */
+export function textMarkInfo(props, dataMode) {
+    if (!dataMode)
+        return {};
+    return {
+        data: props.data,
+        x: typeof props.x === 'string' ? props.x : undefined,
+        y: typeof props.y === 'string' ? props.y : undefined,
+        color: typeof props.fill === 'string' ? props.fill : undefined,
+    };
+}
+/**
+ * Reactive state shared by every per-layer Text variant. Instantiate from
+ * each `Text.svg.svelte` / `Text.canvas.svelte` / `Text.html.svelte`
+ * component setup, passing a getter for the props.
+ *
+ * Per-layer specific bits (SVG `bind:this` refs, canvas's `render` function,
+ * canvas-specific style measurement) stay in their respective `.svelte` files.
+ */
+export class TextState {
+    #getProps = () => ({});
+    // Contexts
+    chartCtx = getChartContext();
+    geo = getGeoContext();
+    // Path measurement (only meaningful for SVG layer where the textPath element exists)
+    pathRef = $state();
+    // Data mode detection
+    dataMode = $derived(this.#getProps().data != null ||
+        isTextDataProp(this.#getProps().x) ||
+        isTextDataProp(this.#getProps().y));
+    // Data resolution
+    #resolvedData = $derived(this.dataMode ? (this.#getProps().data ?? chartDataArray(this.chartCtx.data)) : []);
+    resolvedItems = $derived.by(() => {
+        if (!this.dataMode)
+            return [];
+        const props = this.#getProps();
+        const keyFn = props.key ?? defaultKey;
+        return this.#resolvedData.map((d, i) => {
+            const key = keyFn(d, i);
+            const resolved = this.resolveTextPosition(d);
+            const animated = this.#dataMotionMap?.get(key);
+            return {
+                d,
+                key,
+                x: animated?.x ?? resolved.x,
+                y: animated?.y ?? resolved.y,
+            };
+        });
+    });
+    resolveTextPosition(d) {
+        const props = this.#getProps();
+        if (this.geo.projection) {
+            const [projX, projY] = resolveGeoDataPair(props.x, props.y, d, this.geo.projection);
+            return { x: projX, y: projY };
+        }
+        // When x/y are omitted, fall back to the chart's accessors (xGet/yGet) —
+        // mirroring the Circle / Points / Dodge pattern.
+        const xDefault = typeof props.x === 'number'
+            ? props.x
+            : props.x == null && this.chartCtx.config.x != null
+                ? Number(this.chartCtx.xGet(d)) || 0
+                : 0;
+        const yDefault = typeof props.y === 'number'
+            ? props.y
+            : props.y == null && this.chartCtx.config.y != null
+                ? Number(this.chartCtx.yGet(d)) || 0
+                : 0;
+        return {
+            x: resolveDataProp(props.x, d, this.chartCtx.xScale, xDefault),
+            y: resolveDataProp(props.y, d, this.chartCtx.yScale, yDefault),
+        };
+    }
+    resolveTextValue(d) {
+        const value = this.#getProps().value;
+        if (typeof value === 'function') {
+            const v = value(d);
+            return v != null ? String(v) : '';
+        }
+        if (typeof value === 'string') {
+            const v = get(d, value);
+            return v != null ? String(v) : '';
+        }
+        return value != null ? String(value) : '';
+    }
+    #dataMotionMap = null;
+    // Pixel-mode motion sources
+    #motionX;
+    #motionY;
+    #motionValue;
+    get motionX() {
+        return this.#motionX.current;
+    }
+    get motionY() {
+        return this.#motionY.current;
+    }
+    // Resolved width: for path text, defer to the (SVG-bound) pathRef length
+    resolvedWidth = $derived(this.#getProps().path ? getPathLength(this.pathRef) : this.#getProps().width);
+    #defaultTruncateOptions = $derived({
+        maxChars: undefined,
+        position: 'end',
+        maxWidth: this.resolvedWidth,
+    });
+    truncateConfig = $derived.by(() => {
+        const truncate = this.#getProps().truncate;
+        if (typeof truncate === 'boolean') {
+            if (truncate)
+                return this.#defaultTruncateOptions;
+            return false;
+        }
+        return { ...this.#defaultTruncateOptions, ...(truncate ?? {}) };
+    });
+    // Numeric value tweening
+    rawText = $derived.by(() => {
+        const value = this.#getProps().value;
+        const motion = this.#getProps().motion;
+        const format = this.#getProps().format;
+        if (typeof value === 'function' || value == null)
+            return '';
+        if (typeof value === 'number' && motion) {
+            const v = this.#motionValue.current;
+            // @ts-expect-error - improve format types
+            return format ? formatValue(v, format) : String(v);
+        }
+        // @ts-expect-error - improve format types
+        const text = format ? formatValue(value, format) : value.toString();
+        return text.replace(/\\n/g, '\n');
+    });
+    textValue = $derived.by(() => {
+        const cfg = this.truncateConfig;
+        if (!cfg || cfg === true)
+            return this.rawText;
+        return truncateText(this.rawText, cfg);
+    });
+    // Word-wrapping (depends on style measurement; SVG/canvas-only)
+    // Note: `style` is a placeholder — never assigned in the original component
+    // either, so spaceWidth always falls back to 0. Preserved for behavior parity.
+    #spaceWidth = $derived(getStringWidth(' ', undefined) || 0);
+    wordsByLines = $derived.by(() => {
+        const props = this.#getProps();
+        const width = props.width;
+        const scaleToFit = props.scaleToFit ?? false;
+        const lines = this.textValue.split('\n');
+        return lines.flatMap((line) => {
+            const words = line.split(/(?:(?! +)\s+)/);
+            if (width == null) {
+                return [{ words }];
+            }
+            return words.reduce((result, item) => {
+                const currentLine = result[result.length - 1];
+                const itemWidth = getStringWidth(item, undefined) || 0;
+                if (currentLine &&
+                    (width == null ||
+                        scaleToFit ||
+                        (currentLine.width || 0) + itemWidth + this.#spaceWidth < width)) {
+                    currentLine.words.push(item);
+                    currentLine.width = currentLine.width || 0;
+                    currentLine.width += itemWidth + this.#spaceWidth;
+                }
+                else {
+                    const newLine = { words: [item], width: itemWidth };
+                    result.push(newLine);
+                }
+                return result;
+            }, []);
+        });
+    });
+    lineCount = $derived(this.wordsByLines.length);
+    // Vertical positioning
+    startDy = $derived.by(() => {
+        const props = this.#getProps();
+        const verticalAnchor = props.verticalAnchor ?? 'end';
+        const lineHeight = props.lineHeight ?? '1em';
+        const capHeight = resolveCapHeight(props.capHeight, props.fontSize);
+        if (verticalAnchor === 'start') {
+            return getPixelValue(lineHeight);
+        }
+        else if (verticalAnchor === 'middle') {
+            return ((this.lineCount - 1) / 2) * -getPixelValue(lineHeight) + getPixelValue(capHeight) / 2;
+        }
+        return (this.lineCount - 1) * -getPixelValue(lineHeight) - getPixelValue(capHeight) / 2;
+    });
+    dataModeStartDy = $derived.by(() => {
+        const props = this.#getProps();
+        const verticalAnchor = props.verticalAnchor ?? 'end';
+        const lineHeight = props.lineHeight ?? '1em';
+        const capHeight = resolveCapHeight(props.capHeight, props.fontSize);
+        if (verticalAnchor === 'start')
+            return getPixelValue(lineHeight);
+        if (verticalAnchor === 'middle')
+            return getPixelValue(capHeight) / 2;
+        return -getPixelValue(capHeight) / 2;
+    });
+    scaleTransform = $derived.by(() => {
+        const props = this.#getProps();
+        const x = props.x;
+        const y = props.y;
+        const width = props.width;
+        const scaleToFit = props.scaleToFit ?? false;
+        if (scaleToFit &&
+            this.lineCount > 0 &&
+            typeof x === 'number' &&
+            typeof y === 'number' &&
+            typeof width === 'number') {
+            const lineWidth = this.wordsByLines[0].width || 1;
+            const sx = width / lineWidth;
+            const sy = sx;
+            const originX = x - sx * x;
+            const originY = y - sy * y;
+            return `matrix(${sx}, 0, 0, ${sy}, ${originX}, ${originY})`;
+        }
+        return '';
+    });
+    rotateTransform = $derived.by(() => {
+        const props = this.#getProps();
+        return props.rotate ? `rotate(${props.rotate}, ${props.x}, ${props.y})` : '';
+    });
+    transform = $derived(this.#getProps().transform ??
+        `${this.scaleTransform} ${this.rotateTransform}`);
+    // Static (non-data-driven) values
+    staticFill = $derived(typeof this.#getProps().fill === 'string' ? this.#getProps().fill : undefined);
+    staticFillOpacity = $derived(typeof this.#getProps().fillOpacity === 'number'
+        ? this.#getProps().fillOpacity
+        : undefined);
+    staticStroke = $derived(typeof this.#getProps().stroke === 'string' ? this.#getProps().stroke : undefined);
+    staticStrokeWidth = $derived(typeof this.#getProps().strokeWidth === 'number'
+        ? this.#getProps().strokeWidth
+        : undefined);
+    staticOpacity = $derived(typeof this.#getProps().opacity === 'number' ? this.#getProps().opacity : undefined);
+    staticClassName = $derived(typeof this.#getProps().class === 'string' ? this.#getProps().class : undefined);
+    constructor(getProps) {
+        this.#getProps = getProps;
+        const initial = getProps();
+        const _initialX = initial.initialX ?? (typeof initial.x === 'function' ? 0 : (initial.x ?? 0));
+        const _initialY = initial.initialY ?? (typeof initial.y === 'function' ? 0 : (initial.y ?? 0));
+        this.#motionX = createMotion(_initialX, () => {
+            const x = getProps().x;
+            return typeof x === 'number' || typeof x === 'string' ? x : 0;
+        }, initial.motion);
+        this.#motionY = createMotion(_initialY, () => {
+            const y = getProps().y;
+            return typeof y === 'number' || typeof y === 'string' ? y : 0;
+        }, initial.motion);
+        // Tween numeric values when motion is configured
+        this.#motionValue = createMotion(typeof initial.value === 'number' ? initial.value : 0, () => (typeof getProps().value === 'number' ? getProps().value : 0), typeof initial.value === 'number' && initial.motion
+            ? typeof initial.motion === 'object' && 'type' in initial.motion
+                ? initial.motion
+                : undefined
+            : undefined);
+        this.#dataMotionMap = createDataMotionMap(initial.motion);
+        if (this.#dataMotionMap) {
+            const motionMap = this.#dataMotionMap;
+            $effect(() => {
+                if (!this.dataMode)
+                    return;
+                const props = getProps();
+                const keyFn = props.key ?? defaultKey;
+                const activeKeys = new Set();
+                for (let i = 0; i < this.#resolvedData.length; i++) {
+                    const d = this.#resolvedData[i];
+                    const key = keyFn(d, i);
+                    activeKeys.add(key);
+                    const resolved = this.resolveTextPosition(d);
+                    untrack(() => motionMap.update(key, resolved));
+                }
+                untrack(() => motionMap.cleanup(activeKeys));
+            });
+        }
+    }
+}

package/dist/components/Text/Text.svelte

@@ -0,0 +1,29 @@
+<script lang="ts" module>
+  // Re-export so existing `import type { TextProps } from '../../index.js'` keeps working.
+  export type {
+    TextProps,
+    TextPropsWithoutHTML,
+    TextSegment,
+  } from './Text.shared.svelte.js';
+  export { isTextDataProp } from './Text.shared.svelte.js';
+</script>
+
+<script lang="ts">
+  import { getLayerContext } from '../../contexts/layer.js';
+  import TextSvg from './Text.svg.svelte';
+  import TextCanvas from './Text.canvas.svelte';
+  import TextHtml from './Text.html.svelte';
+  import type { TextProps } from './Text.shared.svelte.js';
+
+  const layerCtx = getLayerContext();
+
+  let props: TextProps = $props();
+</script>
+
+{#if layerCtx === 'svg'}
+  <TextSvg {...props} />
+{:else if layerCtx === 'canvas'}
+  <TextCanvas {...props} />
+{:else if layerCtx === 'html'}
+  <TextHtml {...props} />
+{/if}

package/dist/components/Text/Text.svelte.d.ts

@@ -0,0 +1,6 @@
+export type { TextProps, TextPropsWithoutHTML, TextSegment, } from './Text.shared.svelte.js';
+export { isTextDataProp } from './Text.shared.svelte.js';
+import type { TextProps } from './Text.shared.svelte.js';
+declare const Text: import("svelte").Component<TextProps, {}, "">;
+type Text = ReturnType<typeof Text>;
+export default Text;

package/dist/components/Text/Text.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};