basalt-ui 1.22.0 → 1.23.1

package/configs/oxlint-plugin.test.ts

@@ -984,55 +984,112 @@ describe('basalt/shadow-basalt-export', () => {
   })
 })
 
-// ── theme-allow comment shapes (the plugin half of the annotation contract) ───
+// ── theme-allow shape grid (the plugin half of the annotation contract) ──────
 
-// The prefix rule has had three holes found in three rounds, so every comment shape a consumer
-// actually writes is pinned here — and the guard's copy is pinned identically in
-// `src/guard/check-source.test.ts`. The two must agree on what an annotation IS.
-describe('theme-allow comment shapes', () => {
-  const flags = (source: string): boolean => run(source).rules.has('no-raw-font-size')
+/**
+ * The plugin's copy of the grid pinned in `src/guard/check-source.test.ts`, row name for row name.
+ *
+ * Five holes in four rounds, twice because the two parsers disagreed about what an annotation IS —
+ * so the shapes are enumerated over the axes that vary (comment style × token position × where the
+ * closer falls × what follows), not collected as anecdotes. Every row here has a twin there; the
+ * guard-only dialects (CSS continuation lines, HTML, the JSON member form) have no twin because
+ * oxlint never parses those files.
+ *
+ * `no-raw-font-size` is the vehicle — a JSXAttribute rule, so the reported node's line is exactly
+ * the line an annotation has to reach.
+ */
+/** Wraps JSX children in a component, so a `{/* … *\/}` child is legal source. */
+const jsxShape = (body: string): string =>
+  `export const C = () => (\n  <div>\n${body}\n  </div>\n)\n`
+
+describe('theme-allow shape grid', () => {
+  const REASON = 'deliberate legacy value'
+  const A = `theme-allow no-raw-font-size — ${REASON}`
+  const AF = `theme-allow-file no-raw-font-size — ${REASON}`
+  const T = `<Text fz={10} />`
+  const J = jsxShape
+
+  const waives = (source: string): boolean => !run(source).rules.has('no-raw-font-size')
 
   it.each([
+    ['// own line', `// ${A}\nexport const C = ${T}\n`],
+    ['// indented', `function f() {\n  // ${A}\n  return ${T}\n}\n`],
+    ['// no space after the marker', `//${A}\nexport const C = ${T}\n`],
+    ['// trailing', `export const C = ${T} // ${A}\n`],
     [
-      'own line //',
-      `// theme-allow no-raw-font-size — deliberate\nexport const C = <Text fz={10} />\n`,
-    ],
-    [
-      'trailing //',
-      `export const C = <Text fz={10} /> // theme-allow no-raw-font-size — deliberate\n`,
+      '// reason wrapped onto a second // comment',
+      `// ${A},\n// continued here\nexport const C = ${T}\n`,
     ],
+    ['/* */ own line', `/* ${A} */\nexport const C = ${T}\n`],
+    ['/* */ trailing', `export const C = ${T} /* ${A} */\n`],
+    ['/** */ own line (docblock opener)', `/** ${A} */\nexport const C = ${T}\n`],
+    ['/* opener + token, closer on its own line', `/* ${A}\n*/\nexport const C = ${T}\n`],
+    ['/* gutter token, closer on the token line', `/*\n ${A} */\nexport const C = ${T}\n`],
+    ['/* gutter token, closer on its own line', `/*\n ${A}\n*/\nexport const C = ${T}\n`],
+    ['/** star gutter, closer on the token line', `/**\n * ${A} */\nexport const C = ${T}\n`],
+    ['/** star gutter, closer on its own line', `/**\n * ${A}\n */\nexport const C = ${T}\n`],
+    ['/** token then 1 prose line', `/**\n * ${A}\n * more\n */\nexport const C = ${T}\n`],
     [
-      'trailing block',
-      `export const C = <Text fz={10} /* theme-allow no-raw-font-size — deliberate */ />\n`,
+      '/** token then 12 prose lines',
+      `/**\n * ${A}\n${' * p\n'.repeat(12)} */\nexport const C = ${T}\n`,
     ],
     [
-      'JSX expression comment',
-      `export const C = () => (\n  <div>\n    {/* theme-allow no-raw-font-size — deliberate */}\n    <Text fz={10} />\n  </div>\n)\n`,
+      '/** prose first, token on a later gutter line',
+      `/**\n * some prose\n * ${A}\n */\nexport const C = ${T}\n`,
     ],
+    ['{/* */} own line', J(`    {/* ${A} */}\n    ${T}`)],
+    ['{/* */} trailing on the target line', J(`    ${T} {/* ${A} */}`)],
+    ['{/* opener + token, closer on its own line', J(`    {/* ${A}\n    */}\n    ${T}`)],
+    ['{/* gutter token, closer on the token line', J(`    {/*\n      ${A} */}\n    ${T}`)],
+    ['{/* gutter token, closer on its own line', J(`    {/*\n      ${A}\n    */}\n    ${T}`)],
+    ['{/** star gutter, closer on the token line', J(`    {/**\n     * ${A} */}\n    ${T}`)],
+    ['{/** star gutter, closer on its own line', J(`    {/**\n     * ${A}\n     */}\n    ${T}`)],
     [
-      'JSX expression comment, token on its own wrapped line',
-      `export const C = () => (\n  <div>\n    {/*\n      theme-allow no-raw-font-size — deliberate */}\n    <Text fz={10} />\n  </div>\n)\n`,
+      '{/** token then 6 prose lines',
+      J(`    {/**\n     * ${A}\n${'     * p\n'.repeat(6)}     */}\n    ${T}`),
     ],
+    ['{/* target on the closer line', J(`    {/*\n      ${A}\n    */}${T}`)],
+    ['{/* closer alone, tab indented', J(`\t{/*\n\t  ${A}\n\t*/}\n\t${T}`)],
+    ['{/* closer alone, space between */ and }', J(`    {/*\n      ${A}\n    */ }\n    ${T}`)],
     [
-      'block gutter',
-      `/**\n * theme-allow no-raw-font-size — deliberate\n */\nexport const C = <Text fz={10} />\n`,
+      '{/* closer alone, two annotations in one block',
+      J(`    {/*\n      ${A}\n      theme-allow card-inset — ${REASON}\n    */}\n    ${T}`),
     ],
     [
-      'docblock opener',
-      `/** theme-allow no-raw-font-size — deliberate */\nexport const C = <Text fz={10} />\n`,
+      '/** */ then an unrelated // note',
+      `/** ${A} */\n// an unrelated note\nexport const C = ${T}\n`,
     ],
+    ['{/* */} then an unrelated {/* */}', J(`    {/* ${A} */}\n    {/* unrelated */}\n    ${T}`)],
+    ['theme-allow-file, {/* closer on its own line', J(`    {/*\n      ${AF}\n    */}\n    ${T}`)],
+    ['theme-allow-file, /** star gutter', `/**\n * ${AF}\n */\nexport const C = ${T}\n`],
   ])('%s waives', (_name, source) => {
-    expect(flags(source as string)).toBe(false)
+    expect(waives(source as string)).toBe(true)
   })
 
-  // The false NEGATIVE the prefix rule exists to close: prose that MENTIONS the token is not an
-  // annotation. linewatch documented its own waivers in a docblock and disarmed the file.
-  it('prose that merely mentions the token does not waive', () => {
-    expect(
-      flags(
-        `// each chart here needs a theme-allow no-raw-font-size eventually\nexport const C = <Text fz={10} />\n`,
-      ),
-    ).toBe(true)
+  // ── UNSUPPORTED — asserted, so a hole can never pass for a design decision ──
+  it.each([
+    ['blank line after a // annotation', `// ${A}\n\nexport const C = ${T}\n`],
+    ['blank line after a {/* */} annotation', J(`    {/* ${A} */}\n\n    ${T}`)],
+    [
+      'blank line after a {/* closer on its own line',
+      J(`    {/*\n      ${A}\n    */}\n\n    ${T}`),
+    ],
+    ['mid-sentence in a line comment', `// we normally write a ${A} here\nexport const C = ${T}\n`],
+    [
+      'mid-sentence in a docblock gutter',
+      `/**\n * Each value is escaped with a ${A} annotation.\n */\nexport const C = ${T}\n`,
+    ],
+    [
+      'mid-sentence in a JSX expression comment',
+      J(`    {/* the shape here is a ${A} comment */}\n    ${T}`),
+    ],
+    [
+      'inside a string literal',
+      `const doc = 'theme-allow no-raw-font-size'\nexport const C = ${T}\n`,
+    ],
+    ['above a multi-line opening tag', J(`    {/* ${A} */}\n    <Text\n      fz={10}\n    />`)],
+  ])('%s does NOT waive', (_name, source) => {
+    expect(waives(source as string)).toBe(false)
   })
 })
 

package/dist/charts/hooks/useBandPlot.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 type { ReactNode, RefObject } from 'react';
+import type { ChartMargin } from '../../tokens/index.js';
+import type { CursorResolution } from '../cursor/resolve.js';
+import type { ChartCursor, CursorAnchor } from './useChartCursor.js';
+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;
+};
+/**
+ * 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 declare function foldBands<T>(data: readonly T[], cap: number, merge: (group: T[]) => T): T[];
+/** 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 declare function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T>;
+export {};
+//# sourceMappingURL=useBandPlot.d.ts.map

package/dist/charts/hooks/useBandPlot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBandPlot.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/useBandPlot.ts"],"names":[],"mappings":"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"}

package/dist/charts/hooks/useBandPlot.js

@@ -0,0 +1,127 @@
+import { scaleBand } from "@visx/scale";
+import { useCallback, useMemo, useRef } from "react";
+import { VX } from "../../tokens/index.js";
+import { autoMargin } from "../layout/auto-margin.js";
+import { maxTextWidth } from "../utils/measure-text.js";
+import { smartTicks } from "../utils/ticks.js";
+import { useChartCursor } from "./useChartCursor.js";
+const DEFAULT_MIN_BAND_PX = 3;
+const TERMINAL_GUTTER_MAX_FRACTION = { left: 0.14, right: 0.12 };
+function foldBands(data, cap, merge) {
+  if (cap <= 0) return [];
+  if (data.length <= cap) return [...data];
+  const groupSize = Math.ceil(data.length / cap);
+  const out = [];
+  for (let i = 0; i < data.length; i += groupSize) out.push(merge(data.slice(i, i + groupSize)));
+  return out;
+}
+function useBandPlot(input) {
+  const {
+    data,
+    chartId,
+    getX,
+    formatX,
+    width,
+    fold,
+    cursorResolution,
+    xTickValues,
+    leftLabels,
+    margin: marginOverride,
+    tooltip
+  } = input;
+  const hasLeftAxis = leftLabels !== void 0 && leftLabels.length > 0;
+  const xLabelsAll = useMemo(() => data.map((d) => formatX(getX(d))), [data, getX, formatX]);
+  const margin = useMemo(() => {
+    const measured = autoMargin({
+      ...leftLabels !== void 0 && { left: leftLabels },
+      bottom: xLabelsAll,
+      ...marginOverride !== void 0 && { override: marginOverride }
+    });
+    if (marginOverride?.left !== void 0 && marginOverride.right !== void 0) return measured;
+    const halfXLabel = Math.ceil(maxTextWidth(xLabelsAll, VX.axisFont) / 2);
+    const left = hasLeftAxis ? measured.left : Math.max(measured.left, halfXLabel);
+    return {
+      ...measured,
+      ...marginOverride?.left === void 0 && {
+        left: hasLeftAxis ? left : capTerminalGutter(left, width, TERMINAL_GUTTER_MAX_FRACTION.left, VX.margin.left)
+      },
+      ...marginOverride?.right === void 0 && {
+        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);
+  const minBandPx = fold?.minBandPx ?? DEFAULT_MIN_BAND_PX;
+  const merge = fold?.merge;
+  const bands = useMemo(
+    () => merge === void 0 ? [...data] : foldBands(data, Math.floor(plotWidth / minBandPx), merge),
+    [data, plotWidth, minBandPx, merge]
+  );
+  const keys = useMemo(() => bands.map(getX), [bands, getX]);
+  const scale = useMemo(
+    () => scaleBand({ domain: keys, range: [0, plotWidth] }),
+    [keys, plotWidth]
+  );
+  const bandCenter = useCallback(
+    (key) => {
+      const v = scale(key);
+      return v === void 0 ? void 0 : v + scale.bandwidth() / 2;
+    },
+    [scale]
+  );
+  const cursor = useChartCursor({
+    data: bands,
+    chartId,
+    getKey: getX,
+    xScale: bandCenter,
+    marginLeft: margin.left,
+    ...cursorResolution !== void 0 && { resolution: cursorResolution }
+  });
+  const tickValues = useMemo(
+    () => [
+      ...xTickValues === void 0 ? smartTicks(keys, plotWidth) : xTickValues(keys, plotWidth)
+    ],
+    [keys, plotWidth, xTickValues]
+  );
+  const svgRef = useRef(null);
+  const point = cursor.point;
+  const crosshairX = point === null ? null : bandCenter(getX(point)) ?? null;
+  const cfg = tooltip === false ? void 0 : tooltip;
+  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 ? void 0 : svgRef.current?.getBoundingClientRect();
+  const tooltipAnchor = svgRect === void 0 || 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
+  };
+}
+function capTerminalGutter(gutter, width, fraction, floor) {
+  return Math.min(gutter, Math.max(floor, Math.round(width * fraction)));
+}
+export {
+  foldBands,
+  useBandPlot
+};

package/dist/charts/index.d.ts

@@ -20,6 +20,7 @@ export { CartesianChart, resolveAxisDomain, type CartesianChartProps, type Carte
 export { ChartFrame, type ChartFrameProps, type ChartFrameLegend, type PlotRect, resolveLegend, } from './primitives/ChartFrame.js';
 export { ChartCenter, type ChartCenterProps, ChartPending, type ChartPendingProps, } from './primitives/ChartPending.js';
 export { Crosshair, SeriesDot } from './primitives/Crosshair.js';
+export { HatchPattern, hatchFill, hatchSizeFor } from './primitives/HatchPattern.js';
 export { ChartCard } from './primitives/ChartCard.js';
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend.js';
 export { ChartTooltipFloat, TooltipHeader, TooltipRow, TooltipBody, } from './primitives/ChartTooltip.js';
@@ -29,6 +30,7 @@ export { ZoneRects, type ZoneSpec } from './primitives/ZoneRects.js';
 export { XZoneRects, type XZoneSpec } from './primitives/XZoneRects.js';
 export { AreaGradient, areaFillUrl } from './primitives/AreaGradient.js';
 export { useChartCursor, type ChartCursor, type CursorAnchor } from './hooks/useChartCursor.js';
+export { foldBands, type BandFold, type BandTooltipConfig, type BandTooltipRowContext, } from './hooks/useBandPlot.js';
 export type { CursorResolution } from './cursor/resolve.js';
 export { useChartSize, type UseChartSizeResult, type ChartSize } from './hooks/useChartSize.js';
 export { fmtAxisDate, fmtTooltipDate } from './utils/format.js';
@@ -42,6 +44,8 @@ export { Donut, type DonutProps, type DonutDatum } from './kinds/Donut.js';
 export { MultiLine, type MultiLineProps } from './kinds/MultiLine.js';
 export { DualPanel, type DualPanelProps } from './kinds/DualPanel.js';
 export { Heatmap, type HeatmapProps } from './kinds/Heatmap.js';
+export { BandStrip, type BandStripProps, type BandStripSeries, type BandSpan, } from './kinds/BandStrip.js';
+export { MirroredBars, type MirroredBarsProps, type MirroredBarPane } from './kinds/MirroredBars.js';
 export { LineSparkline, BarSparkline } from './sparklines/index.js';
 export { Group } from '@visx/group';
 export { GridRows, GridColumns } from '@visx/grid';

package/dist/charts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/charts/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/charts/index.ts"],"names":[],"mappings":"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"}

package/dist/charts/index.js

@@ -30,6 +30,7 @@ import {
   ChartPending
 } from "./primitives/ChartPending.js";
 import { Crosshair, SeriesDot } from "./primitives/Crosshair.js";
+import { HatchPattern, hatchFill, hatchSizeFor } from "./primitives/HatchPattern.js";
 import { ChartCard } from "./primitives/ChartCard.js";
 import { ChartLegend } from "./primitives/ChartLegend.js";
 import {
@@ -44,6 +45,9 @@ import { ZoneRects } from "./primitives/ZoneRects.js";
 import { XZoneRects } from "./primitives/XZoneRects.js";
 import { AreaGradient, areaFillUrl } from "./primitives/AreaGradient.js";
 import { useChartCursor } from "./hooks/useChartCursor.js";
+import {
+  foldBands
+} from "./hooks/useBandPlot.js";
 import { useChartSize } from "./hooks/useChartSize.js";
 import { fmtAxisDate, fmtTooltipDate } from "./utils/format.js";
 import { smartTicks, smartTicksEvery } from "./utils/ticks.js";
@@ -60,6 +64,10 @@ import { Donut } from "./kinds/Donut.js";
 import { MultiLine } from "./kinds/MultiLine.js";
 import { DualPanel } from "./kinds/DualPanel.js";
 import { Heatmap } from "./kinds/Heatmap.js";
+import {
+  BandStrip
+} from "./kinds/BandStrip.js";
+import { MirroredBars } from "./kinds/MirroredBars.js";
 import { LineSparkline, BarSparkline } from "./sparklines/index.js";
 import { Group } from "@visx/group";
 import { GridRows, GridColumns } from "@visx/grid";
@@ -80,6 +88,7 @@ export {
   AxisBottomDate,
   AxisLeftNumeric,
   AxisRightNumeric,
+  BandStrip,
   Bar,
   BarGroup,
   BarSparkline,
@@ -99,11 +108,13 @@ export {
   GridColumns,
   GridRows,
   Group,
+  HatchPattern,
   Heatmap,
   HoverOverlay,
   Line,
   LinePath,
   LineSparkline,
+  MirroredBars,
   MultiLine,
   Pie,
   SeriesDot,
@@ -133,8 +144,11 @@ export {
   deriveTooltipRows,
   fmtAxisDate,
   fmtTooltipDate,
+  foldBands,
   globalCursorStore,
   groupTokens,
+  hatchFill,
+  hatchSizeFor,
   maxTextWidth,
   measureText,
   probeAxisLabels,

package/dist/charts/kinds/BandStrip.d.ts

@@ -0,0 +1,127 @@
+import type { ChartMargin } from '../../tokens/index.js';
+import type { CursorResolution } from '../cursor/resolve.js';
+import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot.js';
+import type { ChartLegendConfig, SeriesStyle } from '../series.js';
+/**
+ * A state a strip can draw. Extends `SeriesStyle` rather than `ChartSeries` because a band has no
+ * numeric value to plot — `formatValue` reads the datum directly.
+ */
+export type BandStripSeries<T> = SeriesStyle & {
+    /**
+     * The derived tooltip row's value for a band in this state.
+     *
+     * Return `null` for a datum in this state whose reading is ABSENT — the row renders
+     * {@link NO_READING} instead, which is the escape `ChartSeries.getValue` has and this shape did
+     * not: with no value accessor, an absent reading had to come back as `''` and render as a label
+     * with an empty value, indistinguishable from a state whose name is the whole reading.
+     *
+     * Omit the function entirely for a state whose NAME *is* the whole reading ("Not measured").
+     */
+    formatValue?: (d: T) => string | null;
+};
+/** One drawn band — which state it is in, and the three ways a state can be qualified. */
+export type BandSpan = {
+    /**
+     * Series key naming this band's state: the tie to its legend entry, its fill, and its derived
+     * tooltip row.
+     *
+     * A key not present in `series` is a bug TypeScript cannot catch (this is a `string`), and it
+     * used to draw NOTHING — which on a strip whose vocabulary is measured/not-measured is
+     * indistinguishable from a real coverage gap, so a typo silently asserted "not measured". It now
+     * throws in development and draws an explicit unknown band in production; see
+     * {@link unknownStateError} for why the two differ.
+     */
+    state: string;
+    /**
+     * Overrides the fill derived from the state's series entry — the seam for an intensity ramp
+     * WITHIN one state (5% loss vs 0.5% loss are the same state at different strengths). Build it
+     * with `alpha(VX.*, …)`, never a raw hex.
+     */
+    fill?: string;
+    /**
+     * 0..1 of this band's width that no source sample covers, drawn hatched from the band's right.
+     *
+     * This is what a fold owes the reader. A 1-of-3-measured slot whose merge reports the one
+     * measured member's reading paints, without this, as a fully-measured band — a reading asserted
+     * over two slots that reported nothing either way.
+     */
+    absentFraction?: number;
+    /**
+     * A shorter, inset bar drawn over the band — for a fact that must NOT be readable off the fill
+     * ramp (a renegotiation, a restart, a config change). Its colour comes from a `series` entry, so
+     * it cannot be drawn in a hue the legend does not name.
+     */
+    marker?: {
+        /** Series key naming the marker's colour. Defaults to the band's own `state`. */
+        state?: string;
+        /** Vertical inset from the band's top and bottom, in px. Default 6. */
+        inset?: number;
+    };
+};
+export type BandStripProps<T> = {
+    data: readonly T[];
+    /** Stable id — identifies this chart as the cursor's source. */
+    chartId: string;
+    /** Extracts the x-domain key. On a band strip this is a SLOT START, so `cursorResolution`
+     * defaults to `'leading'` (see below) rather than `CartesianChart`'s `'nearest'`. */
+    getX: (d: T) => string;
+    /** The states this strip can draw — the single source of truth for legend entries, band fills,
+     * and the derived tooltip row. */
+    series: readonly BandStripSeries<T>[];
+    /** Which state each datum is in. */
+    getBand: (d: T) => BandSpan;
+    /** Fixed height in px, forwarded to `ChartFrame`. The band row gets whatever the measured
+     * margins and the measured legend band leave. Default 240. */
+    height?: number;
+    /** Fill the parent flex/grid cell's measured height instead of a fixed one. */
+    fill?: boolean;
+    /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
+    formatX?: (key: string) => string;
+    /** Which keys get a tick. Default `smartTicks`. */
+    xTickValues?: (keys: readonly string[], plotWidth: number) => readonly string[];
+    /** Collapse adjacent data at widths where one band per datum sub-pixels. */
+    fold?: BandFold<T>;
+    /**
+     * How a sibling's broadcast cursor key resolves against this strip's slots. Default
+     * `'leading'` — strict containment, "the slot that swallowed this key" — because a band IS a
+     * span keyed by its leading edge, and it stays correct at every fold width. `'nearest'` puts
+     * the crosshair one slot right for every source key in the back half of a slot.
+     */
+    cursorResolution?: CursorResolution;
+    tooltip?: BandTooltipConfig<T> | false;
+    legend?: ChartLegendConfig | false;
+    /** Colour of the absence hatch. Names a `series` entry, so absence is legended like any other
+     * state — a hatched band is the one mark a reader cannot decode from an axis. Default
+     * `VX.neutral`, unnamed. A key naming no `series` entry throws (a PROP, so a typo can only be a
+     * wiring error) rather than falling back to the unnamed default. */
+    absentState?: string;
+    /** Per-side overrides of the measured margins — applied last. */
+    margin?: Partial<ChartMargin>;
+    /** Accessible text alternative, forwarded to `ChartFrame` (+ `role="group"`) and to the
+     * focusable hover overlay's slider label. */
+    ariaLabel?: string;
+    /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc. */
+    isPending?: boolean;
+};
+/**
+ * A 1-D categorical band strip: one rect per slot over a shared x axis, no y dimension at all.
+ *
+ * `CartesianChart` cannot host this. It renders `AxisLeftNumeric` unconditionally, so composing it
+ * would draw a numeric axis over a chart that measures nothing vertically — and its `scalePoint` x
+ * scale has positions but no widths, which is the whole content of a strip. This is the
+ * non-single-plot escape `docs/CHARTS-SPEC.md` § "The contract" describes, assembled from the same
+ * parts every other chart gets (`ChartFrame`, `autoMargin`, `useChartCursor`, `ChartTooltipFloat`)
+ * via `useBandPlot`, never re-implemented.
+ *
+ * The three qualifications on {@link BandSpan} — `fill`, `absentFraction`, `marker` — are the ones
+ * a state strip cannot do without: an intensity ramp inside a state, the share of a folded slot
+ * nothing measured, and a fact that must not be read off the ramp.
+ */
+declare function BandStripInner<T>(props: BandStripProps<T>): import("react").JSX.Element;
+/**
+ * Hand-memoized: React Compiler does not process the shipped dist, so the hot kind is wrapped in
+ * `React.memo` to retain the auto-memoization it had as source (parity with `DualPanel`).
+ */
+export declare const BandStrip: typeof BandStripInner;
+export {};
+//# sourceMappingURL=BandStrip.d.ts.map