marker.ts; changing the API for marker

the second argument for markers has not been documented yet; changing it from *context* = {document} to *document*

Author: Fil

README.md

@@ -2417,7 +2417,7 @@ The following named markers are supported:
 * *circle*, equivalent to *circle-fill* - a filled circle with a white stroke and 3px radius
 * *circle-stroke* - a hollow circle with a colored stroke and a white fill and 3px radius
 
-If *marker* is true, it defaults to *circle*. If *marker* is a function, it will be called with a given *color* and must return an SVG marker element.
+If *marker* is true, it defaults to *circle*. If *marker* is a function, it will be called with a given *color* and *document* and must return an SVG marker element.
 
 The primary color of a marker is inherited from the *stroke* of the associated mark. The *arrow* marker is [automatically oriented](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/orient) such that it points in the tangential direction of the path at the position the marker is placed. The *circle* markers are centered around the given vertex. Note that lines whose curve is not *linear* (the default), markers are not necessarily drawn at the data positions given by *x* and *y*; marker placement is determined by the (possibly Bézier) path segments generated by the curve. To ensure that symbols are drawn at a given *x* and *y* position, consider using a [dot](#dot).
 

src/api.ts

@@ -68,7 +68,7 @@ type ScalesOptions = {
 /**
  * An instanciated mark
  */
-type InstanciatedMark = {
+export type InstanciatedMark = {
   initialize: (data: Data) => void;
 
   z?: ChannelOption; // copy the user option for error messages
@@ -242,14 +242,23 @@ export type LineOptions = MarkOptions & MarkerOptions;
  * A marker defines a graphic drawn on vertices of a delaunay, line or a link mark
  * @link https://github.com/observablehq/plot/blob/main/README.md#markers
  */
-type MarkerOption = string | boolean | null | undefined;
-type MarkerOptions = {
+export type MarkerOption =
+  | "none"
+  | "arrow"
+  | "dot"
+  | "circle"
+  | "circle-stroke"
+  | MarkerFunction
+  | boolean
+  | null
+  | undefined;
+export type MarkerOptions = {
   marker?: MarkerOption;
   markerStart?: MarkerOption;
   markerMid?: MarkerOption;
   markerEnd?: MarkerOption;
 };
-type MarkerFunction = (color: any, context: any) => SVGElement;
+export type MarkerFunction = (color: string, document: Context["document"]) => SVGElement;
 type MaybeMarkerFunction = MarkerFunction | null;
 
 /**
@@ -428,3 +437,18 @@ export type ArrayType = ArrayConstructor | Float32ArrayConstructor | Float64Arra
  * Type a Datum as an object, when using the field accessor
  */
 export type GenericObject = Record<string, ChannelValue>;
+
+/**
+ * A restrictive definition of D3 selections
+ */
+export type Selection = {
+  append: (name: string) => Selection;
+  attr: (name: string, value: any) => Selection;
+  call: (callback: (selection: Selection, ...args: any[]) => void, ...args: any[]) => Selection;
+  each: (callback: (d: any) => void) => Selection;
+  filter: (filter: (d: any, i: number) => boolean) => Selection;
+  property: (name: string, value: any) => Selection;
+  style: (name: string, value: any) => Selection;
+  text: (value: any) => Selection;
+  [Symbol.iterator]: () => IterableIterator<SVGElement | HTMLElement>;
+};

src/marks/marker.ts

@@ -1,12 +1,26 @@
+import type {
+  Context,
+  index,
+  InstanciatedMark,
+  MarkerFunction,
+  MarkerOption,
+  MarkerOptions,
+  Selection,
+  Series
+} from "../api.js";
+
 import {create} from "../context.js";
 
-export function markers(mark, {marker, markerStart = marker, markerMid = marker, markerEnd = marker} = {}) {
+export function markers(
+  mark: InstanciatedMark,
+  {marker, markerStart = marker, markerMid = marker, markerEnd = marker}: MarkerOptions = {}
+) {
   mark.markerStart = maybeMarker(markerStart);
   mark.markerMid = maybeMarker(markerMid);
   mark.markerEnd = maybeMarker(markerEnd);
 }
 
-function maybeMarker(marker) {
+function maybeMarker(marker: MarkerOption) {
   if (marker == null || marker === false) return null;
   if (marker === true) return markerCircleFill;
   if (typeof marker === "function") return marker;
@@ -26,8 +40,8 @@ function maybeMarker(marker) {
   throw new Error(`invalid marker: ${marker}`);
 }
 
-function markerArrow(color, context) {
-  return create("svg:marker", context)
+function markerArrow(color: string, document: Context["document"]) {
+  return create("svg:marker", {document})
     .attr("viewBox", "-5 -5 10 10")
     .attr("markerWidth", 6.67)
     .attr("markerHeight", 6.67)
@@ -38,66 +52,77 @@ function markerArrow(color, context) {
     .attr("stroke-linecap", "round")
     .attr("stroke-linejoin", "round")
     .call((marker) => marker.append("path").attr("d", "M-1.5,-3l3,3l-3,3"))
-    .node();
+    .node() as SVGElement;
 }
 
-function markerDot(color, context) {
-  return create("svg:marker", context)
+function markerDot(color: string, document: Context["document"]) {
+  return create("svg:marker", {document})
     .attr("viewBox", "-5 -5 10 10")
     .attr("markerWidth", 6.67)
     .attr("markerHeight", 6.67)
     .attr("fill", color)
     .attr("stroke", "none")
     .call((marker) => marker.append("circle").attr("r", 2.5))
-    .node();
+    .node() as SVGElement;
 }
 
-function markerCircleFill(color, context) {
-  return create("svg:marker", context)
+function markerCircleFill(color: string, document: Context["document"]) {
+  return create("svg:marker", {document})
     .attr("viewBox", "-5 -5 10 10")
     .attr("markerWidth", 6.67)
     .attr("markerHeight", 6.67)
     .attr("fill", color)
     .attr("stroke", "white")
     .attr("stroke-width", 1.5)
     .call((marker) => marker.append("circle").attr("r", 3))
-    .node();
+    .node() as SVGElement;
 }
 
-function markerCircleStroke(color, context) {
-  return create("svg:marker", context)
+function markerCircleStroke(color: string, document: Context["document"]) {
+  return create("svg:marker", {document})
     .attr("viewBox", "-5 -5 10 10")
     .attr("markerWidth", 6.67)
     .attr("markerHeight", 6.67)
     .attr("fill", "white")
     .attr("stroke", color)
     .attr("stroke-width", 1.5)
     .call((marker) => marker.append("circle").attr("r", 3))
-    .node();
+    .node() as SVGElement;
 }
 
 let nextMarkerId = 0;
 
-export function applyMarkers(path, mark, {stroke: S} = {}) {
-  return applyMarkersColor(path, mark, S && ((i) => S[i]));
+export function applyMarkers(path: Selection, mark: InstanciatedMark, {stroke: S}: {stroke?: string[]} = {}) {
+  return applyMarkersColor(path, mark, S && ((i: index) => S[i]));
 }
 
-export function applyGroupedMarkers(path, mark, {stroke: S} = {}) {
-  return applyMarkersColor(path, mark, S && (([i]) => S[i]));
+export function applyGroupedMarkers(path: Selection, mark: InstanciatedMark, {stroke: S}: {stroke?: string[]} = {}) {
+  return applyMarkersColor(path, mark, S && (([i]: Series) => S[i]));
 }
 
-function applyMarkersColor(path, {markerStart, markerMid, markerEnd, stroke}, strokeof = () => stroke) {
-  const iriByMarkerColor = new Map();
+// we're cheating typescript here by using index & Series:
+// the stroke function can be applied either on an individual or on a grouped mark;
+// the datum on the path will be either an index or a Series.
+// The stroke is either a color channel or a (non nullish) string constant.
+type StrokeAttr = (i: index & Series) => string;
+type IriColorMap = Map<string | null | undefined, string | undefined>;
+
+function applyMarkersColor(
+  path: Selection,
+  {markerStart, markerMid, markerEnd, stroke}: InstanciatedMark,
+  strokeof: StrokeAttr = () => stroke as string
+) {
+  const iriByMarkerColor = new Map<MarkerFunction, IriColorMap>();
 
-  function applyMarker(marker) {
-    return function (i) {
+  function applyMarker(marker: MarkerFunction) {
+    return function (this: SVGElement, i: index & Series) {
       const color = strokeof(i);
       let iriByColor = iriByMarkerColor.get(marker);
       if (!iriByColor) iriByMarkerColor.set(marker, (iriByColor = new Map()));
       let iri = iriByColor.get(color);
       if (!iri) {
-        const context = {document: this.ownerDocument};
-        const node = this.parentNode.insertBefore(marker(color, context), this);
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const node = this.parentNode!.insertBefore(marker(color, this.ownerDocument), this);
         const id = `plot-marker-${++nextMarkerId}`;
         node.setAttribute("id", id);
         iriByColor.set(color, (iri = `url(#${id})`));