@d3plus/core 3.0.16 → 3.1.0

package/types/src/shapes/Whisker.d.ts

@@ -0,0 +1,96 @@
+import type { DataPoint } from "@d3plus/data";
+import type { D3Selection } from "@d3plus/dom";
+import { BaseClass } from "../utils/index.js";
+import type { AccessorFn } from "../utils/index.js";
+import Circle from "./Circle.js";
+import Line from "./Line.js";
+import Rect from "./Rect.js";
+/**
+    Creates SVG whisker based on an array of data.
+*/
+export default class Whisker extends BaseClass {
+    _endpoint: AccessorFn;
+    _endpointConfig: Record<string, unknown>;
+    _length: AccessorFn;
+    _lineConfig: Record<string, unknown>;
+    _orient: AccessorFn;
+    _x: AccessorFn;
+    _y: AccessorFn;
+    _data: DataPoint[];
+    _select: D3Selection;
+    _line: Line;
+    _whiskerEndpoint: (Circle | Rect)[];
+    /**
+        Invoked when creating a new class instance, and overrides any default parameters inherited from BaseClass.
+        @private
+  */
+    constructor();
+    /**
+        Draws the whisker.
+      @param callback Optional callback invoked after rendering completes.
+  */
+    render(callback?: () => void): this;
+    /**
+        The active highlight state for all sub-shapes in this Whisker.
+  */
+    active(_: ((d: DataPoint, i: number) => boolean) | null): void;
+    /**
+        The data array used to create shapes.
+  */
+    data(): DataPoint[];
+    data(_: DataPoint[]): this;
+    /**
+        The endpoint shape type for each whisker.
+  */
+    endpoint(): AccessorFn;
+    endpoint(_: AccessorFn | string): this;
+    /**
+        Configuration object for each endpoint.
+  */
+    endpointConfig(): Record<string, unknown>;
+    endpointConfig(_: Record<string, unknown>): this;
+    /**
+        The hover highlight state for all sub-shapes in this Whisker.
+  */
+    hover(_: ((d: DataPoint, i: number) => boolean) | null): void;
+    /**
+        Length accessor for whisker.
+  */
+    length(): AccessorFn;
+    length(_: AccessorFn | number): this;
+    /**
+        Configuration object for the line shape.
+  */
+    lineConfig(): Record<string, unknown>;
+    lineConfig(_: Record<string, unknown>): this;
+    /**
+        The orientation of the whisker shape.
+  */
+    orient(): AccessorFn;
+    orient(_: AccessorFn | string): this;
+    /**
+        The SVG container element for this visualization. 3 selector or DOM element.
+  */
+    select(): D3Selection;
+    select(_: string | HTMLElement | SVGElement | null): this;
+    /**
+      The x position accessor for each whisker.
+  
+  @example
+  function(d) {
+    return d.x;
+  }
+  */
+    x(): AccessorFn;
+    x(_: AccessorFn | number): this;
+    /**
+        The y position accessor for each whisker.
+  
+  @example
+  function(d) {
+    return d.y;
+  }
+  */
+    y(): AccessorFn;
+    y(_: AccessorFn | number): this;
+}

package/types/src/shapes/index.d.ts

@@ -0,0 +1,10 @@
+export { default as Shape, type ShapeAes } from "./Shape.js";
+export { default as Area } from "./Area.js";
+export { default as Bar } from "./Bar.js";
+export { default as Box } from "./Box.js";
+export { default as Circle } from "./Circle.js";
+export { default as Image } from "./Image.js";
+export { default as Line } from "./Line.js";
+export { default as Path } from "./Path.js";
+export { default as Rect } from "./Rect.js";
+export { default as Whisker } from "./Whisker.js";

package/types/src/utils/AccessorFn.d.ts

@@ -0,0 +1,6 @@
+import type { DataPoint } from "@d3plus/data";
+/**
+    @type AccessorFn
+    A function that accesses a property from a DataPoint.
+*/
+export type AccessorFn = (d: DataPoint, i?: number) => DataPoint[keyof DataPoint];

package/types/src/utils/BaseClass.d.ts

@@ -0,0 +1,76 @@
+import type { D3plusConfig } from "./D3plusConfig.js";
+/**
+    Provides shared configuration, event handling, and locale management inherited by all d3plus classes.
+*/
+export default class BaseClass {
+    _locale: string;
+    _on: Record<string, (...args: unknown[]) => unknown>;
+    _parent: Record<string, unknown>;
+    _translate: (d: string, locale?: string) => string;
+    _uuid: string;
+    _configDefault?: D3plusConfig;
+    _shapeConfig?: D3plusConfig;
+    /**
+        Invoked when creating a new class instance, and sets any default parameters.
+        @private
+  */
+    constructor();
+    /**
+        Methods that correspond to the key/value pairs and returns this class.
+  */
+    config(): D3plusConfig;
+    config(_: D3plusConfig): this;
+    /**
+        The locale used for all text and number formatting. Supports the locales defined in [d3plus-format](https://github.com/d3plus/d3plus-format/blob/master/src/locale.js). The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.
+  
+  @example
+        {
+          separator: "",
+          suffixes: ["y", "z", "a", "f", "p", "n", "\u00b5", "m", "", "k", "M", "B", "t", "q", "Q", "Z", "Y"],
+          grouping: [3],
+          delimiters: {
+            thousands: ",",
+            decimal: "."
+          },
+          currency: ["$", ""]
+        }
+  */
+    locale(): string;
+    locale(_: string | object): this;
+    /**
+        Event listener for the specified event *typenames*. Mirrors the core [d3-selection](https://github.com/d3/d3-selection#selection_on) behavior.
+  
+  @example <caption>By default, listeners apply globally to all objects, however, passing a namespace with the class name gives control over specific elements:</caption>
+  new Plot
+    .on("click.Shape", function(d) {
+      console.log("data for shape clicked:", d);
+    })
+    .on("click.Legend", function(d) {
+      console.log("data for legend clicked:", d);
+    })
+  */
+    on(): Record<string, (...args: unknown[]) => unknown>;
+    on(_: string): ((...args: unknown[]) => unknown) | undefined;
+    on(_: string, f: (...args: unknown[]) => unknown): this;
+    on(_: Record<string, (...args: unknown[]) => unknown>): this;
+    /**
+        Parent config used by the wrapper.
+  */
+    parent(): Record<string, unknown>;
+    parent(_: Record<string, unknown>): this;
+    /**
+        Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.
+  
+  @example <caption>For example, if we wanted to only change the string "Back" and allow all other string to return in English:</caption>
+  .translate(function(d) {
+    return d === "Back" ? "Get outta here" : d;
+  })
+  */
+    translate(): (d: string, locale?: string) => string;
+    translate(_: (d: string, locale?: string) => string): this;
+    /**
+        Configuration object with key/value pairs applied as method calls on each shape.
+  */
+    shapeConfig(): D3plusConfig;
+    shapeConfig(_: D3plusConfig): this;
+}

package/types/src/utils/D3plusConfig.d.ts

@@ -0,0 +1,164 @@
+import type { DataPoint } from "@d3plus/data";
+type Position = "top" | "right" | "bottom" | "left";
+type DataPointAccessor<T> = string | ((d: DataPoint) => T);
+type AxisScale = "auto" | "band" | "diverging" | "divergingLog" | "divergingPow" | "divergingSqrt" | "divergingSymlog" | "identity" | "implicit" | "jenks" | "linear" | "log" | "ordinal" | "point" | "pow" | "quantile" | "quantize" | "radial" | "sequential" | "sequentialLog" | "sequentialPow" | "sequentialQuantile" | "sequentialSqrt" | "sequentialSymlog" | "sqrt" | "symlog" | "threshold" | "time" | "utc";
+export interface AxisConfig {
+    barConfig?: Record<string, string | number>;
+    gridConfig?: Record<string, string | number>;
+    label?: string;
+    labels?: unknown[];
+    labelOffset?: false | number;
+    maxSize?: number;
+    scale?: AxisScale;
+    tickFormat?: (d: number | string) => string | number;
+    ticks?: unknown[];
+    tickSize?: number;
+    title?: string;
+}
+export interface TooltipConfig {
+    title?: ((d: DataPoint) => string) | string;
+    body?: ((d: DataPoint) => string) | string;
+    thead?: ((d: DataPoint) => [string, string][]) | Array<Array<((d: DataPoint, i?: number, x?: {
+        share: number;
+    }) => string) | string>>;
+    tbody?: ((d: DataPoint) => [string, string][]) | Array<Array<((d: DataPoint, i?: number, x?: {
+        share: number;
+    }) => string) | string>>;
+}
+export interface D3plusConfig {
+    /** Data array or URL string to load data from. */
+    data?: DataPoint[] | string;
+    /** Locale code used for text and number formatting. */
+    locale?: string;
+    /** Custom aggregation functions keyed by data property. */
+    aggs?: {
+        [k: string]: (d: DataPoint[]) => unknown;
+    };
+    /** Padding between bars in pixels. */
+    barPadding?: number;
+    /** Color scale key or custom color function. */
+    colorScale?: string | ((d: number) => string);
+    /** Configuration for the color scale component. */
+    colorScaleConfig?: {
+        axisConfig?: AxisConfig;
+        centered?: boolean;
+        colors?: string[];
+        colorMin?: string;
+        colorMid?: string;
+        colorMax?: string;
+        scale?: AxisScale;
+    };
+    /** Position of the color scale, or false to hide it. */
+    colorScalePosition?: false | Position;
+    /** Column key for matrix-style layouts. */
+    column?: string;
+    /** Active depth level for nested groupings. */
+    depth?: number;
+    /** Sets orientation of main category axis. */
+    discrete?: "x" | "y";
+    /** Allows removing specific geographies from topojson file to improve zoom. */
+    fitFilter?: number | string | ((d: Record<string, unknown>) => boolean);
+    /** Grouping key(s) or accessor function(s). */
+    groupBy?: string | string[] | ((d: DataPoint) => string | number) | ((d: DataPoint) => string | number)[];
+    /** Padding between groups of bars in pixels. */
+    groupPadding?: number;
+    /** Label accessor for shapes. */
+    label?: string | ((...args: unknown[]) => string);
+    /** Whether to show the legend. */
+    legend?: boolean;
+    /** Configuration for the legend component. */
+    legendConfig?: {
+        label?: DataPointAccessor<string>;
+        shapeConfig?: Record<string, string | number>;
+    };
+    /** Position of the legend. */
+    legendPosition?: Position;
+    /** Tooltip configuration for legend items. */
+    legendTooltip?: TooltipConfig;
+    /** Whether to show labels on line charts. */
+    lineLabels?: boolean;
+    /** Whether to show the loading message. */
+    loadingMessage?: boolean;
+    /** Custom HTML content for the loading indicator. */
+    loadingHTML?: string;
+    /** Metric key for the visualization. */
+    metric?: string;
+    /** Ocean color for geomaps (any CSS value including 'transparent'). */
+    ocean?: string;
+    /** Event listeners keyed by event name. */
+    on?: Record<string, (event: Event) => void>;
+    /** Coordinate accessor for point-based geomaps. */
+    point?: (d: DataPoint) => number[];
+    /** Point size accessor for geomaps. */
+    pointSize?: string | ((d: DataPoint) => number);
+    /** Minimum point size for geomaps. */
+    pointSizeMin?: number;
+    /** Maximum point size for geomaps. */
+    pointSizeMax?: number;
+    /** Map projection name or function. */
+    projection?: string | ((x: number, y: number) => [number, number]);
+    /** Outer padding between the visualization edge and map shapes. */
+    projectionPadding?: number | string;
+    /** Rotation offset for the map projection center. */
+    projectionRotate?: [number, number];
+    /** Row key for matrix-style layouts. */
+    row?: string;
+    /** Scrollable container selector for tooltip positioning. */
+    scrollContainer?: string;
+    /** Configuration for shape rendering. */
+    shapeConfig?: {
+        duration?: number;
+        [key: string]: unknown;
+    };
+    /** Size accessor key. */
+    size?: string;
+    /** Whether to stack series. */
+    stacked?: boolean;
+    /** Custom order for stacked series. */
+    stackOrder?: string[];
+    /** Value accessor for treemaps and aggregation. */
+    sum?: DataPointAccessor<number>;
+    /** Threshold value for grouping small slices. */
+    threshold?: number;
+    /** Label for the threshold group. */
+    thresholdName?: string;
+    /** URL to XYZ map tiles. */
+    tileUrl?: string;
+    /** Whether to show map tiles. */
+    tiles?: boolean;
+    /** Time key for temporal data. */
+    time?: string;
+    /** Chart title or title accessor function. */
+    title?: string | ((data: DataPoint[]) => string);
+    /** CSS style configuration for the title. */
+    titleConfig?: Record<string, string | number>;
+    /** Whether to show tooltips. */
+    tooltip?: boolean;
+    /** Configuration for the tooltip component. */
+    tooltipConfig?: TooltipConfig;
+    /** Path or object for the topojson data. */
+    topojson?: string | object;
+    /** CSS color to fill the map shapes. */
+    topojsonFill?: string;
+    /** Accessor function for topojson feature IDs. */
+    topojsonId?: (obj: Record<string, unknown>) => string;
+    /** Value accessor for the visualization. */
+    value?: DataPointAccessor<number>;
+    /** Key, index, or accessor function for x-axis values. */
+    x?: string | number | ((...args: unknown[]) => unknown);
+    /** Configuration for the x-axis. */
+    xConfig?: AxisConfig;
+    /** Custom sort function for x-axis values. */
+    xSort?: (a: DataPoint, b: DataPoint) => number;
+    /** Key, index, or accessor function for y-axis values. */
+    y?: string | number | ((...args: unknown[]) => unknown);
+    /** Configuration for the y-axis. */
+    yConfig?: AxisConfig;
+    /** Custom sort function for y-axis values. */
+    ySort?: (a: DataPoint, b: DataPoint) => number;
+    /** Set to false to disable zooming on geomaps. */
+    zoom?: false;
+    /** Allows additional custom properties. */
+    [key: string]: unknown;
+}
+export {};

package/types/src/utils/RESET.d.ts

@@ -0,0 +1,3 @@
+/** String constant used to reset an individual config property. */
+declare const RESET: string;
+export default RESET;

package/types/src/utils/accessor.d.ts

@@ -0,0 +1,13 @@
+import type { DataPoint } from "@d3plus/data";
+/**
+    Wraps an object key in a simple accessor function.
+    @param key The key to be returned from each Object passed to the function.
+    @param def A default value to be returned if the key is not present.
+    @example <caption>this</caption>
+accessor("id");
+    @example <caption>returns this</caption>
+function(d) {
+  return d["id"];
+}
+*/
+export default function accessor(key: string, def?: DataPoint[keyof DataPoint]): (d: DataPoint) => DataPoint[keyof DataPoint];

package/types/src/utils/configPrep.d.ts

@@ -0,0 +1,28 @@
+import type { DataPoint } from "@d3plus/data";
+import { D3plusConfig } from "./D3plusConfig";
+interface D3PlusWrapped {
+    __d3plus__?: boolean;
+    __d3plusParent__?: D3PlusWrapped;
+    data?: DataPoint;
+    feature?: DataPoint;
+    i?: number;
+    [key: string]: unknown;
+}
+type DataAccessor = (d: DataPoint, i: number, s?: D3PlusWrapped, e?: Event) => DataPoint[keyof DataPoint];
+interface ConfigObject extends D3plusConfig {
+    [key: string]: unknown;
+}
+export interface VizContext {
+    _shapeConfig: ConfigObject;
+    _duration: number;
+    _on: Record<string, DataAccessor>;
+    [key: string]: unknown;
+}
+/**
+    Preps a config object for d3plus data, and optionally bubbles up a specific nested type. When using this function, you must bind a d3plus class' `this` context.
+    @param config The configuration object to parse.
+    @param type The event classifier to user for "on" events. For example, the default event type of "shape" will apply all events in the "on" config object with that key, like "click.shape" and "mouseleave.shape", in addition to any gloval events like "click" and "mouseleave".
+    @param nest An optional nested key to bubble up to the parent config level.
+*/
+export default function configPrep(this: VizContext, config?: ConfigObject, type?: string, nest?: string | false): ConfigObject;
+export {};

package/types/src/utils/constant.d.ts

@@ -0,0 +1,11 @@
+/**
+    Wraps non-function variables in a simple return function.
+    @param value The value to wrap in a return function.
+    @example <caption>this</caption>
+constant(42);
+    @example <caption>returns this</caption>
+function() {
+  return 42;
+}
+*/
+export default function <T>(value: T): () => T;

package/types/src/utils/getProp.d.ts

@@ -0,0 +1,9 @@
+import type { DataPoint } from "@d3plus/data";
+/**
+    @module getProp
+    @param type
+    @param d
+    @param i
+    @private
+*/
+export default function getProp(this: Record<string, (d: DataPoint, i: number) => DataPoint[keyof DataPoint]>, type: string, d: DataPoint, i: number): DataPoint[keyof DataPoint];

package/types/src/utils/index.d.ts

@@ -0,0 +1,8 @@
+export type { AccessorFn } from "./AccessorFn.js";
+export { default as accessor } from "./accessor.js";
+export { default as BaseClass } from "./BaseClass.js";
+export type { D3plusConfig, AxisConfig, TooltipConfig } from "./D3plusConfig.js";
+export { default as configPrep } from "./configPrep.js";
+export { default as constant } from "./constant.js";
+export { default as getProp } from "./getProp.js";
+export { default as RESET } from "./RESET.js";