basalt-ui 1.22.0 → 1.23.1

package/dist/vite.d.ts

@@ -33,6 +33,29 @@ export type BasaltViteOptions = {
     enforcementNotice?: boolean;
 };
 export declare function basaltViteConfig(opts: BasaltViteOptions): UserConfig;
+/**
+ * One icon a consumer names itself — a manifest `icons` member, plus optionally the head `<link>`
+ * that points at the same file.
+ *
+ * The field names are the manifest's own, verbatim, so what a consumer writes here is what ships in
+ * `site.webmanifest`. `src` is root-relative (`'/favicon.svg'` or `'favicon.svg'`, both resolve the
+ * same) and is prefixed with Vite's `base` exactly like basalt's built-in set.
+ */
+export type BasaltAppIcon = {
+    /** Root-relative path under `public/`. Prefixed with Vite's resolved `base`. */
+    src: string;
+    /** Manifest `sizes`. `'any'` for a scalable SVG; `'192x192'` for a raster. */
+    sizes?: string;
+    /** MIME type, e.g. `'image/svg+xml'`. */
+    type?: string;
+    /** Manifest `purpose`, e.g. `'any maskable'`. */
+    purpose?: string;
+    /**
+     * Emit a head `<link rel="…">` for this icon too. Omitted → manifest only, which is what an app
+     * that links its own favicon from `index.html` wants.
+     */
+    rel?: 'icon' | 'shortcut icon' | 'apple-touch-icon' | 'mask-icon';
+};
 export type BasaltAppOptions = {
     /** App display name — used verbatim as the manifest `name` and (unless overridden) OG title. */
     name: string;
@@ -81,12 +104,28 @@ export type BasaltAppOptions = {
     /** Manifest `id`. Default: the resolved `startUrl` (default- or explicitly-derived, per above). */
     id?: string;
     /**
-     * Icon links + manifest icon paths. `false` skips BOTH — the head `<link>` icons and the
-     * manifest's `icons` array — so a manifest is never emitted pointing at files that 404.
+     * Which icons the plugin knows about — three forms, one question each.
+     *
+     * - **omitted / `{ dir }`** — basalt's own six-filename set (the realfavicongenerator layout argo
+     *   ships), optionally under a subdirectory of `public/`. Unchanged default.
+     * - **`false`** — no head `<link>` icons and no manifest `icons` member, so a manifest is never
+     *   emitted pointing at files that 404.
+     * - **an array** — the icons this app ACTUALLY has, named by the consumer.
+     *
+     * The array is the form for every app that was not scaffolded from basalt's icon set, which is
+     * most of them. `{ dir }` can only move the six fixed filenames; it cannot rename one, so an app
+     * whose single icon is `favicon.svg` had no way to say so and had to keep a hand-written manifest
+     * beside the generated head — the last thing standing between rb and deleting a file carrying a
+     * permanent `theme-allow-file`. One SVG at `sizes: 'any'` is a complete, installable icon set.
+     *
+     * Every entry becomes a manifest icon; an entry becomes a head `<link>` only when it names a
+     * {@link BasaltAppIcon.rel}. That split is deliberate — an app that already links its favicon
+     * from its own `index.html` wants the manifest fixed without a duplicate tag, and an app that
+     * wants the plugin to own the head says so per icon. An empty array reads as `false`.
      */
     icons?: false | {
         dir?: string;
-    };
+    } | readonly BasaltAppIcon[];
     /** Emits `<meta name="darkreader-lock">` when `'lock'` (default). Pass `false` to omit it. */
     darkreader?: 'lock' | false;
     /** Site-wide SEO metadata — only the keys provided are emitted, no per-page SEO. */

package/dist/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAA6B,YAAY,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAI/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AA6CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAgFpE;AAgBD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;IAC/C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAA;IAChE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3B,oFAAoF;IACpF,GAAG,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,qBAAqB,CAAA;KAAE,CAAA;IACvF,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClD,CAAA;AA4gBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAMzE"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAA6B,YAAY,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAI/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AA6CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAgFpE;AAgBD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAA;IACX,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,kBAAkB,GAAG,WAAW,CAAA;CAClE,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;IAC/C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAA;IAChE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,aAAa,EAAE,CAAA;IAC3D,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3B,oFAAoF;IACpF,GAAG,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,qBAAqB,CAAA;KAAE,CAAA;IACvF,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClD,CAAA;AA0kBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAMzE"}

package/dist/vite.js

@@ -133,6 +133,18 @@ function withIconPath(dir, file) {
 function withBase(base, path) {
   return base + path.slice(1);
 }
+function isIconList(icons) {
+  return Array.isArray(icons);
+}
+function resolveIcons(icons) {
+  if (icons === false) return { mode: "none" };
+  if (icons === void 0) return { mode: "default", dir: void 0 };
+  if (!isIconList(icons)) return { mode: "default", dir: icons.dir };
+  return icons.length === 0 ? { mode: "none" } : { mode: "explicit", icons };
+}
+function iconHref(base, src) {
+  return withBase(base, src.startsWith("/") ? src : `/${src}`);
+}
 function hasViewportMeta(html) {
   return /<meta\s+[^>]*name=["']viewport["']/i.test(html);
 }
@@ -207,8 +219,7 @@ function buildStaticTags(input) {
     shortName,
     themeColor,
     bootStyle,
-    iconsEnabled,
-    iconsDir,
+    icons,
     darkreader,
     manifestEnabled,
     base,
@@ -234,13 +245,13 @@ function buildStaticTags(input) {
     }
   );
   tags.push({ tag: "style", children: bootStyle });
-  if (iconsEnabled) {
+  if (icons.mode === "default") {
     tags.push(
       {
         tag: "link",
         attrs: {
           rel: "shortcut icon",
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.favicon))
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.favicon))
         }
       },
       {
@@ -248,7 +259,7 @@ function buildStaticTags(input) {
         attrs: {
           rel: "icon",
           type: "image/svg+xml",
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.svg))
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.svg))
         }
       },
       {
@@ -256,7 +267,7 @@ function buildStaticTags(input) {
         attrs: {
           rel: "icon",
           sizes: "96x96",
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.png96))
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.png96))
         }
       },
       {
@@ -264,11 +275,25 @@ function buildStaticTags(input) {
         attrs: {
           rel: "apple-touch-icon",
           sizes: "180x180",
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.appleTouch))
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.appleTouch))
         }
       }
     );
   }
+  if (icons.mode === "explicit") {
+    for (const icon of icons.icons) {
+      if (icon.rel === void 0) continue;
+      tags.push({
+        tag: "link",
+        attrs: {
+          rel: icon.rel,
+          ...icon.type === void 0 ? {} : { type: icon.type },
+          ...icon.sizes === void 0 ? {} : { sizes: icon.sizes },
+          href: iconHref(base, icon.src)
+        }
+      });
+    }
+  }
   tags.push(
     { tag: "meta", attrs: { name: "apple-mobile-web-app-title", content: shortName } },
     { tag: "meta", attrs: { name: "apple-mobile-web-app-capable", content: "yes" } },
@@ -286,6 +311,34 @@ function buildStaticTags(input) {
   );
   return tags;
 }
+function manifestIcons(icons, base) {
+  if (icons.mode === "none") return {};
+  if (icons.mode === "default") {
+    return {
+      icons: [
+        {
+          src: withBase(base, withIconPath(icons.dir, ICON_FILES.manifest192)),
+          sizes: "192x192",
+          type: "image/png"
+        },
+        {
+          src: withBase(base, withIconPath(icons.dir, ICON_FILES.manifest512)),
+          sizes: "512x512",
+          type: "image/png",
+          purpose: "any maskable"
+        }
+      ]
+    };
+  }
+  return {
+    icons: icons.icons.map((icon) => ({
+      src: iconHref(base, icon.src),
+      ...icon.sizes === void 0 ? {} : { sizes: icon.sizes },
+      ...icon.type === void 0 ? {} : { type: icon.type },
+      ...icon.purpose === void 0 ? {} : { purpose: icon.purpose }
+    }))
+  };
+}
 function buildManifestJson(input) {
   const {
     options,
@@ -296,8 +349,7 @@ function buildManifestJson(input) {
     display,
     schemeColor,
     backgroundColor,
-    iconsEnabled,
-    iconsDir,
+    icons,
     base
   } = input;
   const manifest = {
@@ -316,21 +368,9 @@ function buildManifestJson(input) {
     // `{ manifest: true, icons: false }` shipped a manifest pointing at two PNGs the app never
     // ships — an installable app with broken icons, and the reason rb went hybrid (plugin for the
     // head, a hand-written manifest for the rest). A manifest with NO icons member is valid.
-    ...iconsEnabled ? {
-      icons: [
-        {
-          src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest192)),
-          sizes: "192x192",
-          type: "image/png"
-        },
-        {
-          src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest512)),
-          sizes: "512x512",
-          type: "image/png",
-          purpose: "any maskable"
-        }
-      ]
-    } : {}
+    // The `'explicit'` arm is the other half of that fix: honest about icons it cannot see was
+    // only worth having once a consumer could tell it which icons it DOES have.
+    ...manifestIcons(icons, base)
   };
   return JSON.stringify(manifest, null, 2);
 }
@@ -338,8 +378,7 @@ function createMainPlugin(options) {
   const shortName = options.shortName ?? options.name;
   const display = options.display ?? "standalone";
   const darkreader = options.darkreader ?? "lock";
-  const iconsEnabled = options.icons !== false;
-  const iconsDir = options.icons === false ? void 0 : options.icons?.dir;
+  const icons = resolveIcons(options.icons);
   const manifestEnabled = options.manifest !== false;
   const themeColor = resolveThemeColors(options.themeColor);
   const colorScheme = options.colorScheme ?? "dark";
@@ -371,8 +410,7 @@ function createMainPlugin(options) {
         display,
         schemeColor,
         backgroundColor,
-        iconsEnabled,
-        iconsDir,
+        icons,
         base
       });
       staticTags = buildStaticTags({
@@ -380,8 +418,7 @@ function createMainPlugin(options) {
         shortName,
         themeColor,
         bootStyle,
-        iconsEnabled,
-        iconsDir,
+        icons,
         darkreader,
         manifestEnabled,
         base,

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.22.0
+# basalt-ui v1.23.1
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.22.0
+Version: 1.23.1
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.22.0",
+  "version": "1.23.1",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/charts/hooks/useBandPlot.ts

@@ -0,0 +1,302 @@
+/**
+ * The choreography shared by every BANDED x plot — one slot per datum, drawn as a rect, with no
+ * point in between.
+ *
+ * `CartesianChart` cannot host these: its x scale is `scalePoint` (positions, no width) and it
+ * renders `AxisLeftNumeric` unconditionally. `BandStrip` has no numeric y axis at all and
+ * `MirroredBars` has two, in two independent scales. Both are therefore
+ * `basalt/hand-rolled-plot` shapes — and this module is what stops the second one from being a
+ * copy of the first, per `DualPanel`'s own instruction to "promote the shared choreography rather
+ * than copying this file".
+ *
+ * What lives here: width-driven folding, the measured gutters, the band scale and its
+ * half-bandwidth cursor correction, the shared cursor itself, and the source/follower tooltip
+ * anchor arithmetic. What does NOT: any mark. See `docs/CHARTS-SPEC.md` § "The contract".
+ */
+
+import { scaleBand } from '@visx/scale'
+import { useCallback, useMemo, useRef } from 'react'
+import type { ReactNode, RefObject } from 'react'
+import { VX } from '../../tokens'
+import type { ChartMargin } from '../../tokens'
+import type { CursorResolution } from '../cursor/resolve'
+import { autoMargin } from '../layout/auto-margin'
+import { maxTextWidth } from '../utils/measure-text'
+import { smartTicks } from '../utils/ticks'
+import { useChartCursor } from './useChartCursor'
+import type { ChartCursor, CursorAnchor } from './useChartCursor'
+
+type BandScale = ReturnType<typeof scaleBand<string>>
+
+/**
+ * Collapse adjacent data into one drawn band at widths where one-band-per-datum sub-pixels.
+ *
+ * 288 buckets over a 234px plot is a 0.81px pitch: every band draws at a flat 1px and a single
+ * catastrophic slot can be overdrawn by its neighbour. Folding is the only honest answer — the
+ * alternative is a chart that silently loses its worst column.
+ */
+export type BandFold<T> = {
+  /**
+   * Floor on the px pitch of a drawn band. Default 3 — not 2, because a band also has to be wide
+   * enough for a partial-absence split (`absentFraction`) to render as two visibly distinct
+   * pieces, and at 2px the fill and the hatch antialias into one smudge.
+   */
+  minBandPx?: number
+  /**
+   * Collapse a group of adjacent source data into the one datum drawn in its place.
+   *
+   * The merge is the CONSUMER's, deliberately: whether a folded slot's value is a max, a sum, or
+   * a rate recomputed from summed parts is a question about the measurement, not about the
+   * chart — and averaging a fully-down bucket into its clean neighbours describes a bucket that
+   * never happened. The kind owns only the arithmetic of how many groups there are.
+   *
+   * Identity (`getX`) MUST come from `group[0]`, or the axis stops being monotone and the cursor
+   * key stops naming a real slot start.
+   */
+  merge: (group: T[]) => T
+}
+
+const DEFAULT_MIN_BAND_PX = 3
+
+/**
+ * Terminal-gutter cap, as a fraction of the plot width.
+ *
+ * A gutter that exists only so a centred terminal tick label does not clip is half a label wide —
+ * right at 1500px and absurd at 390, where half a `DD.MM HH:MM` label is 48px of a 338px chart
+ * spent on empty margin. A gutter measured from an AXIS's own labels is never capped: shrinking
+ * that one clips the reading itself.
+ */
+const TERMINAL_GUTTER_MAX_FRACTION = { left: 0.14, right: 0.12 }
+
+/**
+ * The grouping half of {@link BandFold}, exported so a consumer can test their `merge` against the
+ * arithmetic that will actually run rather than re-implementing it in the test file — the merge is
+ * where the honesty rules live (max vs mean vs a rate recomputed from summed parts), and a test
+ * that groups differently from the kind is testing the wrong function.
+ */
+export function foldBands<T>(data: readonly T[], cap: number, merge: (group: T[]) => T): T[] {
+  if (cap <= 0) return []
+  if (data.length <= cap) return [...data]
+  const groupSize = Math.ceil(data.length / cap)
+  const out: T[] = []
+  for (let i = 0; i < data.length; i += groupSize) out.push(merge(data.slice(i, i + groupSize)))
+  return out
+}
+
+/** Tooltip seams shared by `BandStrip` and `MirroredBars` — the `CartesianTooltipConfig` subset
+ * that means anything on a banded plot (there is no per-point `follow` distinction to make that
+ * `CartesianChart` doesn't already document identically). */
+export type BandTooltipConfig<T> = {
+  /** Default true — the tooltip tracks the pointer. `false` anchors it to the crosshair at the
+   * plot's top edge, so a column of charts sharing one cursor lines every tooltip up on one x. */
+  follow?: boolean
+  /** Right-aligned badge in the tooltip header. */
+  label?: (d: T) => { text: string; color: string } | null
+  /** Overrides the header's date text — same seam, same reason, as
+   * `CartesianTooltipConfig.formatHeader`. */
+  formatHeader?: (key: string, d: T) => string
+  /** Rows rendered BEFORE the derived rows. `hidden` is the same legend-toggle set the marks
+   * draw from, so a hand-authored row cannot desync from it. */
+  prependRows?: (d: T, ctx: BandTooltipRowContext) => ReactNode
+  /** Rows appended after the derived rows. Same `ctx` as {@link prependRows}. */
+  extraRows?: (d: T, ctx: BandTooltipRowContext) => ReactNode
+  /**
+   * Render this chart's tooltip when it is a cursor FOLLOWER, not only when it is the SOURCE.
+   * Default false. A follower has no pointer under it, so it always anchors to the crosshair
+   * regardless of `follow`; only the SOURCE is `aria-live`. Costs one `getBoundingClientRect`
+   * per hovered frame per opted-in chart — see `CartesianTooltipConfig.onFollow`.
+   */
+  onFollow?: boolean
+}
+
+export type BandTooltipRowContext = { hidden: ReadonlySet<string> }
+
+export type UseBandPlotInput<T> = {
+  data: readonly T[]
+  chartId: string
+  getX: (d: T) => string
+  formatX: (key: string) => string
+  /** The plot rect's width, as handed down by `ChartFrame`. */
+  width: number
+  fold?: BandFold<T>
+  cursorResolution?: CursorResolution
+  /**
+   * Which of the (possibly folded) keys get a tick. Default `smartTicks`. The seam exists because
+   * `smartTicks` appends the final value unconditionally, which on a dense time axis puts the last
+   * two labels on top of each other — a chart whose x labels are richer than `DD.MM` needs its own
+   * rule.
+   */
+  xTickValues?: (keys: readonly string[], plotWidth: number) => readonly string[]
+  /** Left-axis tick labels, already formatted. Empty for a plot with no left axis. */
+  leftLabels?: readonly string[]
+  /** Per-side margin overrides — applied last, so the escape hatch always wins. */
+  margin?: Partial<ChartMargin>
+  tooltip?: BandTooltipConfig<T> | false
+}
+
+export type BandPlot<T> = {
+  /** The data actually drawn — `data` when it fits, the folded slots when it does not. */
+  bands: T[]
+  keys: string[]
+  margin: ChartMargin
+  plotWidth: number
+  scale: BandScale
+  cursor: ChartCursor<T>
+  point: T | null
+  /** Plot-local x of the crosshair, or null when no point resolves. */
+  crosshairX: number | null
+  /** Pitch between adjacent band origins. */
+  step: number
+  /** Drawn width of one band — the pitch minus a 1px separator, floored at 1. */
+  bandWidth: number
+  tickValues: string[]
+  svgRef: RefObject<SVGSVGElement | null>
+  tooltipAnchor: CursorAnchor | null
+  showTooltip: boolean
+  /** Only the cursor SOURCE announces — N followers on one page would fire N live-region updates
+   * per pointer move. */
+  ariaLive: boolean
+}
+
+/**
+ * Wire a banded plot into the framework's measured margins, band scale, shared cursor and tooltip
+ * positioning. Returns everything except the marks.
+ */
+export function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T> {
+  const {
+    data,
+    chartId,
+    getX,
+    formatX,
+    width,
+    fold,
+    cursorResolution,
+    xTickValues,
+    leftLabels,
+    margin: marginOverride,
+    tooltip,
+  } = input
+
+  const hasLeftAxis = leftLabels !== undefined && leftLabels.length > 0
+  const xLabelsAll = useMemo(() => data.map((d) => formatX(getX(d))), [data, getX, formatX])
+
+  // ── Pass 1: gutters, from the labels that will actually be painted ──────────────────────────
+  const margin = useMemo<ChartMargin>(() => {
+    const measured = autoMargin({
+      ...(leftLabels !== undefined && { left: leftLabels }),
+      bottom: xLabelsAll,
+      ...(marginOverride !== undefined && { override: marginOverride }),
+    })
+    if (marginOverride?.left !== undefined && marginOverride.right !== undefined) return measured
+
+    const halfXLabel = Math.ceil(maxTextWidth(xLabelsAll, VX.axisFont) / 2)
+    // A band axis puts its FIRST tick on the plot's left edge, so the left gutter needs the same
+    // half-label law `autoMargin` already applies on the right. `autoMargin` cannot know that —
+    // its left law measures a left AXIS, which a band plot may not have.
+    const left = hasLeftAxis ? measured.left : Math.max(measured.left, halfXLabel)
+    return {
+      ...measured,
+      ...(marginOverride?.left === undefined && {
+        left: hasLeftAxis
+          ? left
+          : capTerminalGutter(left, width, TERMINAL_GUTTER_MAX_FRACTION.left, VX.margin.left),
+      }),
+      ...(marginOverride?.right === undefined && {
+        right: capTerminalGutter(
+          measured.right,
+          width,
+          TERMINAL_GUTTER_MAX_FRACTION.right,
+          VX.margin.right,
+        ),
+      }),
+    }
+  }, [leftLabels, xLabelsAll, marginOverride, hasLeftAxis, width])
+
+  const plotWidth = Math.max(width - margin.left - margin.right, 0)
+
+  // ── Pass 2: the fold, BEFORE the scale — so the domain, and therefore the cursor's key space,
+  // is the grid actually drawn rather than the raw one ────────────────────────────────────────
+  const minBandPx = fold?.minBandPx ?? DEFAULT_MIN_BAND_PX
+  const merge = fold?.merge
+  const bands = useMemo(
+    () =>
+      merge === undefined ? [...data] : foldBands(data, Math.floor(plotWidth / minBandPx), merge),
+    [data, plotWidth, minBandPx, merge],
+  )
+
+  const keys = useMemo(() => bands.map(getX), [bands, getX])
+  const scale = useMemo(
+    () => scaleBand<string>({ domain: keys, range: [0, plotWidth] }),
+    [keys, plotWidth],
+  )
+
+  // `+ bandwidth()/2` is mandatory: `useChartCursor`'s nearest-point loop compares the pointer
+  // against `xScale(getKey(d))`, and `scaleBand` returns the band's LEFT edge. Passing `scale`
+  // raw biases every snap by half a band — at 288 bands, a systematic one-slot-early cursor.
+  const bandCenter = useCallback(
+    (key: string) => {
+      const v = scale(key)
+      return v === undefined ? undefined : v + scale.bandwidth() / 2
+    },
+    [scale],
+  )
+
+  const cursor = useChartCursor<T>({
+    data: bands,
+    chartId,
+    getKey: getX,
+    xScale: bandCenter,
+    marginLeft: margin.left,
+    ...(cursorResolution !== undefined && { resolution: cursorResolution }),
+  })
+
+  const tickValues = useMemo(
+    () => [
+      ...(xTickValues === undefined ? smartTicks(keys, plotWidth) : xTickValues(keys, plotWidth)),
+    ],
+    [keys, plotWidth, xTickValues],
+  )
+
+  const svgRef = useRef<SVGSVGElement>(null)
+  const point = cursor.point
+  const crosshairX = point === null ? null : (bandCenter(getX(point)) ?? null)
+
+  const cfg = tooltip === false ? undefined : tooltip
+  // Identical seam to `CartesianChart`: SOURCE always, FOLLOWER only when opted in. A follower has
+  // no pointer under it, so it is always positioned via the anchored (crosshair) path.
+  const isFollowerRender = !cursor.isSource && cfg?.onFollow === true
+  const showTooltip = tooltip !== false && point !== null && (cursor.isSource || isFollowerRender)
+  const useAnchored = cfg?.follow === false || isFollowerRender
+  const anchorX = useAnchored ? crosshairX : null
+  const svgRect = anchorX === null ? undefined : svgRef.current?.getBoundingClientRect()
+  const tooltipAnchor =
+    svgRect === undefined || anchorX === null
+      ? cursor.anchor
+      : { x: svgRect.left + margin.left + anchorX, y: svgRect.top + margin.top }
+
+  const step = bands.length > 0 ? plotWidth / bands.length : 0
+  const bandWidth = Math.max(step - 1, 1)
+
+  return {
+    bands,
+    keys,
+    margin,
+    plotWidth,
+    scale,
+    cursor,
+    point,
+    crosshairX,
+    step,
+    bandWidth,
+    tickValues,
+    svgRef,
+    tooltipAnchor,
+    showTooltip,
+    ariaLive: cursor.isSource,
+  }
+}
+
+/** Shrink a half-label gutter on a narrow plot, but never below the token floor. */
+function capTerminalGutter(gutter: number, width: number, fraction: number, floor: number): number {
+  return Math.min(gutter, Math.max(floor, Math.round(width * fraction)))
+}

package/src/charts/index.ts

@@ -75,6 +75,7 @@ export {
   type ChartPendingProps,
 } from './primitives/ChartPending'
 export { Crosshair, SeriesDot } from './primitives/Crosshair'
+export { HatchPattern, hatchFill, hatchSizeFor } from './primitives/HatchPattern'
 export { ChartCard } from './primitives/ChartCard'
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend'
 export {
@@ -91,6 +92,12 @@ export { AreaGradient, areaFillUrl } from './primitives/AreaGradient'
 
 // ── Hooks ────────────────────────────────────────────────────────────────
 export { useChartCursor, type ChartCursor, type CursorAnchor } from './hooks/useChartCursor'
+export {
+  foldBands,
+  type BandFold,
+  type BandTooltipConfig,
+  type BandTooltipRowContext,
+} from './hooks/useBandPlot'
 export type { CursorResolution } from './cursor/resolve'
 export { useChartSize, type UseChartSizeResult, type ChartSize } from './hooks/useChartSize'
 
@@ -124,6 +131,13 @@ export { Donut, type DonutProps, type DonutDatum } from './kinds/Donut'
 export { MultiLine, type MultiLineProps } from './kinds/MultiLine'
 export { DualPanel, type DualPanelProps } from './kinds/DualPanel'
 export { Heatmap, type HeatmapProps } from './kinds/Heatmap'
+export {
+  BandStrip,
+  type BandStripProps,
+  type BandStripSeries,
+  type BandSpan,
+} from './kinds/BandStrip'
+export { MirroredBars, type MirroredBarsProps, type MirroredBarPane } from './kinds/MirroredBars'
 
 // ── Sparklines ───────────────────────────────────────────────────────────
 export { LineSparkline, BarSparkline } from './sparklines'