@humanforest/charts 0.3.7 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 Every @humanforest package shares one version, so one entry covers all seven packages. Newest first.
 
+## 0.5.0 — 2026-10-25
+
+### Breaking changes
+
+- **ui**: let a sidebar nav item carry its own badge
+
+### Features
+
+- **ui**: let a HUD card centre between its band's rails
+
+### Fixes
+
+- **ui**: keep `center` off the HUD's bottom card
+- **ui**: drop the page-level scrollbar gutter
+- **ui**: the map search glyph is sized, not padded
+
+## 0.4.0 — 2026-09-15
+
+### Features
+
+- **docs**: the llms mirror prints a section kicker under its heading
+- **frames**: FFitFrame fits a slot that sizes itself
+- **charts**: a sparkline's area fades from its line to the floor
+- **charts**: the calendar month rule boxes each month in a toned line
+- **docs**: the llms mirror heads a non-prop table by its own column
+- **docs**: the llms mirror names the module a page destructures
+- **docs**: the llms mirror renders section loops
+- **docs**: the llms mirror resolves plain strings a page imports
+- **docs**: DemoStage puts a demo's controls above the specimen
+- **docs**: the llms mirror names each code tab in a ProseCodeGroup
+- **docs**: the llms mirror renders guidance cards and imported arrays
+
+### Fixes
+
+- **ui**: the scroll fade follows content that changes after mount
+- **ui**: map drawing places a corner only for a press on the map
+- **ui**: the scale bar measures at the centre and hides off the globe
+- **ui**: geolocate stays active through a location error while tracking
+- **ui**: map search names only a rendered row in aria-activedescendant
+- **ui**: a context menu that reopens elsewhere takes focus again
+- **ui**: map overlays add layers after the frame, not during placement
+- **ui**: the map context menu wires nothing on a non-interactive map
+- **ui**: map search rings kept focus and never sends a pair to suggest
+- **ui**: fullscreen reads nothing without a fullscreen API
+- **ui**: geolocate is a plain action with track off
+- **ui**: coordinates read Mapbox's 512px world and name the copied pair
+- **docs**: chord, treemap and sankey demos keep their heights
+- **charts**: resolveVar leaves the document alone without a DOM
+- **docs**: the battery-swap stage keeps its start edge reachable
+- **docs**: foundations and layout diagrams fit a phone
+- **docs**: device frames scale down to fit a phone's pane
+- **docs**: component specimens fit a phone's preview pane
+- **filter**: the chip's number segments drop their steppers
+- **docs**: the table page's pager drops its arrows on a phone
+- **filter**: a chip wider than its bar wraps its segments
+- **tokens**: the display role steps down to 4xl below 40rem
+- **tokens**: long inline code wraps instead of overflowing its column
+- **docs**: long inline code and prop types wrap instead of widening main
+- **ui**: a vehicle mark's badge outline follows its edge
+- **ui**: ramp swatches abut and round only the ramp's ends
+- **docs**: a context switch keeps a page's live demos mounted
+- **ui**: a bound popup closes on a second click and unbinds on unmount
+- **ui**: a marker is a button only when it acts as one
+- **ui**: FMap applies every padding side and logs each map error
+- **ui**: a track slice no longer bridges a signal gap
+- **ui**: track playback keeps the playhead when the speed changes
+- **ui**: balance maps paint by magnitude, and legends label exactly
+- **charts**: the tooltip snap looks for its panel on pointer entry
+- **ui**: unavailable reasons name a state by its label
+- **ui**: zones ignore a kind they do not know
+- **ui**: a selected vehicle takes its new state on resync
+- **docs**: a cross-page anchored link lands on its target
+- **ui**: useMapReady never runs for a caller that has unmounted
+- **tokens**: area fills keep their opacity under data-theme dark
+- **charts**: crosshair dots sit on stacked band tops
+- **charts**: a fitted London map labels only the areas it draws
+- **charts**: a missing reading breaks a line sparkline
+- **charts**: a dotted map's missing values add nothing
+- **charts**: a selectable London map is reachable at every size
+- **charts**: cell tracks and grids take one Tab stop, props read live
+- **docs**: urgent vehicles draw on top of the fleet
+- **ui**: alt shortcuts select, and deleted features leave the selection
+- **ui**: a crossing edit springs back, and a drag reports once
+- **ui**: selected markers rise, popups are named, one button opens them
+- **ui**: the coordinate tile stays copyable as the pointer moves onto it
+- **ui**: the scale bar's fill is as long as the distance it names
+
 ## 0.3.7 — 2026-09-13
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanforest/charts",
-  "version": "0.3.7",
+  "version": "0.5.0",
   "type": "module",
   "files": [
     "src",
@@ -29,7 +29,7 @@
     "vue": "^3.5.22"
   },
   "dependencies": {
-    "@humanforest/tokens": "^0.3.7"
+    "@humanforest/tokens": "^0.5.0"
   },
   "publishConfig": {
     "access": "public"

package/src/FCalendarGrid.vue

@@ -1,14 +1,16 @@
 <script setup lang="ts" generic="D extends Record<string, unknown>">
-// Days as cells: weeks are columns, weekdays are rows. A year of ride volume, or a year of one
-// station's daily state. Colour resolution is useCellScale's; this component owns the calendar.
+// Days as cells: weeks are columns, weekdays are rows. A year of trip volume, or a year of one
+// parking place's daily state. Colour resolution is useCellScale's; this component owns the
+// calendar.
 //
 // The grid is built from the date window, not from the data, so a day with no datum is a real empty
 // cell in the right place rather than a missing column. Days are bucketed by local calendar date —
 // a timestamp is floored to its day before lookup, so two events on one day land together.
 import { computed, ref } from 'vue';
 import type { BulletLegendItemInterface } from '@unovis/ts';
-import { useCellScale, CELL_EMPTY_COLOR, type SequentialRamp } from './useCellScale';
+import { useCellScaleProps, CELL_EMPTY_COLOR, type SequentialRamp } from './useCellScale';
 import { CELL_SIZES, orElse, type CellSize } from './cellSize';
+import { rovingIndex } from './rovingFocus';
 import FCellLegend from './FCellLegend.vue';
 
 const props = withDefaults(
@@ -39,13 +41,15 @@ const props = withDefaults(
     cellGap?: number;
     radius?: number;
     monthLabels?: boolean;
-    /** Rule along the month boundary. It steps day by day, so a month opening midweek is cut where
-     *  it actually opens rather than at the column edge. */
+    /** Box around each month. It steps day by day, so a month opening midweek is cut where it
+     *  actually opens rather than at the column edge. */
     monthSeparators?: boolean;
     weekdayLabels?: boolean;
     legend?: boolean;
-    /** Hover and focus text. Given one, cells become focusable buttons and get the house bubble.
-     *  Suppressed at xs and sm, where the target is too small to hit reliably. */
+    /** Hover and focus text. Given one, cells become focusable buttons and get the house bubble; the
+     *  grid is one Tab stop, ArrowUp and ArrowDown step a day, ArrowLeft and ArrowRight a week, and
+     *  Home and End jump to the first and last day. Suppressed at xs and sm, where the target is too
+     *  small to hit reliably. */
     tooltip?: (d: D | undefined, date: Date) => string;
     ariaLabel?: string;
   }>(),
@@ -128,16 +132,7 @@ const weeks = computed<{ date: Date; inRange: boolean }[][]>(() => {
   return out;
 });
 
-const scale = useCellScale<D>({
-  mode: props.mode,
-  states: computed(() => props.states),
-  ramp: computed(() => props.ramp ?? ('forest' as SequentialRamp)),
-  domain: computed(() => props.domain),
-  steps: computed(() => props.steps),
-  data: computed(() => props.data),
-  value: props.value,
-  state: props.state,
-});
+const scale = useCellScaleProps<D>(props);
 
 const datumFor = (d: Date) => byDay.value.get(keyOf(d));
 const fillFor = (cell: { date: Date; inRange: boolean }) =>
@@ -158,47 +153,58 @@ const pitch = computed(() => cellSize.value + cellGap.value);
 const gridWidth = computed(() => weeks.value.length * pitch.value - cellGap.value);
 const gridHeight = computed(() => 7 * pitch.value - cellGap.value);
 
-// Where each month opens, in grid coordinates. One source for both the label and the rule: the
-// label used to be placed on the week whose FIRST day fell in the new month, which puts it up to
-// six days late whenever a month opens midweek.
+// The column each month opens in. The label used to be placed on the week whose FIRST day fell in
+// the new month, which puts it up to six days late whenever a month opens midweek.
 const monthStarts = computed(() => {
-  const out: { wi: number; di: number; label: string; first: boolean }[] = [];
+  const out: { wi: number; label: string }[] = [];
   let prevMonth: number | null = null;
   weeks.value.forEach((week, wi) => {
-    week.forEach((cell, di) => {
+    week.forEach((cell) => {
       if (!cell.inRange) return;
       const m = cell.date.getMonth();
-      if (prevMonth === null) out.push({ wi, di, label: monthLabel(cell.date), first: true });
-      else if (m !== prevMonth) out.push({ wi, di, label: monthLabel(cell.date), first: false });
+      if (m !== prevMonth) out.push({ wi, label: monthLabel(cell.date) });
       prevMonth = m;
     });
   });
   return out;
 });
 
-// The boundary between two months, as one continuous path each.
+// A box around each month: an edge wherever a day's neighbour — a row up or down, a week left or
+// right — is another month or outside the window. That one test closes every box top and bottom,
+// steps it round a partial first or last week, and draws the frontier between two months.
 //
 // Time runs down a column then into the next, so a month that opens midweek does NOT split its
 // column into left and right: the days above the opening row in every LATER column already belong
-// to the new month. The frontier is therefore a Z — down the right edge of the opening column to
-// the opening row, one column left, then down to the bottom — not a per-cell outline. A month
-// opening on the week-start row degenerates to a single straight vertical.
+// to the new month. The frontier comes out as a Z — down the right edge of the opening column to
+// the opening row, one column left, then down to the bottom. A month opening on the week-start row
+// gets a straight vertical. A frontier is emitted from both sides; the two segments coincide.
 //
 // Coordinates land on gap midpoints (w * pitch - cellGap/2), so the rule sits centred between two
-// cells rather than against either one, and one path per boundary welds its own corners.
+// cells rather than against either one. Square caps weld the corners between segments.
 const monthPaths = computed(() => {
   if (!props.monthSeparators) return '';
+  const p = pitch.value;
   const half = cellGap.value / 2;
-  return monthStarts.value
-    .filter((m) => !m.first)
-    .map(({ wi, di }) => {
-      const xLeft = wi * pitch.value - half;
-      if (di === 0) return `M${xLeft},0V${gridHeight.value}`;
-      const xRight = (wi + 1) * pitch.value - half;
-      const yCut = di * pitch.value - half;
-      return `M${xRight},0V${yCut}H${xLeft}V${gridHeight.value}`;
-    })
-    .join(' ');
+  const monthAt = (wi: number, di: number) => {
+    const cell = weeks.value[wi]?.[di];
+    return cell?.inRange ? cell.date.getMonth() : -1;
+  };
+  const d: string[] = [];
+  weeks.value.forEach((week, wi) => {
+    week.forEach((cell, di) => {
+      if (!cell.inRange) return;
+      const m = cell.date.getMonth();
+      const x0 = wi * p - half;
+      const x1 = x0 + p;
+      const y0 = di * p - half;
+      const y1 = y0 + p;
+      if (monthAt(wi, di - 1) !== m) d.push(`M${x0},${y0}H${x1}`);
+      if (monthAt(wi, di + 1) !== m) d.push(`M${x0},${y1}H${x1}`);
+      if (monthAt(wi - 1, di) !== m) d.push(`M${x0},${y0}V${y1}`);
+      if (monthAt(wi + 1, di) !== m) d.push(`M${x1},${y0}V${y1}`);
+    });
+  });
+  return d.join('');
 });
 
 const dateLabel = (d: Date) => d.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' });
@@ -228,6 +234,30 @@ const hideTip = () => {
   tipOpen.value = false;
 };
 
+// Roving focus: the grid is one Tab stop, held by the day focused last. A cell's flat index is
+// week * 7 + weekday and the in-range days are one unbroken run of it, so the arrow keys step a day
+// (up, down) or a week (left, right) along that run, and Home and End jump to its ends.
+const focusRange = computed<[number, number]>(() => {
+  const cells = weeks.value.flat();
+  const first = cells.findIndex((c) => c.inRange);
+  return [first, first + cells.filter((c) => c.inRange).length - 1];
+});
+const focusIndex = ref(0);
+const tabStop = computed(() => Math.min(Math.max(focusIndex.value, focusRange.value[0]), focusRange.value[1]));
+const onFocus = (event: Event, index: number, cell: { date: Date }) => {
+  focusIndex.value = index;
+  showTip(event, labelFor(cell));
+};
+const onKeydown = (event: KeyboardEvent, index: number) => {
+  const [first, last] = focusRange.value;
+  const next = rovingIndex(event, index, first, last, 7, 1);
+  if (next === null) return;
+  event.preventDefault();
+  // The in-range days are the grid's only buttons, in flat-index order.
+  const buttons = (event.currentTarget as Element).closest('[role="group"]')?.querySelectorAll('button');
+  buttons?.[next - first]?.focus();
+};
+
 const hasEmpty = computed(() =>
   weeks.value.some((w) => w.some((c) => c.inRange && scale.isEmpty(datumFor(c.date) ?? null))),
 );
@@ -235,7 +265,12 @@ const hasEmpty = computed(() =>
 
 <template>
   <div class="flex w-full flex-col gap-3">
-    <div class="overflow-x-auto">
+    <!-- The month boxes sit half a gap outside the cells, past this scroller's clip. Padding out and
+         margin back in gives them room without moving the grid. -->
+    <div
+      class="overflow-x-auto"
+      :style="monthSeparators ? { padding: `${cellGap}px`, margin: `-${cellGap}px` } : undefined"
+    >
       <div class="flex" :style="{ gap: `${cellGap}px` }">
         <!-- Weekday gutter. justify-end pins the rows to the grid's bottom, so they line up
              whether or not a month-label row sits above. -->
@@ -288,18 +323,20 @@ const hasEmpty = computed(() =>
                   }"
                   :aria-label="interactive && cell.inRange ? labelFor(cell) : undefined"
                   :aria-hidden="interactive && cell.inRange ? undefined : 'true'"
+                  :tabindex="interactive && cell.inRange ? (wi * 7 + di === tabStop ? 0 : -1) : undefined"
                   @mouseenter="interactive && cell.inRange && showTip($event, labelFor(cell))"
                   @mouseleave="hideTip"
-                  @focus="interactive && cell.inRange && showTip($event, labelFor(cell))"
+                  @focus="interactive && cell.inRange && onFocus($event, wi * 7 + di, cell)"
                   @blur="hideTip"
+                  @keydown="interactive && cell.inRange && onKeydown($event, wi * 7 + di)"
                 />
               </div>
             </div>
 
-            <!-- One path for every boundary, over the cells. pointer-events none so it never takes
-                 a hover from the cell beneath; crispEdges so a 1px rule stays 1px off-integer.
-                 Dimmed text rather than a border token: the border tokens sit around 1.5:1 on the
-                 page and vanish between saturated cells. -->
+            <!-- One path for every box, over the cells. pointer-events none so it never takes a
+                 hover from the cell beneath; crispEdges so a 1px rule stays 1px off-integer.
+                 Toned text rather than a border token: the border tokens sit around 1.5:1 on the
+                 page and vanish between saturated cells, and dimmed was still too faint. -->
 
             <svg
               v-if="monthSeparators"
@@ -312,8 +349,9 @@ const hasEmpty = computed(() =>
                 :d="monthPaths"
                 fill="none"
                 stroke-width="1"
+                stroke-linecap="square"
                 shape-rendering="crispEdges"
-                style="stroke: var(--ui-text-dimmed)"
+                style="stroke: var(--ui-text-toned)"
               />
             </svg>
           </div>

package/src/FChartFrame.vue

@@ -10,20 +10,18 @@ import { Position } from '@unovis/ts';
 import type {
   AxisConfigInterface,
   BulletLegendItemInterface,
+  Crosshair,
   TooltipConfigInterface,
   XYContainerConfigInterface,
 } from '@unovis/ts';
 // Relative file imports (not the package barrel): the barrel exports this component, and a
 // self-import through it would create a module cycle.
 import { chartLabel, fromCategories } from './fromCategories';
+import { crosshairConfig } from './crosshairConfig';
 import { forestTooltip, type ForestTooltipOptions } from './forestTooltip';
 import { motionDuration } from './motionDuration';
-import {
-  axisX as axisXPreset,
-  axisY as axisYPreset,
-  tooltipDefaults,
-  tooltipContainer,
-} from './presets';
+import { indexAxes, indexContainer } from './frameIndex';
+import { tooltipDefaults, tooltipContainer } from './presets';
 import { useThemeVersion } from './useThemeVersion';
 import { useTooltipSnap, nextTipId } from './snapTooltip';
 
@@ -58,9 +56,9 @@ const props = withDefaults(
     crosshair?: boolean;
     /** Title/value formatting for the house crosshair template. */
     format?: ForestTooltipOptions<Datum>;
-    /** The mark runs horizontally (set `orientation` on the mark itself). The frame's index
-     *  machinery — tick pinning, the edge gutter, grid-line defaults — follows the category
-     *  dimension onto y; formatters stay yours to place per axis. */
+    /** The mark runs horizontally (set `orientation` on the mark itself). Tick pinning and the
+     *  edge gutter move onto y, the category dimension, and the grid lines onto x; formatters stay
+     *  yours to place per axis. */
     horizontal?: boolean;
     legend?: boolean;
     /** Where the legend sits. `bottom` (default) renders centred under the chart, caption-style;
@@ -98,43 +96,20 @@ defineSlots<{
 
 const acc = computed(() => fromCategories<Datum>(props.categories, props.data, props.xKey));
 
-// Index charts get tick positions at the row indices — without this the axis invents fractional
-// ticks between rows. The pin sits on the category axis: x normally, y when `horizontal` (Unovis
-// swaps which scale carries the index). Grid lines follow the value axis the same way. An xKey
-// chart scales its own axis.
-const indexTicks = computed(() =>
-  props.xKey ? undefined : { tickValues: props.data.map((_, i) => i) },
-);
-const xAxisConfig = computed<Partial<AxisConfigInterface<Datum>>>(() => ({
-  ...axisXPreset,
-  ...(props.horizontal ? { gridLine: true } : indexTicks.value),
-  ...(props.axisX || {}),
-}));
-const yAxisConfig = computed<Partial<AxisConfigInterface<Datum>>>(() => ({
-  ...axisYPreset,
-  ...(props.horizontal ? { gridLine: false, ...indexTicks.value } : {}),
-  ...(props.axisY || {}),
-}));
-
-// Index charts also get half a row of outer gutter: the category domain extends past the first
-// and last rows so edge marks (bars especially) stop sitting flush against the plot edges. Ticks
-// stay on the row indices, and the gutter follows the category dimension under `horizontal`. An
-// xKey chart plots a real field and keeps the library's exact-extent default; an explicit
-// `container` domain overrides this like any other container key.
-const containerConfig = computed<Partial<XYContainerConfigInterface<Datum>>>(() => {
-  const gutter: [number, number] = [-0.5, props.data.length - 0.5];
-  return {
-    ...(props.xKey || props.data.length === 0
-      ? {}
-      : props.horizontal
-        ? { yDomain: gutter }
-        : { xDomain: gutter }),
-    ...(props.container || {}),
-  };
-});
+// Index charts pin the category axis ticks to the row indices, extend its domain half a row past
+// each end, and leave the grid to the value axis; `horizontal` moves the ticks and the gutter onto
+// y and the grid onto x. The rules live in frameIndex.ts. The container keeps a computed of its
+// own: VisXYContainer updates on every new config object, where VisAxis compares its props deeply.
+const axes = computed(() => indexAxes<Datum>(props));
+const containerConfig = computed(() => indexContainer<Datum>(props));
 
 const tipFn = computed(() => forestTooltip<Datum>(props.categories, props.format));
 
+const crosshairRef = ref<{ component?: Crosshair<Datum> }>();
+const crosshairProps = computed(() =>
+  crosshairConfig(acc.value, () => crosshairRef.value?.component?.accessors),
+);
+
 // The panel is snapped to the datum by useTooltipSnap below, which rewrites its position after
 // Unovis places it. What Unovis is configured to do here is therefore only what shows when the
 // snap stands down (`followCursor`), plus the show/hide and content it always owns: pointer
@@ -180,8 +155,8 @@ const repaintKey = computed(() =>
       v-bind="{ ...containerConfig, ...$attrs }"
     >
       <slot name="mark" :data="data" :x="acc.xAccessor" :y="acc.yAccessors" :colors="acc.colors" />
-      <VisAxis v-if="axisX !== false" v-bind="xAxisConfig" />
-      <VisAxis v-if="axisY !== false" v-bind="yAxisConfig" />
+      <VisAxis v-if="axisX !== false" v-bind="axes.axisX" />
+      <VisAxis v-if="axisY !== false" v-bind="axes.axisY" />
       <template v-if="tooltip !== false">
         <!-- duration 0 is deliberate, and load-bearing twice over. Unovis animates the crosshair
              line's x through a transition, so it eases toward the row the pointer just snapped to
@@ -190,9 +165,8 @@ const repaintKey = computed(() =>
              tooltip's anchor. Easing it would put the panel on the wrong side of the plot. -->
         <VisCrosshair
           v-if="crosshair"
-          :x="acc.xAccessor"
-          :y="acc.yAccessors"
-          :color="acc.colors"
+          ref="crosshairRef"
+          v-bind="crosshairProps"
           :template="tipFn"
           :duration="0"
         />

package/src/FDottedMap.vue

@@ -3,8 +3,8 @@
 // FStatusTrack puts cells in a sequence, FCalendarGrid puts them on a date grid, this puts them on a
 // geography. Colour resolution is useCellScale's; this component owns the binning and the layout.
 //
-// It is not a map. There is no pan, no zoom and no projection at read time — a dot is roughly a
-// square kilometre and locates nothing. Real geography is Mapbox's job. This answers "where in
+// It is not a map. There is no pan, no zoom and no projection at read time — a dot on the default
+// grid covers about 0.37 km² and locates nothing. Real geography is Mapbox's job. This answers "where in
 // London" at a glance, with no tiles and no network.
 import { computed, ref, shallowRef, watchEffect } from 'vue';
 import { useCellScale, type SequentialRamp } from './useCellScale';
@@ -13,7 +13,7 @@ import {
   LONDON_GRID,
   RIVER_COLOR,
   loadLondonGrid,
-  dotAt,
+  binPoints,
   dotKey,
   type DotDensity,
   type LondonGrid,
@@ -31,7 +31,7 @@ const props = withDefaults(
     points: P[];
     lat: (p: P) => number;
     lng: (p: P) => number;
-    /** Summed per dot as `value(p) ?? 1`, so the default reading is a count of points. */
+    /** Summed per dot. Unset, each point counts one; a null, undefined or non-finite return adds nothing. */
     value?: (p: P) => number | null | undefined;
     ramp?: SequentialRamp;
     /** Intensity domain, in the caller's units. Two maps compared side by side must both set it. */
@@ -121,22 +121,11 @@ const land = computed(() => new Set(landDots.value.map(([c, r]) => dotKey(c, r))
 
 // Points are summed into their dot. A point outside the boundary, or on the river, has nowhere to
 // land — those are counted rather than quietly absorbed, so a caller feeding the wrong city or the
-// wrong coordinate order can see it. The river is drawn but is not a bucket: a ride does not start
+// wrong coordinate order can see it. The river is drawn but is not a bucket: a trip does not start
 // in the Thames, and letting one land there would put a reading on a dot that cannot have one.
-const binned = computed(() => {
-  const totals = new Map<string, number>();
-  let dropped = 0;
-  for (const p of props.points) {
-    const at = dotAt(grid.value, props.lat(p), props.lng(p));
-    const key = at && dotKey(at[0], at[1]);
-    if (!key || !land.value.has(key)) {
-      dropped++;
-      continue;
-    }
-    totals.set(key, (totals.get(key) ?? 0) + (props.value?.(p) ?? 1));
-  }
-  return { totals, dropped };
-});
+const binned = computed(() =>
+  binPoints(grid.value, land.value, props.points, props.lat, props.lng, props.value),
+);
 
 // Every land dot gets a cell, whether or not a point reached it.
 //
@@ -155,9 +144,9 @@ const cells = computed<DotInfo[]>(() =>
 
 // How a total is spaced along the ramp.
 //
-// Density is heavy-tailed, and linearly spacing a heavy tail produces a blank map: with a typical
-// week of rides the median dot holds 1 and the busiest holds over a hundred, so five equal buckets
-// put roughly ninety per cent of the city in the palest one and the picture says nothing. Compress
+// Density is heavy-tailed, and linearly spacing a heavy tail produces a blank map: in a week of
+// trip starts the median dot can hold 1 and the busiest 50, so five equal buckets put over ninety
+// per cent of the city in the palest one and the picture says nothing. Compress
 // the tail and the structure appears. Nothing is compressed by default — a transform the caller did
 // not ask for would quietly change what the ramp claims — but a density map usually wants one.
 const spaced = (v: number) =>
@@ -226,7 +215,7 @@ const byPosition = computed(() => {
 const mapLabel = computed(() => {
   if (props.ariaLabel) return props.ariaLabel;
   // The busiest dot in the caller's units. scale.domain is in spaced units and would report a
-  // logarithm as though it were a ride count.
+  // logarithm as though it were a count.
   const hi = props.domain?.[1] ?? cells.value.reduce((m, c) => (c.value > m ? c.value : m), 0);
   const placed = props.points.length - binned.value.dropped;
   return `London, as a grid of dots shaded by density. The busiest holds ${hi.toLocaleString('en-GB')}, across ${placed.toLocaleString('en-GB')} of ${props.points.length.toLocaleString('en-GB')} points.`;