layerchart 2.0.0-next.5 → 2.0.0-next.51

package/dist/utils/stats.js

@@ -0,0 +1,79 @@
+import { quantile, ascending, deviation } from 'd3-array';
+/**
+ * Compute box plot statistics (five-number summary + outliers) from raw numeric values.
+ * Uses the standard Tukey method: outliers are values beyond `k * IQR` from Q1/Q3.
+ *
+ * @param values - Array of numeric values
+ * @param k - IQR multiplier for outlier detection (default: 1.5)
+ */
+export function computeBoxStats(values, k = 1.5) {
+    const sorted = Float64Array.from(values).sort();
+    const q1 = quantile(sorted, 0.25);
+    const q3 = quantile(sorted, 0.75);
+    const median = quantile(sorted, 0.5);
+    const iqr = q3 - q1;
+    const lowerFence = q1 - k * iqr;
+    const upperFence = q3 + k * iqr;
+    const outliers = [];
+    let min = Infinity;
+    let max = -Infinity;
+    for (const v of sorted) {
+        if (v < lowerFence || v > upperFence) {
+            outliers.push(v);
+        }
+        else {
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+    }
+    // If no non-outlier values, use q1/q3 as min/max
+    if (min === Infinity)
+        min = q1;
+    if (max === -Infinity)
+        max = q3;
+    return { min, q1, median, q3, max, outliers };
+}
+/**
+ * Epanechnikov kernel function.
+ * Optimal kernel for minimizing mean integrated squared error.
+ */
+function epanechnikov(bandwidth) {
+    return (x) => {
+        const u = x / bandwidth;
+        return Math.abs(u) <= 1 ? (0.75 * (1 - u * u)) / bandwidth : 0;
+    };
+}
+/**
+ * Compute kernel density estimation (KDE) for a set of numeric values.
+ * Returns an array of [value, density] pairs suitable for rendering violin plots.
+ *
+ * @param values - Array of numeric values
+ * @param options - KDE configuration
+ */
+export function kde(values, options = {}) {
+    const { kernel = epanechnikov, thresholds: thresholdsProp = 50 } = options;
+    const sorted = [...values].sort(ascending);
+    if (sorted.length === 0)
+        return [];
+    const ext = options.extent ?? [sorted[0], sorted[sorted.length - 1]];
+    // Silverman's rule of thumb for bandwidth
+    const bw = options.bandwidth ?? 1.06 * (deviation(sorted) ?? 1) * Math.pow(sorted.length, -1 / 5);
+    const kernelFn = kernel(bw);
+    // Generate evaluation thresholds
+    let ticks;
+    if (Array.isArray(thresholdsProp)) {
+        ticks = thresholdsProp;
+    }
+    else {
+        const n = Math.max(2, thresholdsProp);
+        const step = (ext[1] - ext[0]) / (n - 1);
+        ticks = Array.from({ length: n }, (_, i) => ext[0] + i * step);
+    }
+    // Compute density at each threshold
+    return ticks.map((t) => {
+        const density = values.reduce((sum, v) => sum + kernelFn(t - v), 0) / values.length;
+        return [t, density];
+    });
+}

package/dist/utils/string.d.ts

@@ -0,0 +1,51 @@
+declare function _getStringWidth(str: string, style?: CSSStyleDeclaration): number | null;
+export declare const getStringWidth: typeof _getStringWidth;
+export type RasterizeTextOptions = {
+    fontSize?: string;
+    fontWeight?: number;
+    fontFamily?: string;
+    textAlign?: CanvasTextAlign;
+    textBaseline?: CanvasTextBaseline;
+    spacing?: number;
+    width?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+};
+export declare function rasterizeText(text: string, options?: RasterizeTextOptions): number[][];
+export declare function toTitleCase(str: string): string;
+export type TruncateTextOptions = {
+    /**
+     * The maximum pixel width (optional if maxChars is provided).
+     */
+    maxWidth?: number;
+    /**
+     * CSS style for width calculation
+     */
+    style?: CSSStyleDeclaration;
+    /**
+     * The maximum character count
+     */
+    maxChars?: number;
+    /**
+     * Where to place the ellipsis: 'start', 'middle', or 'end'
+     *
+     * @default 'end'
+     */
+    position?: 'start' | 'middle' | 'end';
+    /**
+     * The character(s) to use as the ellipsis
+     *
+     * @default '…'
+     */
+    ellipsis?: string;
+};
+/**
+ * Truncates a string to fit within a specified pixel width or character count.
+ * If the string's width exceeds the maxWidth, it will be truncated. If the character
+ * count exceeds maxChars, it will also be truncated.
+ *
+ * The ellipsis can be placed at the start, middle, or end of the string.
+ */
+export declare function truncateText(text: string, { position, ellipsis, maxWidth, style, maxChars }: TruncateTextOptions): string;
+export {};

package/dist/utils/string.js

@@ -1,4 +1,4 @@
-import { memoize } from 'lodash-es';
+import memoize from 'memoize';
 const MEASUREMENT_ELEMENT_ID = '__text_measurement_id';
 function _getStringWidth(str, style) {
     try {
@@ -24,7 +24,9 @@ function _getStringWidth(str, style) {
         return null;
     }
 }
-export const getStringWidth = memoize(_getStringWidth, (str, style) => `${str}_${JSON.stringify(style)}`);
+export const getStringWidth = memoize(_getStringWidth, {
+    cacheKey: ([str, style]) => `${str}_${JSON.stringify(style)}`,
+});
 export function rasterizeText(text, options = {}) {
     const fontSize = options.fontSize ?? '200px';
     const fontWeight = options.fontWeight ?? 600;

package/dist/utils/ticks.d.ts

@@ -1,9 +1,20 @@
 import { type TimeInterval } from 'd3-time';
+import { Duration, type FormatType, type FormatConfig } from '@layerstack/utils';
 import { type AnyScale } from './scales.svelte.js';
-export declare function getMajorTicks(start: Date, end: Date): TimeInterval | null;
-export declare function formatMajorTick(date: Date, rangeStart: Date, rangeEnd: Date): string;
-export declare function getMinorTicks(start: Date, end: Date): TimeInterval | null;
+import type { AxisProps } from '../components/Axis.svelte';
+export declare function getDurationFormat(duration: Duration, options?: {
+    multiline?: boolean;
+    placement?: AxisProps['placement'];
+}): (date: Date, i: number) => string;
 export type TicksConfig = number | any[] | ((scale: AnyScale) => any[] | undefined) | {
     interval: TimeInterval | null;
 } | null;
-export declare function resolveTickVals(scale: AnyScale, ticks?: TicksConfig, placement?: 'radius' | 'top' | 'bottom' | 'left' | 'right' | 'angle'): any[];
+export declare function autoTickVals(scale: AnyScale, ticks?: TicksConfig, count?: number): any[];
+export declare function autoTickFormat(options: {
+    scale: AnyScale;
+    ticks?: TicksConfig;
+    count?: number;
+    formatType?: FormatType | FormatConfig;
+    multiline?: boolean;
+    placement?: AxisProps['placement'];
+}): (date: Date, i: number) => string;

package/dist/utils/ticks.js

@@ -1,183 +1,168 @@
-import { timeYear, timeMonth, timeWeek, timeDay, timeHour, timeMinute, timeSecond, timeMillisecond, } from 'd3-time';
-import { format } from 'date-fns';
-import { formatDate, PeriodType, getDuration, fail } from '@layerstack/utils';
-import { isScaleBand } from './scales.svelte.js';
-// TODO: Use PeriodType along with Duration to format (and possibly select intervals)
-const majorTicks = [
-    {
-        predicate: (duration) => duration == null, // Unknown
-        interval: timeYear.every(1), // Better than rendering a lot of items
-        format: (date) => date.toString(),
-    },
-    {
-        predicate: (duration) => duration.years > 1,
-        interval: timeYear.every(1),
-        format: (date) => formatDate(date, PeriodType.CalendarYear, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.years,
-        interval: timeMonth.every(1),
-        format: (date) => formatDate(date, PeriodType.Month, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.days > 30,
-        interval: timeMonth.every(1),
-        format: (date) => formatDate(date, PeriodType.Month, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.days,
-        interval: timeDay.every(1),
-        format: (date) => formatDate(date, PeriodType.Day, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.hours,
-        interval: timeHour.every(1),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.minutes > 10,
-        interval: timeMinute.every(10),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.minutes,
-        interval: timeMinute.every(1),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.seconds > 10,
-        interval: timeSecond.every(10),
-        format: (date) => format(date, 'h:mm:ss'),
-    },
-    {
-        predicate: (duration) => duration.seconds,
-        interval: timeSecond.every(1),
-        format: (date) => format(date, 'h:mm:ss'),
-    },
-    {
-        predicate: (duration) => true, // 0 or more milliseconds
-        interval: timeMillisecond.every(100),
-        format: (date) => format(date, 'h:mm:ss.SSS'),
-    },
-];
-const minorTicks = [
-    {
-        predicate: (duration) => duration == null, // Unknown
-        interval: timeYear.every(1), // Better than rendering a lot of items
-        format: (date) => date.toString(),
-    },
-    {
-        predicate: (duration) => duration.years,
-        interval: timeMonth.every(1),
-        format: (date) => formatDate(date, PeriodType.Month, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.days > 90,
-        interval: timeMonth.every(1),
-        format: (date) => formatDate(date, PeriodType.Month, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.days > 30,
-        interval: timeWeek.every(1),
-        format: (date) => formatDate(date, PeriodType.WeekSun, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.days > 7,
-        interval: timeDay.every(1),
-        format: (date) => formatDate(date, PeriodType.Day, { variant: 'short' }),
-    },
-    {
-        predicate: (duration) => duration.days > 3,
-        interval: timeHour.every(8),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.days,
-        interval: timeHour.every(1),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.hours,
-        interval: timeMinute.every(15),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.minutes > 10,
-        interval: timeMinute.every(10),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.minutes > 2,
-        interval: timeMinute.every(1),
-        format: (date) => format(date, 'h:mm a'),
-    },
-    {
-        predicate: (duration) => duration.minutes,
-        interval: timeSecond.every(10),
-        format: (date) => format(date, 'h:mm:ss'),
-    },
-    {
-        predicate: (duration) => duration.seconds,
-        interval: timeSecond.every(1),
-        format: (date) => format(date, 'h:mm:ss'),
-    },
-    {
-        predicate: (duration) => true, // 0 or more milliseconds
-        interval: timeMillisecond.every(10),
-        format: (date) => format(date, 'h:mm:ss.SSS'),
-    },
-];
-export function getMajorTicks(start, end) {
-    const duration = getDuration(start, end);
-    for (var t of majorTicks) {
-        if (t.predicate(duration)) {
-            return t.interval;
+import { timeYear, timeDay, timeTicks } from 'd3-time';
+import { format, Duration, isLiteralObject, DateToken, } from '@layerstack/utils';
+import { isScaleBand, isScaleTime } from './scales.svelte.js';
+export function getDurationFormat(duration, options = {
+    multiline: false,
+}) {
+    const { multiline = false, placement = 'bottom' } = options;
+    return function (date, i) {
+        let result = '';
+        if (+duration >= +new Duration({ duration: { years: 1 } })) {
+            // Year
+            result = format(date, 'year');
         }
-    }
-    fail(`Unable to locate major ticks for duration: ${duration}`);
-}
-export function formatMajorTick(date, rangeStart, rangeEnd) {
-    const duration = getDuration(rangeStart, rangeEnd);
-    for (var t of majorTicks) {
-        if (t.predicate(duration)) {
-            return t.format(date);
+        else if (+duration >= +new Duration({ duration: { days: 28 } })) {
+            // Month
+            const isFirst = i === 0 || +timeYear.floor(date) === +date;
+            if (multiline) {
+                result = [format(date, 'month', { variant: 'short' }), isFirst && format(date, 'year')];
+            }
+            else {
+                result =
+                    format(date, 'month', { variant: 'short' }) +
+                        (isFirst ? ` '${format(date, 'year', { variant: 'short' })}` : '');
+            }
         }
-    }
-    fail(`Unable to format major ticks for duration: ${duration}`);
-}
-export function getMinorTicks(start, end) {
-    const duration = getDuration(start, end);
-    for (var t of minorTicks) {
-        if (t.predicate(duration)) {
-            return t.interval;
+        else if (+duration >= +new Duration({ duration: { days: 1 } })) {
+            // Day
+            const isFirst = i === 0 || date.getDate() <= duration.days;
+            if (multiline) {
+                result = [
+                    format(date, 'custom', { custom: DateToken.DayOfMonth_numeric }),
+                    isFirst && format(date, 'month', { variant: 'short' }),
+                ];
+            }
+            else {
+                result = format(date, 'day', { variant: 'short' });
+            }
         }
-    }
-    fail(`Unable to locate minor ticks for duration: ${duration}`);
+        else if (+duration >= +new Duration({ duration: { hours: 1 } })) {
+            // Hours
+            const isFirst = i === 0 || +timeDay.floor(date) === +date;
+            if (multiline) {
+                result = [
+                    format(date, 'custom', { custom: DateToken.Hour_numeric }),
+                    isFirst && format(date, 'day', { variant: 'short' }),
+                ];
+            }
+            else {
+                result = isFirst
+                    ? format(date, 'day', { variant: 'short' })
+                    : format(date, 'custom', { custom: DateToken.Hour_numeric });
+            }
+        }
+        else if (+duration >= +new Duration({ duration: { minutes: 1 } })) {
+            // Minutes
+            const isFirst = i === 0 || +timeDay.floor(date) === +date;
+            if (multiline) {
+                result = [
+                    format(date, 'time', { variant: 'short' }),
+                    isFirst && format(date, 'day', { variant: 'short' }),
+                ];
+            }
+            else {
+                result = format(date, 'time', { variant: 'short' });
+            }
+        }
+        else if (+duration >= +new Duration({ duration: { seconds: 1 } })) {
+            // Seconds
+            const isFirst = i === 0 || +timeDay.floor(date) === +date;
+            result = [
+                format(date, 'time'),
+                multiline && isFirst && format(date, 'day', { variant: 'short' }),
+            ];
+        }
+        else if (+duration >= +new Duration({ duration: { milliseconds: 1 } })) {
+            // Milliseconds
+            const isFirst = i === 0 || +timeDay.floor(date) === +date;
+            result = [
+                format(date, 'custom', {
+                    custom: [
+                        DateToken.Hour_2Digit,
+                        DateToken.Minute_2Digit,
+                        DateToken.Second_2Digit,
+                        DateToken.MiliSecond_3,
+                        DateToken.Hour_woAMPM,
+                    ],
+                }),
+                multiline && isFirst && format(date, 'day', { variant: 'short' }),
+            ];
+        }
+        else {
+            result = date.toString();
+        }
+        if (Array.isArray(result)) {
+            switch (placement) {
+                case 'top':
+                    return result.filter(Boolean).reverse().join('\n');
+                case 'bottom':
+                    return result.filter(Boolean).join('\n');
+                case 'left':
+                    return result.filter(Boolean).reverse().join(' ');
+                case 'right':
+                    return result.filter(Boolean).join(' ');
+                default:
+                    return result.filter(Boolean).join('\n');
+            }
+        }
+        else {
+            return result;
+        }
+    };
 }
-export function resolveTickVals(scale, ticks, placement) {
+export function autoTickVals(scale, ticks, count) {
+    // Explicit ticks
     if (Array.isArray(ticks))
         return ticks;
+    // Function
     if (typeof ticks === 'function')
         return ticks(scale) ?? [];
+    // Interval
     if (isLiteralObject(ticks) && 'interval' in ticks) {
         if (ticks.interval === null || !('ticks' in scale) || typeof scale.ticks !== 'function') {
             return []; // Explicitly return empty array for null interval or invalid scale
         }
         return scale.ticks(ticks.interval);
     }
+    // Band (use domain)
     if (isScaleBand(scale)) {
-        return ticks && typeof ticks === 'number'
-            ? scale.domain().filter((_, i) => i % ticks === 0)
-            : scale.domain();
+        const domain = scale.domain();
+        const resolvedCount = typeof ticks === 'number' ? ticks : count;
+        if (resolvedCount != null && resolvedCount < domain.length) {
+            const step = Math.max(1, Math.ceil(domain.length / resolvedCount));
+            return domain.filter((_, i) => i % step === 0);
+        }
+        return domain;
     }
+    // Ticks from scale
     if (scale.ticks && typeof scale.ticks === 'function') {
-        if (placement) {
-            return scale.ticks(ticks ?? (placement === 'left' || placement === 'right' ? 4 : undefined));
-        }
-        return scale.ticks(ticks);
+        return scale.ticks(count ?? (typeof ticks === 'number' ? ticks : undefined));
     }
     return [];
 }
-function isLiteralObject(val) {
-    return val !== null && typeof val === 'object' && !Array.isArray(val);
+export function autoTickFormat(options) {
+    const { scale, ticks, count, formatType, multiline, placement } = options;
+    // Explicit format
+    if (formatType) {
+        // @ts-expect-error - improve types
+        return (tick) => format(tick, formatType);
+    }
+    // Time scale
+    if (isScaleTime(scale) && count) {
+        if (isLiteralObject(ticks) && 'interval' in ticks && ticks.interval != null) {
+            const start = ticks.interval.floor(new Date());
+            const end = ticks.interval.ceil(new Date());
+            return getDurationFormat(new Duration({ start, end }), { multiline, placement });
+        }
+        else {
+            // Compare first 2 ticks to determine duration between ticks for formatting
+            const [start, end] = timeTicks(scale.domain()[0], scale.domain()[1], count);
+            return getDurationFormat(new Duration({ start, end }), { multiline, placement });
+        }
+    }
+    // Format from scale
+    if (scale.tickFormat) {
+        return scale.tickFormat(count);
+    }
+    return (tick) => `${tick}`;
 }

package/dist/utils/ticks.test.js

@@ -1,67 +1,67 @@
 import { describe, it, expect, vi } from 'vitest';
-import { resolveTickVals } from './ticks.js';
+import { autoTickVals } from './ticks.js';
 // Mock helpers
 const mockTicksFn = vi.fn();
 const mockDomain = vi.fn(() => ['a', 'b', 'c', 'd', 'e']);
-describe('resolveTickVals', () => {
+describe('autoTickVals', () => {
     it('returns array ticks directly', () => {
         const ticks = [1, 2, 3];
         const scale = { ticks: mockTicksFn };
-        expect(resolveTickVals(scale, ticks)).toEqual([1, 2, 3]);
+        expect(autoTickVals(scale, ticks)).toEqual([1, 2, 3]);
     });
     it('calls function ticks with scale', () => {
         const fnTicks = vi.fn(() => [4, 5, 6]);
         const scale = { ticks: mockTicksFn };
-        expect(resolveTickVals(scale, fnTicks)).toEqual([4, 5, 6]);
+        expect(autoTickVals(scale, fnTicks)).toEqual([4, 5, 6]);
         expect(fnTicks).toHaveBeenCalledWith(scale);
     });
     it('uses interval when provided', () => {
         const interval = { every: vi.fn() };
         const ticksConfig = { interval };
         const scale = { ticks: vi.fn(() => [7, 8, 9]) };
-        expect(resolveTickVals(scale, ticksConfig)).toEqual([7, 8, 9]);
+        expect(autoTickVals(scale, ticksConfig)).toEqual([7, 8, 9]);
         expect(scale.ticks).toHaveBeenCalledWith(interval);
     });
     it('returns empty array if interval is null', () => {
         const ticksConfig = { interval: null };
         const scale = { ticks: mockTicksFn };
-        expect(resolveTickVals(scale, ticksConfig)).toEqual([]);
+        expect(autoTickVals(scale, ticksConfig)).toEqual([]);
     });
-    it('filters band scale domain with number ticks', () => {
+    it('filters band scale domain with explicit number ticks', () => {
         const scale = { domain: mockDomain, bandwidth: vi.fn() };
-        expect(resolveTickVals(scale, 2)).toEqual(['a', 'c', 'e']);
+        // ticks=2, domain has 5 items → step = ceil(5/2) = 3 → indices 0, 3
+        expect(autoTickVals(scale, 2)).toEqual(['a', 'd']);
     });
-    it('returns full domain for band scale without ticks', () => {
+    it('filters band scale domain using count parameter (from tickSpacing)', () => {
         const scale = { domain: mockDomain, bandwidth: vi.fn() };
-        expect(resolveTickVals(scale)).toEqual(['a', 'b', 'c', 'd', 'e']);
+        // count=3, domain has 5 items → step = ceil(5/3) = 2 → indices 0, 2, 4
+        expect(autoTickVals(scale, undefined, 3)).toEqual(['a', 'c', 'e']);
     });
-    it('uses default 4 ticks for left placement', () => {
-        const scale = { ticks: vi.fn(() => [1, 2, 3, 4]) };
-        expect(resolveTickVals(scale, undefined, 'left')).toEqual([1, 2, 3, 4]);
-        expect(scale.ticks).toHaveBeenCalledWith(4);
+    it('returns full domain for band scale when count >= domain length', () => {
+        const scale = { domain: mockDomain, bandwidth: vi.fn() };
+        expect(autoTickVals(scale, undefined, 10)).toEqual(['a', 'b', 'c', 'd', 'e']);
     });
-    it('uses default 4 ticks for right placement', () => {
-        const scale = { ticks: vi.fn(() => [1, 2, 3, 4]) };
-        expect(resolveTickVals(scale, undefined, 'right')).toEqual([1, 2, 3, 4]);
-        expect(scale.ticks).toHaveBeenCalledWith(4);
+    it('returns full domain for band scale without ticks or count', () => {
+        const scale = { domain: mockDomain, bandwidth: vi.fn() };
+        expect(autoTickVals(scale)).toEqual(['a', 'b', 'c', 'd', 'e']);
     });
     it('uses undefined for non-left/right placement', () => {
-        const scale = { ticks: vi.fn(() => [1, 2]) };
-        expect(resolveTickVals(scale, undefined, 'top')).toEqual([1, 2]);
+        const scale = { domain: mockDomain, ticks: vi.fn(() => [1, 2]) };
+        expect(autoTickVals(scale, undefined, undefined)).toEqual([1, 2]);
         expect(scale.ticks).toHaveBeenCalledWith(undefined);
     });
     it('passes number ticks to scale.ticks', () => {
-        const scale = { ticks: vi.fn(() => [10, 20]) };
-        expect(resolveTickVals(scale, 5)).toEqual([10, 20]);
+        const scale = { domain: mockDomain, ticks: vi.fn(() => [10, 20]) };
+        expect(autoTickVals(scale, 5)).toEqual([10, 20]);
         expect(scale.ticks).toHaveBeenCalledWith(5);
     });
     it('returns empty array for scale without ticks', () => {
-        const scale = {};
-        expect(resolveTickVals(scale, 5)).toEqual([]);
+        const scale = { domain: mockDomain };
+        expect(autoTickVals(scale, 5)).toEqual([]);
     });
     it('handles null ticks with placement', () => {
-        const scale = { ticks: vi.fn(() => [1, 2, 3]) };
-        expect(resolveTickVals(scale, null, 'bottom')).toEqual([1, 2, 3]);
+        const scale = { domain: mockDomain, ticks: vi.fn(() => [1, 2, 3]) };
+        expect(autoTickVals(scale, null, undefined)).toEqual([1, 2, 3]);
         expect(scale.ticks).toHaveBeenCalledWith(undefined);
     });
 });

package/dist/utils/trail.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Trail path utilities for variable-width lines.
+ *
+ * Round cap (capsule) approach adapted from Vega's trail mark.
+ * Copyright (c) 2015-2023, University of Washington Interactive Data Lab.
+ * BSD 3-Clause License: https://github.com/vega/vega/blob/main/LICENSE
+ *
+ * Butt cap (polygon offset) and curve resampling via fake context
+ * adapted from SveltePlot's trail mark.
+ * Copyright 2024-2026, Gregor Aisch.
+ * ISC License: https://github.com/svelteplot/svelteplot/blob/main/LICENSE
+ */
+import type { CurveFactory, CurveFactoryLineOnly } from 'd3-shape';
+export type TrailPoint = {
+    x: number;
+    y: number;
+    r: number;
+};
+export type TrailCap = 'round' | 'butt';
+export type TrailPathOptions = {
+    /** Curve interpolation factory from d3-shape */
+    curve?: CurveFactory | CurveFactoryLineOnly;
+    /** Cap style for trail endpoints. @default 'round' */
+    cap?: TrailCap;
+    /** Tension parameter for applicable curve factories (0–1) */
+    tension?: number;
+    /** Samples per segment for curve interpolation. Auto-estimated when omitted. */
+    resolution?: number;
+};
+/**
+ * Computes a filled SVG path for a trail with variable width.
+ *
+ * Supports optional curve interpolation (via d3-shape curve factories)
+ * and two cap styles: 'round' (capsule-based) and 'butt' (polygon offset).
+ */
+export declare function computeTrailPath(points: TrailPoint[], options?: TrailPathOptions): string;