clip: true clips the mark to the frame

closes #165

related: #181

Author: Fil

README.md

@@ -646,6 +646,7 @@ All marks support the following optional channels:
 * **title** - a tooltip (a string of text, possibly with newlines)
 * **href** - a URL to link to
 * **ariaLabel** - a short label representing the value in the accessibility tree
+* **clip** - if true, the mark is clipped to the frame’s dimensions
 
 The **fill**, **fillOpacity**, **stroke**, **strokeWidth**, **strokeOpacity**, and **opacity** options can be specified as either channels or constants. When the fill or stroke is specified as a function or array, it is interpreted as a channel; when the fill or stroke is specified as a string, it is interpreted as a constant if a valid CSS color and otherwise it is interpreted as a column name for a channel. Similarly when the fill opacity, stroke opacity, object opacity, stroke width, or radius is specified as a number, it is interpreted as a constant; otherwise it is interpreted as a channel.
 

src/marks/area.js

@@ -3,7 +3,7 @@ import {Curve} from "../curve.js";
 import {defined} from "../defined.js";
 import {Mark} from "../plot.js";
 import {indexOf, maybeZ} from "../options.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, applyGroupedChannelStyles} from "../style.js";
+import {applyClip, applyDirectStyles, applyIndirectStyles, applyTransform, applyGroupedChannelStyles} from "../style.js";
 import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
 
@@ -30,12 +30,13 @@ export class Area extends Mark {
     );
     this.curve = Curve(curve, tension);
   }
-  render(I, {x, y}, channels) {
+  render(I, {x, y}, channels, dimensions) {
     const {x1: X1, y1: Y1, x2: X2 = X1, y2: Y2 = Y1, z: Z} = channels;
     const {dx, dy} = this;
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, dx, dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(Z ? group(I, i => Z[i]).values() : [I])
           .join("path")

src/marks/arrow.js

@@ -1,7 +1,7 @@
 import {create} from "d3";
 import {radians} from "../math.js";
 import {Mark} from "../plot.js";
-import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {applyClip, applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
 import {maybeSameValue} from "./link.js";
 
 const defaults = {
@@ -44,7 +44,7 @@ export class Arrow extends Mark {
     this.insetStart = +insetStart;
     this.insetEnd = +insetEnd;
   }
-  render(index, {x, y}, channels) {
+  render(index, {x, y}, channels, dimensions) {
     const {x1: X1, y1: Y1, x2: X2 = X1, y2: Y2 = Y1, SW} = channels;
     const {dx, dy, strokeWidth, bend, headAngle, headLength, insetStart, insetEnd} = this;
     const sw = SW ? i => SW[i] : () => strokeWidth;
@@ -67,6 +67,7 @@ export class Arrow extends Mark {
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(index)
           .join("path")

src/marks/bar.js

@@ -2,7 +2,7 @@ import {create} from "d3";
 import {Mark} from "../plot.js";
 import {number} from "../options.js";
 import {isCollapsed} from "../scales.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, impliedString, applyAttr, applyChannelStyles} from "../style.js";
+import {applyClip, applyDirectStyles, applyIndirectStyles, applyTransform, impliedString, applyAttr, applyChannelStyles} from "../style.js";
 import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeIntervalX, maybeIntervalY} from "../transforms/interval.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
@@ -22,6 +22,7 @@ export class AbstractBar extends Mark {
     const {dx, dy, rx, ry} = this;
     return create("svg:g")
         .call(applyIndirectStyles, this)
+        .call(applyClip, this, dimensions)
         .call(this._transform, scales, dx, dy)
         .call(g => g.selectAll()
           .data(index)

src/marks/dot.js

@@ -2,7 +2,7 @@ import {create, path, symbolCircle} from "d3";
 import {positive} from "../defined.js";
 import {identity, maybeFrameAnchor, maybeNumberChannel, maybeSymbolChannel, maybeTuple} from "../options.js";
 import {Mark} from "../plot.js";
-import {applyChannelStyles, applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {applyClip, applyChannelStyles, applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, offset} from "../style.js";
 
 const defaults = {
   ariaLabel: "dot",
@@ -56,6 +56,7 @@ export class Dot extends Mark {
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(index)
           .join(circle ? "circle" : "path")

src/marks/frame.js

@@ -1,7 +1,7 @@
 import {create} from "d3";
 import {Mark} from "../plot.js";
 import {number} from "../options.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {applyClip, applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
 
 const defaults = {
   ariaLabel: "frame",
@@ -31,6 +31,7 @@ export class Frame extends Mark {
         .call(applyIndirectStyles, this)
         .call(applyDirectStyles, this)
         .call(applyTransform, null, null, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .attr("x", marginLeft + insetLeft)
         .attr("y", marginTop + insetTop)
         .attr("width", width - marginLeft - marginRight - insetLeft - insetRight)

src/marks/image.js

@@ -2,7 +2,7 @@ import {create} from "d3";
 import {positive} from "../defined.js";
 import {maybeFrameAnchor, maybeNumberChannel, maybeTuple, string} from "../options.js";
 import {Mark} from "../plot.js";
-import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform, applyAttr, offset, impliedString, applyFrameAnchor} from "../style.js";
+import {applyClip, applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform, applyAttr, offset, impliedString, applyFrameAnchor} from "../style.js";
 
 const defaults = {
   ariaLabel: "image",
@@ -66,6 +66,7 @@ export class Image extends Mark {
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(index)
           .join("image")

src/marks/line.js

@@ -3,7 +3,7 @@ import {Curve} from "../curve.js";
 import {defined} from "../defined.js";
 import {Mark} from "../plot.js";
 import {indexOf, identity, maybeTuple, maybeZ} from "../options.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, applyGroupedChannelStyles, offset} from "../style.js";
+import {applyClip, applyDirectStyles, applyIndirectStyles, applyTransform, applyGroupedChannelStyles, offset} from "../style.js";
 import {applyGroupedMarkers, markers} from "./marker.js";
 
 const defaults = {
@@ -30,12 +30,13 @@ export class Line extends Mark {
     this.curve = Curve(curve, tension);
     markers(this, options);
   }
-  render(I, {x, y}, channels) {
+  render(I, {x, y}, channels, dimensions) {
     const {x: X, y: Y, z: Z} = channels;
     const {dx, dy} = this;
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(Z ? group(I, i => Z[i]).values() : [I])
           .join("path")

src/marks/link.js

@@ -1,7 +1,7 @@
 import {create, path} from "d3";
 import {Curve} from "../curve.js";
 import {Mark} from "../plot.js";
-import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {applyClip, applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
 import {markers, applyMarkers} from "./marker.js";
 
 const defaults = {
@@ -28,12 +28,13 @@ export class Link extends Mark {
     this.curve = Curve(curve, tension);
     markers(this, options);
   }
-  render(index, {x, y}, channels) {
+  render(index, {x, y}, channels, dimensions) {
     const {x1: X1, y1: Y1, x2: X2 = X1, y2: Y2 = Y1} = channels;
     const {dx, dy, curve} = this;
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(index)
           .join("path")

src/marks/rect.js

@@ -2,7 +2,7 @@ import {create} from "d3";
 import {number} from "../options.js";
 import {Mark} from "../plot.js";
 import {isCollapsed} from "../scales.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, impliedString, applyAttr, applyChannelStyles} from "../style.js";
+import {applyClip, applyDirectStyles, applyIndirectStyles, applyTransform, impliedString, applyAttr, applyChannelStyles} from "../style.js";
 import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeIntervalX, maybeIntervalY} from "../transforms/interval.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
@@ -51,6 +51,7 @@ export class Rect extends Mark {
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, dx, dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(index)
           .join("rect")

src/marks/rule.js

@@ -2,7 +2,7 @@ import {create} from "d3";
 import {identity, number} from "../options.js";
 import {Mark} from "../plot.js";
 import {isCollapsed} from "../scales.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, applyChannelStyles, offset} from "../style.js";
+import {applyClip, applyDirectStyles, applyIndirectStyles, applyTransform, applyChannelStyles, offset} from "../style.js";
 import {maybeIntervalX, maybeIntervalY} from "../transforms/interval.js";
 
 const defaults = {
@@ -41,6 +41,7 @@ export class RuleX extends Mark {
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(applyTransform, X && x, null, offset, 0)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll("line")
           .data(index)
           .join("line")

src/marks/text.js

@@ -3,7 +3,7 @@ import {nonempty} from "../defined.js";
 import {formatNumber} from "../format.js";
 import {indexOf, identity, string, maybeNumberChannel, maybeTuple, numberChannel, isNumeric, isTemporal, keyword, maybeFrameAnchor, isTextual} from "../options.js";
 import {Mark} from "../plot.js";
-import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyAttr, applyTransform, offset, impliedString, applyFrameAnchor} from "../style.js";
+import {applyClip, applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyAttr, applyTransform, offset, impliedString, applyFrameAnchor} from "../style.js";
 
 const defaults = {
   ariaLabel: "text",
@@ -65,6 +65,7 @@ export class Text extends Mark {
     return create("svg:g")
         .call(applyIndirectTextStyles, this, T)
         .call(applyTransform, x, y, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(index)
           .join("text")

src/marks/tick.js

@@ -1,7 +1,7 @@
 import {create} from "d3";
 import {Mark} from "../plot.js";
 import {identity, number} from "../options.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, applyChannelStyles, offset} from "../style.js";
+import {applyClip, applyDirectStyles, applyIndirectStyles, applyTransform, applyChannelStyles, offset} from "../style.js";
 
 const defaults = {
   ariaLabel: "tick",
@@ -18,6 +18,7 @@ class AbstractTick extends Mark {
     return create("svg:g")
         .call(applyIndirectStyles, this)
         .call(this._transform, scales, dx, dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll("line")
           .data(index)
           .join("line")

src/marks/vector.js

@@ -2,7 +2,7 @@ import {create} from "d3";
 import {radians} from "../math.js";
 import {maybeFrameAnchor, maybeNumberChannel, maybeTuple, keyword} from "../options.js";
 import {Mark} from "../plot.js";
-import {applyChannelStyles, applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {applyClip, applyChannelStyles, applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, offset} from "../style.js";
 
 const defaults = {
   ariaLabel: "vector",
@@ -46,6 +46,7 @@ export class Vector extends Mark {
         .attr("fill", "none")
         .call(applyIndirectStyles, this)
         .call(applyTransform, x, y, offset + dx, offset + dy)
+        .call(applyClip, this, dimensions)
         .call(g => g.selectAll()
           .data(index)
           .join("path")

src/plot.js

@@ -6,7 +6,7 @@ import {Dimensions} from "./dimensions.js";
 import {Legends, exposeLegends} from "./legends.js";
 import {arrayify, isOptions, keyword, range, first, second, where} from "./options.js";
 import {Scales, ScaleFunctions, autoScaleRange, applyScales, exposeScales} from "./scales.js";
-import {applyInlineStyles, maybeClassName, styles} from "./style.js";
+import {applyInlineStyles, maybeClassName, maybeClip, styles} from "./style.js";
 import {basic} from "./transforms/basic.js";
 
 export function plot(options = {}) {
@@ -134,7 +134,7 @@ function filter(index, channels, values) {
 
 export class Mark {
   constructor(data, channels = [], options = {}, defaults) {
-    const {facet = "auto", sort, dx, dy} = options;
+    const {facet = "auto", sort, dx, dy, clip} = options;
     const names = new Set();
     this.data = data;
     this.sort = isOptions(sort) ? sort : null;
@@ -158,6 +158,7 @@ export class Mark {
     });
     this.dx = +dx || 0;
     this.dy = +dy || 0;
+    this.clip = maybeClip(clip);
   }
   initialize(facets, facetChannels) {
     let data = arrayify(this.data);

src/style.js

@@ -5,6 +5,8 @@ import {string, number, maybeColorChannel, maybeNumberChannel, isTemporal, isNum
 
 export const offset = typeof window !== "undefined" && window.devicePixelRatio > 1 ? 0 : 0.5;
 
+let nextClipPathId = 0;
+
 export function styles(
   mark,
   {
@@ -172,6 +174,29 @@ export function applyGroupedChannelStyles(selection, {target}, {ariaLabel: AL, t
   applyTitleGroup(selection, T);
 }
 
+// clip: true clips to the frame
+// TODO: accept other types of clips (paths, urls, x, y, other marks?…)
+// https://github.com/observablehq/plot/issues/181
+export function maybeClip(clip) {
+  if (clip === true) return "frame";
+  if (clip == null || clip === false) return false;
+  throw new Error(`clip method not implemented: ${clip}`);
+}
+
+export function applyClip(selection, mark, {width, height, marginLeft, marginRight, marginTop, marginBottom}) {
+  if (mark.clip === "frame") {
+    const id = `plot-clippath-${++nextClipPathId}`;
+    const w = width - marginRight - marginLeft;
+    const h = height - marginTop - marginBottom;
+    selection.append("clipPath")
+      .attr("id", id)
+      .append("rect")
+      .attr("width", w)
+      .attr("height", h);
+    applyAttr(selection, "clip-path", `url(#${id})`);
+  }
+}
+
 export function applyIndirectStyles(selection, mark) {
   applyAttr(selection, "aria-label", mark.ariaLabel);
   applyAttr(selection, "aria-description", mark.ariaDescription);