Skip to content

Spacing ​

The Spacing family holds the ways spread sets its neighbors apart along dir. A spacing is a value of spread's spacing option, beside a bare amount. Spacing.box(gap) leaves a gap between the facing edges of each child's box. Spacing.pitch(distance, { at }) puts the same point on each child a fixed distance from the last one. The spacing of Constraint.distribute takes the same values.

ts
import { Spacing, Unit, chart, datum, field, rect, ribbon, scatter, spread } from "gofish-graphics";
import { seattleWeather } from "./dataset";

const monthNames = [
  "Jan",
  "Feb",
  "Mar",
  "Apr",
  "May",
  "Jun",
  "Jul",
  "Aug",
  "Sep",
  "Oct",
  "Nov",
  "Dec",
];

const binWidth = 2.5;

const temps = seattleWeather.map((d) => d.temp_max);

const minTemp = Math.floor(Math.min(...temps) / binWidth) * binWidth;

const maxTemp = Math.ceil(Math.max(...temps) / binWidth) * binWidth;

const binCount = Math.round((maxTemp - minTemp) / binWidth);

const binCenters = Array.from(
  { length: binCount },
  (_, i) => minTemp + (i + 0.5) * binWidth
);

const counts = new Map<string, number>();

const ridgelineData = monthNames.flatMap((month) =>
  binCenters.map((temp_max, bin) => ({
    month,
    temp_max,
    count: counts.get(`${month}|${bin}`) ?? 0,
  }))
);

const rowPitch = 24;

const ridgeHeight = 140;

const container = document.getElementById("app");

chart(ridgelineData, {
  axes: { x: true, y: false },
  schema: { temp_max: { name: "Max temperature", unit: Unit("°C") } },
  w: 500,
})
  .flow(
    spread({
      by: field("month").sort(monthNames),
      dir: "y",
      spacing: Spacing.pitch(rowPitch, { at: "baseline" }),
    }),
    scatter({ x: "temp_max", h: ridgeHeight })
  )
  .mark(
    ribbon({
      h: "count",
      fill: "steelblue",
      stroke: "white",
      strokeWidth: 1,
      opacity: 0.85,
      blendMode: "normal",
    })
  )
  // Per-row baseline labeling, in the style of a ggridges ridgeline: a
  // thin rule along each month's baseline with the month name to the
  // LEFT of the plot (tick-label style), instead of a standard y axis
  // that can't line up with 12 overlapping, unevenly-tall silhouettes.
  // The rules are the same fixed-pitch baseline spread as the ridges, a
  // bare rect per month, so each registers exactly on its ribbon's zero
  // line. Each rule spans the ribbon's run, from the first bin's center
  // to the last's, so the ribbon's white outline lies along the whole
  // rule. Each rule carries its month as a label outside its left end,
  // standing on the rule. `.zOrder(-1)` paints the rules BEHIND the
  // ribbons, visible only outside the silhouettes, the classic look.
  .layer(
    chart(monthNames.map((month) => ({ month })))
      .flow(
        spread({
          by: field("month").sort(monthNames),
          dir: "y",
          spacing: Spacing.pitch(rowPitch, { at: "baseline" }),
        })
      )
      .mark(
        rect({
          x: datum(binCenters[0]),
          w: datum(binCenters[binCount - 1] - binCenters[0]),
          h: 1,
          fill: "#999",
        }).label("month", {
          position: "outset-left-end",
          fontSize: 11,
          color: "#666",
        })
      )
      .zOrder(-1)
  )
  .render(container);
Dataset
ts
export type SeattleWeather = {
  date: string;
  precipitation: number;
  temp_max: number;
  temp_min: number;
  wind: number;
  weather: string;
};
export const seattleWeather: SeattleWeather[] = [
  { date: "2012-01-01T00:00:00.000Z", precipitation: 0, temp_max: 12.8, temp_min: 5, wind: 4.7, weather: "drizzle" },
  { date: "2012-01-02T00:00:00.000Z", precipitation: 10.9, temp_max: 10.6, temp_min: 2.8, wind: 4.5, weather: "rain" },
  { date: "2012-01-03T00:00:00.000Z", precipitation: 0.8, temp_max: 11.7, temp_min: 7.2, wind: 2.3, weather: "rain" },
  { date: "2012-01-04T00:00:00.000Z", precipitation: 20.3, temp_max: 12.2, temp_min: 5.6, wind: 4.7, weather: "rain" },
  { date: "2012-01-05T00:00:00.000Z", precipitation: 1.3, temp_max: 8.9, temp_min: 2.8, wind: 6.1, weather: "rain" },
  // … 1,456 more rows
];

Signature ​

ts
spread({ dir, spacing: Spacing.box(gap) });
spread({ dir, spacing: Spacing.pitch(distance, { at? }) });
spread({ dir, spacing: gap }); // the same as Spacing.box(gap)

A bare amount is Spacing.box(amount): spacing: 8 and spacing: Spacing.box(8) lay the children out the same way. The amount is a number of pixels, percent(n), or fr(k), in both members.

A spacing is a plain object, { kind, ...params }, of type Spacing.Spacing, for example { kind: "pitch", distance: 36, at: "baseline" }. The same object is the spacing's wire form.

The family is also a module of its own:

ts
import { Spacing } from "gofish-graphics";
import { pitch } from "gofish-graphics/spacing"; // the same function as Spacing.pitch

Members ​

MemberMeasures fromToDepends on the children's sizes
Spacing.box()the end of one child's boxthe start of the next child's boxyes
Spacing.pitch()the point at on one childthe point at on the next childno

at is "start", "middle", "end" or "baseline". "middle" is center to center. "baseline" is each child's local 0, which for a ribbon or a text is its baseline, not an edge of its box.

Spacing.box() ​

OptionTypeDefaultDescription
gapnumber | LengthRequired. The gap between facing edges, in pixels. A negative gap overlaps the children. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.

Spacing.pitch() ​

OptionTypeDefaultDescription
distancenumber | LengthRequired. The distance between the points, in pixels. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.
at"start" | "middle" | "end" | "baseline""baseline"The point on each child: the start of its box, its middle, the end of its box, or its baseline (its local 0). "middle" is center to center.

Example ​

ts
// Rows 36 px apart, baseline to baseline, whatever each row's height.
spread({
  by: "month",
  dir: "y",
  spacing: Spacing.pitch(36, { at: "baseline" }),
});

// Nodes as points: centers 70 units apart.
spread({ dir: "y", spacing: Spacing.pitch(70, { at: "middle" }) }, nodes);

// Columns with a 10 px gap between their edges.
spread({ by: "letter", dir: "x", spacing: Spacing.box(10) });

See also ​