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

@@ -30,11 +30,11 @@ 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(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, dx, dy)
         .call(g => g.selectAll()
           .data(Z ? group(I, i => Z[i]).values() : [I])

src/marks/arrow.js

@@ -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;
@@ -65,7 +65,7 @@ export class Arrow extends Mark {
     const wingScale = headLength / 1.5;
 
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, offset + dx, offset + dy)
         .call(g => g.selectAll()
           .data(index)

src/marks/bar.js

@@ -21,7 +21,7 @@ export class AbstractBar extends Mark {
   render(index, scales, channels, dimensions) {
     const {dx, dy, rx, ry} = this;
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(this._transform, scales, dx, dy)
         .call(g => g.selectAll()
           .data(index)

src/marks/dot.js

@@ -54,7 +54,7 @@ export class Dot extends Mark {
     const [cx, cy] = applyFrameAnchor(this, dimensions);
     const circle = this.symbol === symbolCircle;
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, offset + dx, offset + dy)
         .call(g => g.selectAll()
           .data(index)

src/marks/frame.js

@@ -28,7 +28,7 @@ export class Frame extends Mark {
     const {marginTop, marginRight, marginBottom, marginLeft, width, height} = dimensions;
     const {insetTop, insetRight, insetBottom, insetLeft, dx, dy} = this;
     return create("svg:rect")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyDirectStyles, this)
         .call(applyTransform, null, null, offset + dx, offset + dy)
         .attr("x", marginLeft + insetLeft)

src/marks/image.js

@@ -64,7 +64,7 @@ export class Image extends Mark {
     const {dx, dy} = this;
     const [cx, cy] = applyFrameAnchor(this, dimensions);
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, offset + dx, offset + dy)
         .call(g => g.selectAll()
           .data(index)

src/marks/line.js

@@ -30,11 +30,11 @@ 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(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, offset + dx, offset + dy)
         .call(g => g.selectAll()
           .data(Z ? group(I, i => Z[i]).values() : [I])

src/marks/link.js

@@ -28,11 +28,11 @@ 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(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, offset + dx, offset + dy)
         .call(g => g.selectAll()
           .data(index)

src/marks/rect.js

@@ -49,7 +49,7 @@ export class Rect extends Mark {
     const {marginTop, marginRight, marginBottom, marginLeft, width, height} = dimensions;
     const {insetTop, insetRight, insetBottom, insetLeft, dx, dy, rx, ry} = this;
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, dx, dy)
         .call(g => g.selectAll()
           .data(index)

src/marks/rule.js

@@ -39,7 +39,7 @@ export class RuleX extends Mark {
     const {width, height, marginTop, marginRight, marginLeft, marginBottom} = dimensions;
     const {insetTop, insetBottom} = this;
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyTransform, X && x, null, offset, 0)
         .call(g => g.selectAll("line")
           .data(index)
@@ -82,7 +82,7 @@ export class RuleY extends Mark {
     const {width, height, marginTop, marginRight, marginLeft, marginBottom} = dimensions;
     const {insetLeft, insetRight, dx, dy} = this;
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyTransform, null, Y && y, dx, offset + dy)
         .call(g => g.selectAll("line")
           .data(index)

src/marks/text.js

@@ -63,7 +63,8 @@ export class Text extends Mark {
     const {dx, dy, rotate} = this;
     const [cx, cy] = applyFrameAnchor(this, dimensions);
     return create("svg:g")
-        .call(applyIndirectTextStyles, this, T)
+        .call(applyIndirectStyles, this, dimensions)
+        .call(applyIndirectTextStyles, this, T, dimensions)
         .call(applyTransform, x, y, offset + dx, offset + dy)
         .call(g => g.selectAll()
           .data(index)
@@ -129,7 +130,6 @@ export function textY(data, {y = identity, ...options} = {}) {
 }
 
 function applyIndirectTextStyles(selection, mark, T) {
-  applyIndirectStyles(selection, mark);
   applyAttr(selection, "text-anchor", mark.textAnchor);
   applyAttr(selection, "font-family", mark.fontFamily);
   applyAttr(selection, "font-size", mark.fontSize);

src/marks/tick.js

@@ -16,7 +16,7 @@ class AbstractTick extends Mark {
   render(index, scales, channels, dimensions) {
     const {dx, dy} = this;
     return create("svg:g")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(this._transform, scales, dx, dy)
         .call(g => g.selectAll("line")
           .data(index)

src/marks/vector.js

@@ -44,7 +44,7 @@ export class Vector extends Mark {
     const k = anchor === "start" ? 0 : anchor === "end" ? 1 : 0.5;
     return create("svg:g")
         .attr("fill", "none")
-        .call(applyIndirectStyles, this)
+        .call(applyIndirectStyles, this, dimensions)
         .call(applyTransform, x, y, offset + dx, offset + dy)
         .call(g => g.selectAll()
           .data(index)

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,7 +174,16 @@ export function applyGroupedChannelStyles(selection, {target}, {ariaLabel: AL, t
   applyTitleGroup(selection, T);
 }
 
-export function applyIndirectStyles(selection, mark) {
+// 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 applyIndirectStyles(selection, mark, {width, height, marginLeft, marginRight, marginTop, marginBottom}) {
   applyAttr(selection, "aria-label", mark.ariaLabel);
   applyAttr(selection, "aria-description", mark.ariaDescription);
   applyAttr(selection, "aria-hidden", mark.ariaHidden);
@@ -187,6 +198,17 @@ export function applyIndirectStyles(selection, mark) {
   applyAttr(selection, "stroke-dasharray", mark.strokeDasharray);
   applyAttr(selection, "shape-rendering", mark.shapeRendering);
   applyAttr(selection, "paint-order", mark.paintOrder);
+  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 applyDirectStyles(selection, mark) {