vue-data-ui 3.20.1 → 3.20.2

package/dist/types/utils.d.ts

@@ -0,0 +1,551 @@
+//--------------------------------------------------------------------------------------------//
+
+/**
+ * UTILITY FUNCTION TYPES
+ *
+ * IMPORTANT: these types are duplicated in vue-data-ui.d.ts  for the legacy import to work.
+ * If we ever ship a v4 these types can be forcefully removed from vue-data-ui.ts, with
+ * a breaking change.
+ */
+
+//--------------------------------------------------------------------------------------------//
+
+/**
+ * Configuration options for cumulative functions
+ */
+export type CumulativeConfig = {
+    /**
+     * If `true`, invalid inputs are kept (and echoed) in the output.
+     * Defaults to `true`.
+     */
+    keepInvalid?: boolean;
+    /**
+     * If `true`, invalid inputs are treated as zero when computing the statistic.
+     * Defaults to `false`.
+     */
+    convertInvalidToZero?: boolean;
+};
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Compute the cumulative median of a sequence, optionally echoing or zero-filling invalid inputs.
+ * ---
+ * @example
+ * ```js
+ * // Simple usage
+ * const arr = [1, 2, 3, 4, 5];
+ * const medians = getCumulativeMedian({ values: arr });
+ *
+ * // Ignore invalid values entirely
+ * const arrWithInvalid = [1, null, 2, Infinity, undefined];
+ * const mediansNoInvalid = getCumulativeMedian({
+ *   values: arrWithInvalid,
+ *   config: { keepInvalid: false }
+ * });
+ *
+ * // Convert invalid values to zero
+ * const mediansZeroed = getCumulativeMedian({
+ *   values: arrWithInvalid,
+ *   config: { convertInvalidToZero: true }
+ * });
+ * ```
+ *
+ * @param {Object} params
+ * @param {Array<number|*>} params.values
+ *   The input sequence. Can include numbers or any “invalid” placeholders.
+ * @param {CumulativeConfig} [params.config]
+ *   Configuration flags to control handling of invalid inputs.
+ * @returns {Array<number|*>}
+ *   An array where each slot is either the cumulative median up to that point,
+ *   or the original invalid value if `keepInvalid` is `true`.
+ */
+export function getCumulativeMedian<T = unknown>(params: {
+    values: Array<number | T>;
+    config?: CumulativeConfig;
+}): Array<number | T>;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Compute the cumulative median of a sequence, optionally echoing or zero-filling invalid inputs.
+ * ---
+ * @example
+ * ```js
+ * // Simple usage
+ * const arr = [1, 2, 3, 4, 5];
+ * const medians = getCumulativeMedian({ values: arr });
+ *
+ * // Ignore invalid values entirely
+ * const arrWithInvalid = [1, null, 2, Infinity, undefined];
+ * const mediansNoInvalid = getCumulativeMedian({
+ *   values: arrWithInvalid,
+ *   config: { keepInvalid: false }
+ * });
+ *
+ * // Convert invalid values to zero
+ * const mediansZeroed = getCumulativeMedian({
+ *   values: arrWithInvalid,
+ *   config: { convertInvalidToZero: true }
+ * });
+ * ```
+ *
+ * @param {Object} params
+ * @param {Array<number|*>} params.values
+ *   The input sequence. Can include numbers or any “invalid” placeholders.
+ * @param {CumulativeConfig} [params.config]
+ *   Configuration flags to control handling of invalid inputs.
+ * @returns {Array<number|*>}
+ *   An array where each slot is either the cumulative median up to that point,
+ *   or the original invalid value if `keepInvalid` is `true`.
+ */
+export function getCumulativeAverage<T = unknown>(params: {
+    values: Array<number | T>;
+    config?: CumulativeConfig;
+}): Array<number | T>;
+
+/**
+ * Recursively makes all properties in T optional.
+ * - Leaves functions as-is
+ * - Handles arrays by making their item type DeepPartial
+ */
+export type DeepPartial<T> = T extends Function
+    ? T
+    : T extends Array<infer U>
+      ? Array<DeepPartial<U>>
+      : T extends object
+        ? { [K in keyof T]?: DeepPartial<T[K]> }
+        : T;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Merge a partial config with a full default config
+ * ---
+ * @example
+ * const defaultConfig = getVueDataUiConfig('vue_ui_xy');
+ * const merged = mergeConfigs({
+ *      defaultConfig,
+ *      userConfig: {
+ *          chart: {
+ *              backgroundColor: '#FF0000'
+ *          }
+ *      }
+ * })
+ */
+export function mergeConfigs<T extends Record<string, any>>({
+    defaultConfig,
+    userConfig,
+}: {
+    defaultConfig: T;
+    userConfig: DeepPartial<T>;
+}): T;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Generate a straight line path to include in the d attribute of a svg path element
+ * ___
+ * @example
+ * const path = createStraightPath([{x: 1, y: 1}, { x: 2, y: 1.2}])
+ *
+ * @param points - An array of point objects
+ */
+export const createStraightPath: (points: Point[]) => string;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Generate a spline path to include in the d attribute of a svg path element
+ * ___
+ * @example
+ * const path = createSmoothPath([{x: 1, y: 1}, { x: 2, y: 1.2}, { x: 3, y: 0.2 }])
+ *
+ * @param points - An array of point objects
+ */
+export const createSmoothPath: (points: Point[]) => string;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Create a dataset for VueUiWordCloud from a string
+ * ___
+ * @example
+ * const dataset = createWordCloudDatasetFromPlainText('Lorem Ipsum Dolor', (w) => w.toUpperCase())
+ *
+ * @param text - The text from which the dataset will be generated
+ * @param callback - Optional transform callback to format each word of the dataset
+ */
+export const createWordCloudDatasetFromPlainText: (
+    text: string,
+    callback?: VueDataUiWordCloudTransformCallback,
+) => VueUiWordCloudDatasetItem[];
+
+export type VueDataUiAbbreviatePayload = {
+    source: string;
+    length?: number;
+};
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Abbreviate a string to a given length
+ * ___
+ * @example
+ * const label = abbreviate({
+ *  source: 'Lorem Ipsum Dolor',
+ *  length: 3
+ * })
+ *
+ * @param source - The string to abbreviate
+ * @param length - The number of letters to return (defaults to 3)
+ */
+export const abbreviate: (payload: VueDataUiAbbreviatePayload) => string;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Get the color palette for a given theme
+ * ___
+ * @example
+ * const palette = getPalette("hack");
+ *
+ * @param theme - The theme for which the palette is requested (e.g., "hack" | "zen", | "concrete")
+ */
+export const getPalette: (theme: Theme) => string[];
+
+export type VueDataUiGetConfigOptions = {
+    colorBackground?: string;
+    colorTextPrimary?: string;
+    colorTextSecondary?: string;
+    colorGrid?: string;
+    colorBorder?: string;
+};
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Get the default config for a given component
+ * ___
+ * @typeParam T - The config type for the component
+ * @param key - Component key in snake_case (e.g. `"vue_ui_xy"`).
+ * @param options - Optional general color settings
+ * @returns The default configuration of type `T`.
+ * @example
+ * ```ts
+ * const defaultConfig = getVueDataUiConfig<VueUiXyConfig>("vue_ui_xy");
+ * ```
+ */
+export const getVueDataUiConfig: <T>(
+    key: VueDataUiConfigKey,
+    options?: VueDataUiGetConfigOptions,
+) => T;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Lightens a color by a specified strength.
+ * ___
+ * @example
+ * const color = lightenColor("#FF0000", 0.25);
+ * const color = lightenColor("#FF000080", 0.25);
+ * const color = lightenColor("rgb(255,0,0)", 0.25);
+ * const color = lightenColor("rgb(255,0,0,0.5)", 0.25);
+ * const color = lightenColor("red", 0.25);
+ *
+ * @param color - The input color. Can be hexadecimal (e.g., "#FF0000", or "#FF000080" with alpha channel), RGB or RGBA, or a named color.
+ * @param strength - The strength to lighten the color, typically a value between 0 and 1.
+ * @returns The lightened color in hexadecimal format.
+ */
+export const lightenColor: (color: string, strength: number) => string;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Returns a readable text color (dark or light) based on the provided background color.
+ * ___
+ * @example
+ * const color = adaptColorToBackground("#FFFFFF");
+ * const color = adaptColorToBackground("#000000");
+ * const color = adaptColorToBackground("rgba(255,0,0,0.5)");
+ * const color = adaptColorToBackground("oklch(62% 0.15 29)");
+ * const color = adaptColorToBackground("#FF0000", { dark: "#111111", light: "#EEEEEE" });
+ *
+ * @param backgroundColor - The input background color. Can be any supported format.
+ * @param options - Optional color overrides.
+ * @param options.dark - Color returned when the background is considered light.
+ * @param options.light - Color returned when the background is considered dark.
+ * @returns The chosen text color.
+ */
+export const adaptColorToBackground: (
+    backgroundColor: string | null | undefined,
+    options?: { dark?: string; light?: string },
+) => string;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Darkens a color by a specified strength.
+ * ___
+ * @example
+ * const color = darkenColor("#FF0000", 0.25);
+ * const color = darkenColor("#FF000080", 0.25);
+ * const color = darkenColor("rgb(255,0,0)", 0.25);
+ * const color = darkenColor("rgb(255,0,0,0.5)", 0.25);
+ * const color = darkenColor("red", 0.25);
+ *
+ * @param color - The input color. Can be hexadecimal (e.g., "#FF0000", or "#FF000080" with alpha channel), or RGB or RGBA.
+ * @param strength - The strength to darken the color, typically a value between 0 and 1.
+ * @returns The darkened color in hexadecimal format.
+ */
+export const darkenColor: (color: string, strength: number) => string;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Shifts hue for a given color, by a given strength.
+ * ___
+ * @example
+ * const color = shiftColorHue("#FF0000", 0.25);
+ * const color = shiftColorHue("#FF000080", 0.25);
+ * const color = shiftColorHue("rgb(255,0,0)", 0.25);
+ * const color = shiftColorHue("rgb(255,0,0,0.5)", 0.25);
+ * const color = shiftColorHue("red", 0.25);
+ *
+ * @param color - The input color. Can be hexadecimal (e.g., "#FF0000", or "#FF000080" with alpha channel), or RGB or RGBA.
+ * @param strength - The strength to darken the color, typically a value between 0 and 1.
+ * @returns The shifted color in hexadecimal format.
+ */
+export const shiftColorHue: (color: string, strength: number) => string;
+
+export type FormatSmallValueArgs = {
+    value: number;
+    maxDecimals?: number;
+    fallbackFormatter?: (value: number) => string;
+    removeTrailingZero?: boolean;
+};
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Formats numeric values with a controlled number of decimal places,
+ * applying maxDecimals for all values when no fallbackFormatter is given,
+ * or calling the fallbackFormatter for values ≥ 1 if provided.
+ * ___
+ * @example
+ * // Zero value
+ * formatSmallValue({ value: 0 }); // "0"
+ *
+ * // Values < 1 use minimal decimals
+ * formatSmallValue({ value: 0.9 }); // "0.9"
+ * formatSmallValue({ value: 0.0042 }); // "0.0042"
+ * formatSmallValue({ value: 0.00420001 }); // "0.0042"
+ *
+ * // Retain trailing zeros
+ * formatSmallValue({ value: 0.9, removeTrailingZero: false }); // "0.90"
+ *
+ * // Values ≥ 1 without fallback apply maxDecimals
+ * formatSmallValue({ value: 1.61803, maxDecimals: 3 }); // "1.618"
+ *
+ * // Values ≥ 1 with fallbackFormatter
+ * formatSmallValue({ value: 2.5, fallbackFormatter: v => v.toFixed(1) }); // "2.5"
+ *
+ * // Negative values
+ * formatSmallValue({ value: -0.056 }); // "-0.056"
+ *
+ * @param {FormatSmallValueArgs} options - Configuration object for formatting.
+ * @param {number} options.value                 - The numeric value to format.
+ * @param {number} [options.maxDecimals=4]       - Maximum decimal places to use.
+ * @param {(value: number) => string} [options.fallbackFormatter] - Formatter for values ≥ 1.
+ * @param {boolean} [options.removeTrailingZero=true] - Whether to strip unnecessary trailing zeros.
+ * @returns {string} The formatted number as a string.
+ */
+export const formatSmallValue: ({
+    value,
+    maxDecimals,
+    fallbackFormatter,
+    removeTrailingZero,
+}: FormatSmallValueArgs) => string;
+
+export type CreateTSpansArgs = {
+    content: string;
+    fontSize: number;
+    fill: string;
+    maxWords: number;
+    x: number;
+    y: number;
+};
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Creates TSpan elements from a string to break text into multiple lines.
+ * The output should be placed with `v-html` inside an SVG `<text>` element.
+ * ___
+ * @example
+ * const textContent = createTSpans({
+ *   content: "This is an example of multiline text",
+ *   fontSize: 16,
+ *   fill: "#1A1A1A",
+ *   maxWords: 3, // Will create lines of 3 words max
+ *   x: 10,
+ *   y: 20
+ * });
+ *
+ * // Usage: <text :x="10" :y="20" fill="#1A1A1A" :font-size="16" v-html="textContent"/>
+ *
+ * @param {Object} args - The arguments object.
+ * @param {string} args.content - The text content to be split into lines.
+ * @param {number} args.fontSize - The font size used to determine line spacing.
+ * @param {string} args.fill - The fill color for the text.
+ * @param {number} args.maxWords - Maximum number of words per line.
+ * @param {number} args.x - The x-coordinate for each `tspan` element.
+ * @param {number} args.y - The starting y-coordinate for the first `tspan`.
+ *
+ * @returns {string} A string containing the HTML content to be placed with `v-html` inside an SVG `<text>` element.
+ */
+export const createTSpans: ({
+    content,
+    fontSize,
+    fill,
+    maxWords,
+    x,
+    y,
+}: CreateTSpansArgs) => string;
+
+/**
+ * Vue Data UI composable
+ * ---
+ * Flattens a reactive config object into computed refs for every leaf property.
+ *
+ * @template T extends object
+ * @param configRef  A Vue `Ref` holding your object.
+ * @param options    Optional settings: `delimiter` (default `"."`) and `skipArrays` (default `true`).
+ * @returns         An object with flatten config as refs
+ *
+ * ___
+ * @example
+ *
+ * ```js
+ *   import { useObjectBindings } from "vue-data-ui";
+ *
+ *   const config = ref({
+ *     customPalette: ["#CCCCCC", "#1A1A1A"],
+ *     style: {
+ *       chart: {
+ *         backgroundColor: "#FFFFFF",
+ *         color: "#1A1A1A",
+ *       },
+ *     },
+ *   });
+ *
+ *   const bindings = useObjectBindings(config);
+ * ```
+ *
+ * Then in your template:
+ * ```html
+ *   <template>
+ *     <div>
+ *       <input type="color" v-model="bindings['style.chart.backgroundColor']" />
+ *     </div>
+ *   </template>
+ * ```
+ */
+export function useObjectBindings(
+    configRef: Ref<Record<string, any>>,
+    options?: {
+        delimiter?: string;
+        skipArrays?: boolean;
+    },
+): Record<string, Ref<any>>;
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Applies a two-stage data correction pipeline to a numeric time series.
+ * ---
+ *
+ * The correction is performed in sequence:
+ *
+ * 1. Bidirectional Moving Average:
+ *    Reduces local noise by blending trailing (left-anchored) and leading
+ *    (right-anchored) averages. This ensures smooth transitions from both
+ *    fixed endpoints while preserving the first and last values.
+ *
+ * 2. Forward-Backward Exponential Smoothing (Zero-Phase):
+ *    Further smooths the signal without introducing phase lag. A forward
+ *    and backward exponential pass are blended to preserve trend timing
+ *    and avoid temporal shift artifacts.
+ *
+ * This utility is designed for visual data refinement,
+ * where smoothness is required without distorting boundary values
+ * or shifting peaks and transitions.
+ *
+ * @param {Array<{ value: number | null }>} data
+ *   The ordered dataset to correct. Each item must contain a numeric `value`.
+ *
+ * @param {{ averageWindow: number, smoothingTau: number }} settings
+ *   Configuration object:
+ *   - `averageWindow`: Half-window size for the moving average.
+ *     `0` disables the moving average stage.
+ *   - `smoothingTau`: Time constant controlling smoothing strength.
+ *     `0` disables the smoothing stage. Higher values produce smoother output.
+ *
+ * @returns {Array<{ value: number | null }>}
+ *   A new array with corrected values. The original input array is not mutated.
+ */
+export function applyDataCorrection(
+    data: Array<{ value: number | null }>,
+    settings: {
+        averageWindow: number;
+        smoothingTau: number;
+    },
+): Array<{ value: number | null }>;
+
+export type CreatePatternArgs = {
+    id: string;
+    seed: string | number;
+    foregroundColor?: string;
+    backgroundColor?: string;
+    maxSize?: number;
+    minSize?: number;
+    disambiguator?: string | number;
+};
+
+/**
+ * Vue Data UI utility
+ * ---
+ * Creates an SVG <defs> element with a <pattern> markup string for seeded chart patterns.
+ * The output can be injected inside an SVG <defs> element, or in tooltips customFormat to apply patterns on tooltip markers.
+ * ___
+ * @example
+ * const patternMarkup = createPatternDef({
+ *   id: "pattern-1",
+ *   seed: "Series A",
+ *   foregroundColor: "#1A1A1A",
+ *   backgroundColor: "#FFFFFF",
+ *   minSize: 8,
+ *   maxSize: 20
+ *   disambiguator: "pattern-1"
+ * });
+ *
+ * @param {CreatePatternArgs} args - Pattern creation options.
+ * @param {string} args.id - Unique SVG pattern identifier.
+ * @param {string | number} args.seed - Seed used to deterministically generate the pattern.
+ * @param {string} [args.foregroundColor] - Foreground color used for the pattern marks.
+ * @param {string} [args.backgroundColor] - Background color for the pattern tile.
+ * @param {number} [args.maxSize] - Maximum tile size used during seeded pattern generation.
+ * @param {number} [args.minSize] - Minimum tile size used during seeded pattern generation.
+ * @param {string | number} args.disambiguator - Additional unique identifier to disambiguate patterns for large datasets
+ *
+ * @returns {string} SVG <defs> with <pattern> markup as a string.
+ */
+export const createPatternDef: ({
+    id,
+    seed,
+    foregroundColor,
+    backgroundColor,
+    maxSize,
+    minSize,
+    disambiguator,
+}: CreatePatternArgs) => string;