@d3plus/core 3.0.16 → 3.1.1

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

@@ -0,0 +1,124 @@
+import type { DataPoint } from "@d3plus/data";
+import type { D3Selection } from "@d3plus/dom";
+import type { AccessorFn } from "../utils/index.js";
+/**
+    Creates SVG images based on an array of data.
+    @example <caption>a sample row of data</caption>
+var data = {"url": "file.png", "width": "100", "height": "50"};
+@example <caption>passed to the generator</caption>
+new Image().data([data]).render();
+@example <caption>creates the following</caption>
+<image class="d3plus-Image" opacity="1" href="file.png" width="100" height="50" x="0" y="0"></image>
+@example <caption>this is shorthand for the following</caption>
+image().data([data])();
+@example <caption>which also allows a post-draw callback function</caption>
+image().data([data])(function() { alert("draw complete!"); })
+*/
+export default class Image {
+    _duration: number;
+    _height: AccessorFn;
+    _id: AccessorFn;
+    _opacity: AccessorFn;
+    _pointerEvents: AccessorFn;
+    _select: D3Selection;
+    _url: AccessorFn;
+    _width: AccessorFn;
+    _x: AccessorFn;
+    _y: AccessorFn;
+    _data: DataPoint[];
+    /**
+        Invoked when creating a new class instance, and sets any default parameters.
+        @private
+  */
+    constructor();
+    /**
+        Renders the current Image to the page. If a *callback* is specified, it will be called once the images are done drawing.
+      @param callback Optional callback invoked after rendering completes.
+  */
+    render(callback?: () => void): this;
+    /**
+        The data array used to create image shapes. An <image> tag will be drawn for each object in the array.
+  */
+    data(): DataPoint[];
+    data(_: DataPoint[]): this;
+    /**
+        The animation duration in milliseconds.
+  */
+    duration(): number;
+    duration(_: number): this;
+    /**
+        The height accessor for each image.
+  
+  @example
+  function(d) {
+    return d.height;
+  }
+  */
+    height(): AccessorFn;
+    height(_: AccessorFn | number): this;
+    /**
+        The unique id accessor for each image.
+  
+  @example
+  function(d) {
+    return d.id;
+  }
+  */
+    id(): AccessorFn;
+    id(_: AccessorFn): this;
+    /**
+        The opacity of each image.
+  */
+    opacity(): AccessorFn;
+    opacity(_: AccessorFn | number): this;
+    /**
+        The pointer-events.
+  */
+    pointerEvents(): AccessorFn;
+    pointerEvents(_: AccessorFn | string): this;
+    /**
+        The SVG container element as a d3 selector or DOM element.
+  */
+    select(): D3Selection;
+    select(_: string | HTMLElement | SVGElement | null): this;
+    /**
+        Accessor function for the URL of each image.
+  
+  @example
+  function(d) {
+    return d.url;
+  }
+  */
+    url(): AccessorFn;
+    url(_: AccessorFn): this;
+    /**
+        The width accessor for each image.
+  
+  @example
+  function(d) {
+    return d.width;
+  }
+  */
+    width(): AccessorFn;
+    width(_: AccessorFn | number): this;
+    /**
+        The x position accessor for each image.
+  
+  @example
+  function(d) {
+    return d.x || 0;
+  }
+  */
+    x(): AccessorFn;
+    x(_: AccessorFn | number): this;
+    /**
+        The y position accessor for each image.
+  
+  @example
+  function(d) {
+    return d.y || 0;
+  }
+  */
+    y(): AccessorFn;
+    y(_: AccessorFn | number): this;
+}

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

@@ -0,0 +1,48 @@
+import type { DataPoint } from "@d3plus/data";
+import type { AccessorFn } from "../utils/index.js";
+import Shape, { type ShapeAes } from "./Shape.js";
+/**
+    Creates SVG lines based on an array of data.
+*/
+export default class Line extends Shape {
+    _curve: AccessorFn;
+    _defined: AccessorFn;
+    _fill: AccessorFn;
+    _hitArea: ((d: DataPoint, i: number, aes: ShapeAes) => Record<string, unknown>) | null;
+    _name: string;
+    _path: Record<string, unknown>;
+    _stroke: AccessorFn;
+    _strokeWidth: AccessorFn;
+    _strokeDasharray: AccessorFn;
+    /**
+        Invoked when creating a new class instance, and overrides any default parameters inherited from Shape.
+        @private
+  */
+    constructor();
+    /**
+        Filters/manipulates the data array before binding each point to an SVG group.
+        @param data @private
+  */
+    _dataFilter(data: DataPoint[]): DataPoint[];
+    /**
+        Draws the lines.
+      @param callback Optional callback invoked after rendering completes.
+  */
+    render(callback?: () => void): this;
+    /**
+        Given a specific data point and index, returns the aesthetic properties of the shape.
+        @param data point*
+        @param index @private
+  */
+    _aes(d: DataPoint, i: number): ShapeAes;
+    /**
+        The d3 curve function used to interpolate the line.
+  */
+    curve(): AccessorFn;
+    curve(_: AccessorFn | string): this;
+    /**
+        An accessor function that determines whether a data point is defined (not a gap in the line).
+  */
+    defined(): AccessorFn;
+    defined(_: AccessorFn): this;
+}

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

@@ -0,0 +1,38 @@
+import type { DataPoint } from "@d3plus/data";
+import type { AccessorFn } from "../utils/index.js";
+import Shape, { type ShapeAes } from "./Shape.js";
+/**
+    Creates SVG Paths based on an array of data.
+*/
+export default class Path extends Shape {
+    _d: AccessorFn;
+    _labelBounds: ((d: DataPoint, i: number, aes: ShapeAes) => Record<string, unknown> | null | false) | null;
+    _name: string;
+    _labelConfig: Record<string, unknown>;
+    /**
+        Invoked when creating a new class instance, and overrides any default parameters inherited from Shape.
+        @private
+  */
+    constructor();
+    /**
+        Given a specific data point and index, returns the aesthetic properties of the shape.
+        @param data point*
+        @param index @private
+  */
+    _aes(d: DataPoint, i: number): ShapeAes;
+    /**
+        Draws the paths.
+      @param callback Optional callback invoked after rendering completes.
+  */
+    render(callback?: () => void): this;
+    /**
+        The "d" attribute.
+  
+  @example
+  function(d) {
+    return d.path;
+  }
+  */
+    d(): AccessorFn;
+    d(_: AccessorFn | string): this;
+}

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

@@ -0,0 +1,54 @@
+import type { DataPoint } from "@d3plus/data";
+import type { D3Selection } from "@d3plus/dom";
+import type { AccessorFn } from "../utils/index.js";
+import Shape, { type ShapeAes } from "./Shape.js";
+/**
+    Creates SVG rectangles based on an array of data. See [this example](https://d3plus.org/examples/d3plus-shape/getting-started/) for help getting started using the rectangle generator.
+*/
+export default class Rect extends Shape {
+    _height: AccessorFn;
+    _labelBounds: ((d: DataPoint, i: number, aes: ShapeAes) => Record<string, unknown> | null | false) | null;
+    _name: string;
+    _width: AccessorFn;
+    /**
+        Invoked when creating a new class instance, and overrides any default parameters inherited from Shape.
+        @private
+  */
+    constructor();
+    /**
+        Draws the rectangles.
+      @param callback Optional callback invoked after rendering completes.
+  */
+    render(callback?: () => void): this;
+    /**
+        Given a specific data point and index, returns the aesthetic properties of the shape.
+        @param data point*
+        @param index @private
+  */
+    _aes(d: DataPoint, i: number): ShapeAes;
+    /**
+        Provides the default positioning to the <rect> elements.
+        @param elem @private
+  */
+    _applyPosition(elem: D3Selection): void;
+    /**
+        The height accessor for each rectangle.
+  
+  @example
+  function(d) {
+    return d.height;
+  }
+  */
+    height(): AccessorFn;
+    height(_: AccessorFn | number): this;
+    /**
+        The width accessor for each rectangle.
+  
+  @example
+  function(d) {
+    return d.width;
+  }
+  */
+    width(): AccessorFn;
+    width(_: AccessorFn | number): this;
+}

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

@@ -0,0 +1,378 @@
+import { transition } from "d3-transition";
+import type { DataPoint } from "@d3plus/data";
+import type { D3Selection } from "@d3plus/dom";
+import { TextBox } from "../components/index.js";
+import { BaseClass } from "../utils/index.js";
+import type { AccessorFn } from "../utils/index.js";
+export interface ShapeAes {
+    width?: number;
+    height?: number;
+    points?: [number, number][];
+    r?: number;
+    x?: number;
+    y?: number;
+}
+import Image from "./Image.js";
+/**
+    An abstracted class for generating shapes.
+*/
+export default class Shape extends BaseClass {
+    _activeOpacity: number;
+    _activeStyle: Record<string, unknown>;
+    _ariaLabel: AccessorFn;
+    _backgroundImage: AccessorFn;
+    _backgroundImageClass: Image;
+    _data: DataPoint[];
+    _duration: number;
+    _fill: AccessorFn;
+    _fillOpacity: AccessorFn;
+    _hoverOpacity: number;
+    _hoverStyle: Record<string, unknown>;
+    _id: AccessorFn;
+    _label: AccessorFn;
+    _labelClass: TextBox;
+    _labelConfig: Record<string, unknown>;
+    _labelBounds: ((d: DataPoint, i: number, aes: ShapeAes) => Record<string, unknown> | null | false) | null;
+    _name: string;
+    _opacity: AccessorFn;
+    _pointerEvents: AccessorFn;
+    _role: AccessorFn;
+    _rotate: AccessorFn;
+    _rx: AccessorFn;
+    _ry: AccessorFn;
+    _scale: AccessorFn;
+    _shapeRendering: AccessorFn;
+    _stroke: AccessorFn;
+    _strokeDasharray: AccessorFn;
+    _strokeLinecap: AccessorFn;
+    _strokeOpacity: AccessorFn;
+    _strokeWidth: AccessorFn;
+    _tagName: string;
+    _textAnchor: AccessorFn;
+    _texture: AccessorFn;
+    _textureDefault: Record<string, unknown>;
+    _textureDefs: Record<string, Record<string, unknown>>;
+    _vectorEffect: AccessorFn;
+    _verticalAlign: AccessorFn;
+    _x: AccessorFn;
+    _y: AccessorFn;
+    _select: D3Selection;
+    _transition: ReturnType<typeof transition>;
+    /** @param data The raw data array to filter. */
+    _dataFilter?(data: DataPoint[]): DataPoint[];
+    _sort: ((a: DataPoint, b: DataPoint) => number) | null;
+    _group: D3Selection;
+    _update: D3Selection;
+    _enter: D3Selection;
+    _exit: D3Selection;
+    _hoverGroup: D3Selection;
+    _activeGroup: D3Selection;
+    _hitArea: ((d: DataPoint, i: number, aes: ShapeAes) => Record<string, unknown>) | null;
+    _active: ((d: DataPoint, i: number) => boolean) | null;
+    _hover: ((d: DataPoint, i: number) => boolean) | null;
+    _discrete: string | undefined;
+    _path: Record<string, unknown>;
+    _defined: AccessorFn;
+    _curve: AccessorFn;
+    /**
+        Invoked when creating a new class instance, and sets any default parameters.
+        @private
+  */
+    constructor(tagName?: string);
+    /**
+        Given a specific data point and index, returns the aesthetic properties of the shape.
+        @param data point*
+        @param index @private
+  */
+    _aes(_d?: DataPoint, _i?: number): ShapeAes;
+    /**
+        Adds event listeners to each shape group or hit area.
+        @private
+  */
+    _applyEvents(handler: D3Selection): void;
+    /**
+        Provides the updated styling to the given shape elements.
+  
+        @private
+  */
+    _updateStyle(elem: D3Selection, style: Record<string, unknown>): void;
+    /**
+        Provides the default styling to the shape elements.
+        @param elem @private
+  */
+    _applyStyle(elem: D3Selection): void;
+    /**
+        Calculates the transform for the group elements.
+        @param elem @private
+  */
+    _applyTransform(elem: D3Selection): void;
+    /**
+        Returns a full JSON string of the texture config for a given data point.
+  
+        @private
+  */
+    _getTextureKey(d: DataPoint, i: number): string | false;
+    /**
+        Checks for nested data and uses the appropriate variables for accessor functions.
+        @param elem @private
+  */
+    _nestWrapper(method: AccessorFn): (d: DataPoint, i: number) => DataPoint[keyof DataPoint];
+    /**
+        Modifies existing shapes to show active status.
+        @private
+  */
+    _renderActive(): void;
+    /**
+        Modifies existing shapes to show hover status.
+        @private
+  */
+    _renderHover(): void;
+    /**
+        Adds background image to each shape group.
+        @private
+  */
+    _renderImage(): void;
+    /**
+        Adds labels to each shape group.
+        @private
+  */
+    _renderLabels(): void;
+    /**
+        Renders the current Shape to the page. If a *callback* is specified, it will be called once the shapes are done drawing.
+      @param callback Optional callback invoked after rendering completes.
+  */
+    render(callback?: () => void): this;
+    /**
+        The active callback function for highlighting shapes.
+  */
+    active(): ((d: DataPoint, i: number) => boolean) | null;
+    active(_: ((d: DataPoint, i: number) => boolean) | null): this;
+    /**
+        When shapes are active, this is the opacity of any shape that is not active.
+  */
+    activeOpacity(): number;
+    activeOpacity(_: number): this;
+    /**
+        The style to apply to active shapes.
+  */
+    activeStyle(): Record<string, unknown>;
+    activeStyle(_: Record<string, unknown>): this;
+    /**
+        The aria-label attribute for each shape.
+  */
+    ariaLabel(): AccessorFn;
+    ariaLabel(_: AccessorFn | string): this;
+    /**
+        The background-image accessor for each shape.
+  */
+    backgroundImage(): AccessorFn;
+    backgroundImage(_: AccessorFn | string): this;
+    /**
+        The data array used to create shapes. A shape will be drawn for each object in the array.
+  */
+    data(): DataPoint[];
+    data(_: DataPoint[]): this;
+    /**
+        Determines if either the X or Y position is discrete along a Line, which helps in determining the nearest data point on a line for a hit area event.
+  */
+    discrete(): string | undefined;
+    discrete(_: string): this;
+    /**
+        The animation duration in milliseconds.
+  */
+    duration(): number;
+    duration(_: number): this;
+    /**
+        The fill color accessor for each shape.
+  */
+    fill(): AccessorFn;
+    fill(_: AccessorFn | string): this;
+    /**
+        Defines the "fill-opacity" attribute for the shapes.
+  */
+    fillOpacity(): AccessorFn;
+    fillOpacity(_: AccessorFn | number): this;
+    /**
+        The hover callback function for highlighting shapes on mouseover.
+  */
+    hover(): ((d: DataPoint, i: number) => boolean) | null;
+    hover(_: ((d: DataPoint, i: number) => boolean) | null): this;
+    /**
+        The style to apply to hovered shapes.
+  */
+    hoverStyle(): Record<string, unknown>;
+    hoverStyle(_: Record<string, unknown>): this;
+    /**
+        The opacity of non-hovered shapes when any shape is hovered.
+  */
+    hoverOpacity(): number;
+    hoverOpacity(_: number): this;
+    /**
+        The mouse hit area accessor function.
+        @example
+  function(d, i, shape) {
+    return {
+      "width": shape.width,
+      "height": shape.height,
+      "x": -shape.width / 2,
+      "y": -shape.height / 2
+    };
+  }
+  */
+    hitArea(): ((d: DataPoint, i: number, aes: Record<string, unknown>) => Record<string, unknown>) | null;
+    hitArea(_: ((d: DataPoint, i: number, aes: Record<string, unknown>) => Record<string, unknown>) | Record<string, unknown>): this;
+    /**
+        The unique id accessor for each shape.
+  */
+    id(): AccessorFn;
+    id(_: AccessorFn): this;
+    /**
+        The text label accessor for each shape.
+  */
+    label(): AccessorFn;
+    label(_: AccessorFn | string | string[]): this;
+    /**
+        The label bounds accessor function.
+        @example
+  function(d, i, shape) {
+    return {
+      "width": shape.width,
+      "height": shape.height,
+      "x": -shape.width / 2,
+      "y": -shape.height / 2
+    };
+  }
+  */
+    labelBounds(): ((d: DataPoint, i: number, aes: Record<string, unknown>) => Record<string, unknown> | null | false) | null;
+    labelBounds(_: ((d: DataPoint, i: number, aes: Record<string, unknown>) => Record<string, unknown> | null | false) | Record<string, unknown>): this;
+    /**
+        A pass-through to the config method of the TextBox class used to create a shape's labels.
+  */
+    labelConfig(): Record<string, unknown>;
+    labelConfig(_: Record<string, unknown>): this;
+    /**
+        The opacity accessor for each shape.
+  */
+    opacity(): AccessorFn;
+    opacity(_: AccessorFn | number): this;
+    /**
+        The pointer-events CSS property for each shape.
+  */
+    pointerEvents(): AccessorFn;
+    pointerEvents(_: AccessorFn | string): this;
+    /**
+        The role attribute.
+  */
+    role(): AccessorFn;
+    role(_: AccessorFn | string): this;
+    /**
+        The rotation angle in degrees for each shape.
+  */
+    rotate(): AccessorFn;
+    rotate(_: AccessorFn | number): this;
+    /**
+        Defines the "rx" attribute for the shapes.
+  */
+    rx(): AccessorFn;
+    rx(_: AccessorFn | number): this;
+    /**
+        Defines the "rx" attribute for the shapes.
+  */
+    ry(): AccessorFn;
+    ry(_: AccessorFn | number): this;
+    /**
+        The scale transform accessor for each shape.
+  */
+    scale(): AccessorFn;
+    scale(_: AccessorFn | number): this;
+    /**
+        The SVG container element as a d3 selector or DOM element.
+  */
+    select(): D3Selection;
+    select(_: string | HTMLElement | SVGElement | null): this;
+    /**
+        The shape-rendering.
+  
+  @example
+  function(d) {
+    return d.x;
+  }
+  */
+    shapeRendering(): AccessorFn;
+    shapeRendering(_: AccessorFn | string): this;
+    /**
+        A comparator function used to sort shapes for layering order.
+  */
+    sort(): ((a: DataPoint, b: DataPoint) => number) | null;
+    sort(_: ((a: DataPoint, b: DataPoint) => number) | null): this;
+    /**
+        The stroke color accessor for each shape.
+  */
+    stroke(): AccessorFn;
+    stroke(_: AccessorFn | string): this;
+    /**
+        Defines the "stroke-dasharray" attribute for the shapes.
+  */
+    strokeDasharray(): AccessorFn;
+    strokeDasharray(_: AccessorFn | string): this;
+    /**
+        Defines the "stroke-linecap" attribute for the shapes. Accepted values are `"butt"`, `"round"`, and `"square"`.
+  */
+    strokeLinecap(): AccessorFn;
+    strokeLinecap(_: AccessorFn | string): this;
+    /**
+        Defines the "stroke-opacity" attribute for the shapes.
+  */
+    strokeOpacity(): AccessorFn;
+    strokeOpacity(_: AccessorFn | number): this;
+    /**
+        The stroke-width.
+  */
+    strokeWidth(): AccessorFn;
+    strokeWidth(_: AccessorFn | number): this;
+    /**
+        The text-anchor.
+  */
+    textAnchor(): AccessorFn;
+    textAnchor(_: AccessorFn | string): this;
+    /**
+        Defines the texture used inside of each shape. This uses the [textures.js](https://riccardoscalco.it/textures/) package, and expects either a simple string (`"lines"` or `"circles"`) or a more complex Object containing the various properties of the texture (ie. `{texture: "lines", orientation: "3/8", stroke: "darkorange"}`). If multiple textures are necessary, provide an accsesor Function that returns the correct String/Object for each given data point and index.
+  */
+    texture(): AccessorFn;
+    texture(_: AccessorFn | string | Record<string, unknown>): this;
+    /**
+        A series of global texture methods to be used for all textures (ie. `{stroke: "darkorange", strokeWidth: 2}`).
+  */
+    textureDefault(): Record<string, unknown>;
+    textureDefault(_: Record<string, unknown>): this;
+    /**
+        The vector-effect.
+  */
+    vectorEffect(): AccessorFn;
+    vectorEffect(_: AccessorFn | string): this;
+    /**
+        The vertical alignment.
+  */
+    verticalAlign(): AccessorFn;
+    verticalAlign(_: AccessorFn | string): this;
+    /**
+        The x position accessor for each shape.
+  
+  @example
+  function(d) {
+    return d.x;
+  }
+  */
+    x(): AccessorFn;
+    x(_: AccessorFn | number): this;
+    /**
+        The y position accessor for each shape.
+  
+  @example
+  function(d) {
+    return d.y;
+  }
+  */
+    y(): AccessorFn;
+    y(_: AccessorFn | number): this;
+}