top-level clip option (#1792)

Author: mbostock

docs/features/plots.md

@@ -270,6 +270,8 @@ Unitless numbers ([quirky lengths](https://www.w3.org/TR/css-values-4/#deprecate
 
 The generated SVG element has a class name which applies a default stylesheet. Use the top-level **className** option to specify that class name.
 
+The **clip** option <VersionBadge pr="1792" /> determines the default clipping behavior if the [mark **clip** option](./marks.md#mark-options) is not specified; set it to true to enable clipping. This option does not affect [axis](../marks/axis.md), [grid](../marks/grid.md), and [frame](../marks/frame.md) marks, whose **clip** option defaults to false.
+
 The **document** option specifies the [document](https://developer.mozilla.org/en-US/docs/Web/API/Document) used to create plot elements. It defaults to window.document, but can be changed to another document, say when using a virtual DOM implementation for server-side rendering in Node.
 
 ## plot(*options*) {#plot}

src/context.d.ts

@@ -1,4 +1,5 @@
 import type {GeoStreamWrapper} from "d3";
+import type {MarkOptions} from "./mark.js";
 
 /** Additional rendering context provided to marks and initializers. */
 export interface Context {
@@ -16,4 +17,7 @@ export interface Context {
 
   /** The current projection, if any. */
   projection?: GeoStreamWrapper;
+
+  /** The default clip for all marks. */
+  clip?: MarkOptions["clip"];
 }

src/context.js

@@ -1,8 +1,9 @@
 import {creator, select} from "d3";
+import {maybeClip} from "./style.js";
 
 export function createContext(options = {}) {
-  const {document = typeof window !== "undefined" ? window.document : undefined} = options;
-  return {document};
+  const {document = typeof window !== "undefined" ? window.document : undefined, clip} = options;
+  return {document, clip: maybeClip(clip)};
 }
 
 export function create(name, {document}) {

src/mark.js

@@ -22,7 +22,7 @@ export class Mark {
       marginRight = margin,
       marginBottom = margin,
       marginLeft = margin,
-      clip,
+      clip = defaults?.clip,
       channels: extraChannels,
       tip,
       render

src/marks/axis.js

@@ -564,6 +564,7 @@ function axisMark(mark, k, ariaLabel, data, options, initialize) {
     channels = {};
   }
   m.ariaLabel = ariaLabel;
+  if (m.clip === undefined) m.clip = false; // don’t clip axes by default
   return m;
 }
 

src/marks/frame.js

@@ -6,14 +6,16 @@ import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransfo
 const defaults = {
   ariaLabel: "frame",
   fill: "none",
-  stroke: "currentColor"
+  stroke: "currentColor",
+  clip: false
 };
 
 const lineDefaults = {
   ariaLabel: "frame",
   fill: null,
   stroke: "currentColor",
-  strokeLinecap: "square"
+  strokeLinecap: "square",
+  clip: false
 };
 
 export class Frame extends Mark {

src/plot.d.ts

@@ -1,6 +1,6 @@
 import type {ChannelValue} from "./channel.js";
 import type {LegendOptions} from "./legends.js";
-import type {Data, Markish} from "./mark.js";
+import type {Data, MarkOptions, Markish} from "./mark.js";
 import type {ProjectionFactory, ProjectionImplementation, ProjectionName, ProjectionOptions} from "./projection.js";
 import type {Scale, ScaleDefaults, ScaleName, ScaleOptions} from "./scales.js";
 
@@ -146,6 +146,9 @@ export interface PlotOptions extends ScaleDefaults {
    */
   document?: Document;
 
+  /** The default clip for all marks. */
+  clip?: MarkOptions["clip"];
+
   // scale, axis, and legend definitions
 
   /**

src/style.js

@@ -2,17 +2,8 @@ import {geoPath, group, namespaces} from "d3";
 import {create} from "./context.js";
 import {defined, nonempty} from "./defined.js";
 import {formatDefault} from "./format.js";
-import {
-  string,
-  number,
-  maybeColorChannel,
-  maybeNumberChannel,
-  maybeKeyword,
-  isNoneish,
-  isNone,
-  isRound,
-  keyof
-} from "./options.js";
+import {isNone, isNoneish, isRound, maybeColorChannel, maybeNumberChannel} from "./options.js";
+import {keyof, keyword, number, string} from "./options.js";
 import {warn} from "./warnings.js";
 
 export const offset = (typeof window !== "undefined" ? window.devicePixelRatio > 1 : typeof it === "undefined") ? 0 : 0.5; // prettier-ignore
@@ -311,13 +302,15 @@ export function* groupIndex(I, position, mark, channels) {
 export function maybeClip(clip) {
   if (clip === true) clip = "frame";
   else if (clip === false) clip = null;
-  return maybeKeyword(clip, "clip", ["frame", "sphere"]);
+  else if (clip != null) clip = keyword(clip, "clip", ["frame", "sphere"]);
+  return clip;
 }
 
 // Note: may mutate selection.node!
 function applyClip(selection, mark, dimensions, context) {
   let clipUrl;
-  switch (mark.clip) {
+  const {clip = context.clip} = mark;
+  switch (clip) {
     case "frame": {
       const {width, height, marginLeft, marginRight, marginTop, marginBottom} = dimensions;
       const id = getClipId();

test/plots/band-clip.ts

@@ -4,15 +4,8 @@ import * as d3 from "d3";
 export async function bandClip() {
   return Plot.plot({
     y: {type: "band"},
-    marks: [
-      Plot.frame(),
-      Plot.text(["A", "B", "C"], {
-        x: (d) => d,
-        y: (d) => d,
-        clip: true,
-        fontSize: 50
-      })
-    ]
+    clip: true,
+    marks: [Plot.frame(), Plot.text(["A", "B", "C"], {x: (d) => d, y: (d) => d, fontSize: 50})]
   });
 }