basalt-ui 1.41.0 → 2.0.0

package/dist/agent/use-agent-thread-runs.js

@@ -1,8 +1,22 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { toAgentError } from "./error.js";
 import { mintMessageId, mintThreadId, withPartIds } from "./id.js";
 import { mergePart } from "./merge.js";
 import { isStartPart } from "./parts.js";
+import { createRunCommitter, isContentPart } from "./run-committer.js";
+import {
+  beginRun,
+  endRun,
+  failedThreadIds,
+  dismissRun,
+  hasLiveRun,
+  isLatestRun,
+  isLive,
+  planStopWithTombstone,
+  sweepFlushed
+} from "./run-records.js";
 import { isResumable } from "./transport.js";
+import { TelemetryContext, createEmitter, errorName, now } from "../telemetry.js";
 function defaultToUserParts(input) {
   return [{ id: mintThreadId(), type: "text", text: input }];
 }
@@ -29,36 +43,47 @@ function buildDoneSnapshot(priorThread, threadId, userMessage, assistantMessage)
 async function consumeAndFinalize(args) {
   const {
     threadId,
-    controller,
+    record,
     generator,
     userMessage,
-    controllersRef,
-    appendedRef,
+    recordsRef,
     storeRef,
     resolveOutcome,
     setRuns,
     onFailureStatus,
+    throttle,
+    emit,
     onError
   } = args;
+  const { controller } = record;
+  const live = () => isLive(recordsRef.current, threadId, controller);
+  const owns = () => isLatestRun(record);
   let parts = [];
+  const startedAt = now();
+  let firstContentAt;
+  const committer = createRunCommitter(throttle, (committed, status) => {
+    if (!live()) return;
+    setRuns((prev) => {
+      const next = new Map(prev);
+      next.set(threadId, { status, parts: committed });
+      return next;
+    });
+  });
   try {
     for await (const part of generator) {
-      if (controllersRef.current.get(threadId) !== controller) return;
-      if (controller.signal.aborted) return;
+      if (!live()) return;
       if (isStartPart(part)) {
         storeRef.current.setResumeToken(threadId, part.resumeToken);
         continue;
       }
       parts = mergePart(parts, part);
-      setRuns((prev) => {
-        const next = new Map(prev);
-        next.set(threadId, { status: "streaming", parts });
-        return next;
-      });
-    }
-    if (controllersRef.current.get(threadId) !== controller || controller.signal.aborted) {
-      return;
+      record.parts = parts;
+      const firstContent = firstContentAt === void 0 && isContentPart(part);
+      if (firstContent) firstContentAt = now();
+      committer.push(parts, firstContentAt === void 0 ? "submitted" : "streaming", firstContent);
     }
+    committer.flush();
+    if (!live()) return;
     const assistantMessage = {
       // appendMessage's idempotency key — mintMessageId, never mintThreadId (see that helper's
       // doc): a collided id here would silently drop this message, not merge a duplicate thread.
@@ -69,42 +94,83 @@ async function consumeAndFinalize(args) {
       finish: "complete"
     };
     storeRef.current.appendMessage(threadId, assistantMessage);
-    appendedRef.current.set(threadId, controller);
+    record.appended = true;
     const priorThread = storeRef.current.threads.find((thread) => thread.id === threadId);
     const snapshot = buildDoneSnapshot(priorThread, threadId, userMessage, assistantMessage);
-    const outcome = await resolveOutcome(snapshot);
-    if (controllersRef.current.get(threadId) !== controller || controller.signal.aborted) {
+    record.resolving = true;
+    let outcome;
+    try {
+      outcome = await resolveOutcome(snapshot);
+    } finally {
+      record.resolving = false;
+    }
+    if (!live()) {
+      if (record.ended === "stopped" && record.appended && owns()) {
+        storeRef.current.setOutcome(threadId, outcome);
+      }
       return;
     }
     storeRef.current.setOutcome(threadId, outcome);
     storeRef.current.setStatus(threadId, outcome.status);
     storeRef.current.setResumeToken(threadId, void 0);
-    controllersRef.current.delete(threadId);
-    appendedRef.current.delete(threadId);
+    endRun(record, "settled");
     setRuns((prev) => {
       if (!prev.has(threadId)) return prev;
       const next = new Map(prev);
       next.delete(threadId);
       return next;
     });
+    emit(
+      buildTurnEvent({
+        threadId,
+        startedAt,
+        firstContentAt,
+        partCount: parts.length,
+        status: outcome.status
+      })
+    );
   } catch (err) {
-    if (err instanceof Error && err.name === "AbortError") return;
-    if (controllersRef.current.get(threadId) !== controller) return;
-    if (controller.signal.aborted) return;
+    if (!live()) {
+      if (record.ended === "stopped" && record.appended) onError?.({ threadId, error: err });
+      return;
+    }
+    const agentError = toAgentError(err);
+    const messageLanded = record.appended;
+    endRun(record, "failed");
     storeRef.current.setStatus(threadId, onFailureStatus);
-    controllersRef.current.delete(threadId);
-    appendedRef.current.delete(threadId);
+    const failedParts = messageLanded ? [] : parts;
     setRuns((prev) => {
-      if (!prev.has(threadId)) return prev;
       const next = new Map(prev);
-      next.delete(threadId);
+      next.set(threadId, { status: "error", parts: failedParts, error: agentError });
       return next;
     });
+    emit(
+      buildTurnEvent({
+        threadId,
+        startedAt,
+        firstContentAt,
+        partCount: parts.length,
+        status: onFailureStatus,
+        failure: { error: err, agentError }
+      })
+    );
     onError?.({ threadId, error: err });
+  } finally {
+    committer.cancel();
   }
 }
 async function finalizeStop(args) {
-  const { threadId, parts, alreadyAppended, storeRef, resolveOutcome, setRuns } = args;
+  const {
+    threadId,
+    parts,
+    alreadyAppended,
+    outcomeInFlight,
+    record,
+    onError,
+    storeRef,
+    resolveOutcome,
+    setRuns
+  } = args;
   let appendFailed = false;
   if (!alreadyAppended && parts.length > 0) {
     try {
@@ -141,26 +207,64 @@ async function finalizeStop(args) {
     next.delete(threadId);
     return next;
   });
-  if (settleFailed) return;
+  if (settleFailed || outcomeInFlight) return;
   const snapshot = storeRef.current.threads.find((thread) => thread.id === threadId);
   if (snapshot === void 0) return;
-  const outcome = await resolveOutcome(snapshot);
-  storeRef.current.setOutcome(threadId, outcome);
+  record.resolving = true;
+  try {
+    const outcome = await resolveOutcome(snapshot);
+    if (isLatestRun(record)) storeRef.current.setOutcome(threadId, outcome);
+  } catch (error) {
+    onError?.({ threadId, error });
+  } finally {
+    record.resolving = false;
+  }
+}
+function buildTurnEvent(args) {
+  const { threadId, startedAt, firstContentAt, partCount, status, failure } = args;
+  const endedAt = now();
+  const base = {
+    start: startedAt,
+    duration: endedAt - startedAt
+  };
+  const attributes = {
+    "basalt.chat.thread_id": threadId,
+    "basalt.chat.ttft_ms": (firstContentAt ?? endedAt) - startedAt,
+    "basalt.chat.parts": partCount,
+    "basalt.chat.status": status
+  };
+  if (failure === void 0) return { ...base, type: "chat.turn", failed: false, attributes };
+  return {
+    ...base,
+    type: "chat.turn",
+    failed: true,
+    attributes: {
+      ...attributes,
+      "exception.type": errorName(failure.error),
+      "basalt.error.kind": failure.agentError.kind
+    }
+  };
 }
 function useAgentThreadRuns({
   transport,
   store,
   resolveOutcome,
   toUserParts,
-  onError
+  onError,
+  throttle = 100,
+  telemetry
 }) {
   const [runs, setRuns] = useState(/* @__PURE__ */ new Map());
   const runsRef = useRef(runs);
   runsRef.current = runs;
   const onErrorRef = useRef(onError);
   onErrorRef.current = onError;
-  const controllersRef = useRef(/* @__PURE__ */ new Map());
-  const appendedRef = useRef(/* @__PURE__ */ new Map());
+  const providerSink = useContext(TelemetryContext);
+  const telemetryRef = useRef(telemetry ?? providerSink);
+  telemetryRef.current = telemetry ?? providerSink;
+  const throttleRef = useRef(throttle);
+  throttleRef.current = throttle;
+  const recordsRef = useRef(/* @__PURE__ */ new Map());
   const lastInputRef = useRef(/* @__PURE__ */ new Map());
   const storeRef = useRef(store);
   storeRef.current = store;
@@ -170,6 +274,10 @@ function useAgentThreadRuns({
   const resolvedToUserParts = toUserParts ?? defaultToUserParts;
   const toUserPartsRef = useRef(resolvedToUserParts);
   toUserPartsRef.current = resolvedToUserParts;
+  const emitTelemetry = useMemo(
+    () => createEmitter((event) => telemetryRef.current?.(event)),
+    []
+  );
   const resolveTransport = (threadId) => {
     const currentTransport = transportRef.current;
     if (typeof currentTransport !== "function") return currentTransport;
@@ -181,10 +289,13 @@ function useAgentThreadRuns({
   };
   useEffect(
     () => () => {
-      const abortedThreadIds = Array.from(controllersRef.current.keys());
-      controllersRef.current.forEach((controller) => controller.abort());
-      controllersRef.current.clear();
-      appendedRef.current.clear();
+      const abortedThreadIds = [];
+      for (const [threadId, record] of recordsRef.current) {
+        if (record.ended !== void 0) continue;
+        abortedThreadIds.push(threadId);
+        record.controller.abort();
+      }
+      recordsRef.current.clear();
       if (abortedThreadIds.length === 0) return;
       setRuns((prev) => {
         let next;
@@ -198,10 +309,13 @@ function useAgentThreadRuns({
     },
     []
   );
+  useEffect(() => {
+    sweepFlushed(recordsRef.current, runs);
+  });
   useEffect(() => {
     if (!store.hydrated) return;
     for (const thread of storeRef.current.threads) {
-      const orphaned = (thread.status === "pending" || thread.status === "streaming") && !controllersRef.current.has(thread.id);
+      const orphaned = (thread.status === "pending" || thread.status === "streaming") && !hasLiveRun(recordsRef.current, thread.id);
       if (!orphaned) continue;
       const resumeToken = thread.resumeToken;
       const lastUserMessage = thread.messages.filter((message) => message.role === "user").at(-1);
@@ -212,15 +326,15 @@ function useAgentThreadRuns({
       }
       const resume = resolvedTransport.resume;
       const controller = new AbortController();
-      controllersRef.current.set(thread.id, controller);
+      const record = beginRun(recordsRef.current, thread.id, controller);
       setRuns((prev) => {
         const next = new Map(prev);
-        next.set(thread.id, { status: "streaming", parts: [] });
+        next.set(thread.id, { status: "submitted", parts: [] });
         return next;
       });
       void consumeAndFinalize({
         threadId: thread.id,
-        controller,
+        record,
         // Namespaced by thread.id (stable across a thread's whole lifetime, including this
         // resume) rather than per-call — see withPartIds' own doc for why this is NOT a replay-
         // convergence guarantee on its own: it only protects against two id-less drafts within
@@ -230,19 +344,20 @@ function useAgentThreadRuns({
         // providing that safety.
         generator: withPartIds(thread.id, resume(resumeToken, controller.signal)),
         userMessage: lastUserMessage,
-        controllersRef,
-        appendedRef,
+        recordsRef,
         storeRef,
         resolveOutcome,
         setRuns,
         onFailureStatus: "interrupted",
+        throttle: throttleRef.current,
+        emit: emitTelemetry,
         onError: (info) => onErrorRef.current?.(info)
       });
     }
   }, [store.hydrated]);
   const start = useCallback(
     (threadId, input) => {
-      if (controllersRef.current.has(threadId)) return;
+      if (hasLiveRun(recordsRef.current, threadId)) return;
       lastInputRef.current.set(threadId, input);
       const userMessage = {
         // Same idempotency-key reasoning as consumeAndFinalize's assistantMessage — mintMessageId.
@@ -255,15 +370,15 @@ function useAgentThreadRuns({
       storeRef.current.setStatus(threadId, "streaming");
       setRuns((prev) => {
         const next = new Map(prev);
-        next.set(threadId, { status: "streaming", parts: [] });
+        next.set(threadId, { status: "submitted", parts: [] });
         return next;
       });
       const controller = new AbortController();
-      controllersRef.current.set(threadId, controller);
+      const record = beginRun(recordsRef.current, threadId, controller);
       const resolvedTransport = resolveTransport(threadId);
       void consumeAndFinalize({
         threadId,
-        controller,
+        record,
         // Namespaced by threadId — same choice, same caveat, as the mount-time resume call above.
         // ctx.messageId is this turn's OWN idempotency key (userMessage.id, just minted above) —
         // a transport that accepts it (aiSdkTransport) mints its wire-level message with the SAME
@@ -273,16 +388,17 @@ function useAgentThreadRuns({
           resolvedTransport.stream(input, controller.signal, { messageId: userMessage.id })
         ),
         userMessage,
-        controllersRef,
-        appendedRef,
+        recordsRef,
         storeRef,
         resolveOutcome,
         setRuns,
         onFailureStatus: "error",
+        throttle: throttleRef.current,
+        emit: emitTelemetry,
         onError: (info) => onErrorRef.current?.(info)
       });
     },
-    [resolveOutcome]
+    [emitTelemetry, resolveOutcome]
   );
   const retry = useCallback(
     (threadId) => {
@@ -292,30 +408,50 @@ function useAgentThreadRuns({
     },
     [start]
   );
+  const dismiss = useCallback((threadId) => {
+    dismissRun(recordsRef.current, threadId);
+    setRuns((prev) => {
+      if (!prev.has(threadId)) return prev;
+      const next = new Map(prev);
+      next.delete(threadId);
+      return next;
+    });
+  }, []);
   const stop = useCallback(
     (threadId) => {
-      const controller = controllersRef.current.get(threadId);
-      if (controller === void 0) {
-        if (!runsRef.current.has(threadId)) return;
-        const parts2 = runsRef.current.get(threadId)?.parts ?? [];
-        const alreadyAppended2 = appendedRef.current.has(threadId);
-        appendedRef.current.delete(threadId);
-        void finalizeStop({ threadId, parts: parts2, alreadyAppended: alreadyAppended2, storeRef, resolveOutcome, setRuns });
+      const plan = planStopWithTombstone(
+        recordsRef.current,
+        threadId,
+        runsRef.current.get(threadId)
+      );
+      if (plan.kind === "noop") return;
+      if (plan.kind === "dismiss") {
+        dismiss(threadId);
         return;
       }
-      controllersRef.current.delete(threadId);
-      const parts = runsRef.current.get(threadId)?.parts ?? [];
-      controller.abort();
-      const alreadyAppended = appendedRef.current.get(threadId) === controller;
-      appendedRef.current.delete(threadId);
-      void finalizeStop({ threadId, parts, alreadyAppended, storeRef, resolveOutcome, setRuns });
+      const { record, parts } = plan;
+      const { appended, resolving } = record;
+      endRun(record, "stopped");
+      record.controller.abort();
+      void finalizeStop({
+        threadId,
+        parts,
+        alreadyAppended: appended,
+        outcomeInFlight: resolving,
+        record,
+        storeRef,
+        resolveOutcome,
+        setRuns,
+        onError: (info) => onErrorRef.current?.(info)
+      });
     },
-    [resolveOutcome]
+    [dismiss, resolveOutcome]
   );
   const stopAll = useCallback(() => {
-    for (const threadId of Array.from(controllersRef.current.keys())) {
-      stop(threadId);
+    for (const [threadId, record] of Array.from(recordsRef.current)) {
+      if (record.ended === void 0) stop(threadId);
     }
+    for (const threadId of failedThreadIds(recordsRef.current, runsRef.current)) stop(threadId);
   }, [stop]);
   return { runs, start, retry, stop, stopAll };
 }

package/dist/charts/BandStrip.d.ts

@@ -0,0 +1,46 @@
+import type { ReactElement } from 'react';
+import type { CartesianChartProps, ChartSeries, ChartX } from './types.js';
+/** A state a strip can draw. A band has no number to plot, so `formatValue` reads the datum. */
+export type BandStripSeries<T> = Pick<ChartSeries<T>, 'key' | 'label' | 'color' | 'tooltip' | 'legend' | 'note' | 'fillOpacity'> & {
+    /**
+     * The tooltip row's value for a band in this state. `null` is an ABSENT reading and renders an
+     * em dash; omit the function when the state's name is the whole reading ("Not measured").
+     */
+    formatValue?: (d: T) => string | null;
+};
+/** One band: its state, and the two ways to qualify it. */
+export type BandSpan = {
+    /** A `states` key: the band's legend entry, fill and tooltip row. */
+    state: string;
+    /** Overrides the state's fill — an intensity ramp WITHIN a state. `alpha(VX.*, …)`, never a hex. */
+    fill?: string;
+    /**
+     * A shorter, inset bar over the band, for a fact that must not be read off the fill ramp (a
+     * renegotiation, a restart). Its color is a `states` entry, so the legend names it.
+     */
+    marker?: {
+        /** Defaults to the band's own `state`. */
+        state?: string;
+        /** Vertical inset from the band's top and bottom, in px. Default 6. */
+        inset?: number;
+    };
+};
+/** Collapse adjacent data where one band per datum would be thinner than `minBandPx`. */
+export type BandFold<T> = {
+    /** Floor on a drawn band's px width. Default 3. */
+    minBandPx?: number;
+    /**
+     * The consumer's merge of a group of adjacent data into the datum drawn in its place — whether
+     * that is a max, a sum or a recomputed rate is a question about the measurement. Keep the first
+     * datum's `x`, or the cursor key stops naming a real slot.
+     */
+    merge: (group: T[]) => T;
+};
+export type BandStripProps<T, X extends ChartX = ChartX> = Omit<CartesianChartProps<T, X>, 'marks' | 'series' | 'y' | 'y2' | 'zones' | 'xZones' | 'refLines'> & {
+    states: readonly BandStripSeries<T>[];
+    /** Which state, fill and marker each datum has. Memoize it: a new function recompiles the chart. */
+    getBand: (d: T) => BandSpan;
+    fold?: BandFold<T>;
+};
+export declare function BandStrip<T, X extends ChartX = ChartX>(props: BandStripProps<T, X>): ReactElement;
+//# sourceMappingURL=BandStrip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BandStrip.d.ts","sourceRoot":"","sources":["../../src/charts/BandStrip.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAOzC,OAAO,KAAK,EAEV,mBAAmB,EAEnB,WAAW,EACX,MAAM,EAGP,MAAM,SAAS,CAAA;AAEhB,gGAAgG;AAChG,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,IAAI,CACnC,WAAW,CAAC,CAAC,CAAC,EACd,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,aAAa,CAC1E,GAAG;IACF;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;CACtC,CAAA;AAED,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG;IACrB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,oGAAoG;IACpG,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,0CAA0C;QAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,uEAAuE;QACvE,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;CACF,CAAA;AAED,yFAAyF;AACzF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CAC7D,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EACzB,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAClE,GAAG;IACF,MAAM,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,CAAA;IACrC,oGAAoG;IACpG,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAA;IAC3B,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;CACnB,CAAA;AAuHD,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,YAAY,CA0EjG"}

package/dist/charts/BandStrip.js

@@ -0,0 +1,151 @@
+import { jsx } from "react/jsx-runtime";
+import { barY } from "@tanstack/charts/bar";
+import { decorative } from "@tanstack/charts/mark/decorative";
+import { rect } from "@tanstack/charts/rect";
+import { useCallback, useMemo } from "react";
+import { oneOf } from "../common/errors.js";
+import { NON_FINITE } from "../format/shared.js";
+import { VX, alpha } from "../tokens/index.js";
+import { CartesianRung } from "./CartesianChart.js";
+import { emphasis } from "./marks.js";
+import { rowX } from "./types.js";
+const DEFAULT_MIN_BAND_PX = 3;
+const DEFAULT_MARKER_INSET = 6;
+const STRIP_AXIS = {
+  domain: [0, 1],
+  ticks: [],
+  grid: false
+};
+const ZX_ANCHOR = [{ fill: "transparent" }];
+const UNKNOWN_FILL = alpha(VX.neutral, 0.2);
+function groupsOf(data, cap) {
+  const size = Math.max(1, Math.ceil(data.length / Math.max(cap, 1)));
+  const out = [];
+  data.forEach((d, i) => {
+    const last = out.at(-1);
+    if (last && last.items.length < size) last.items.push(d);
+    else out.push({ start: i, items: [d] });
+  });
+  return out;
+}
+function paintInto(layers, fill, opacity, cell) {
+  const key = `${fill}|${opacity}`;
+  const layer = layers.get(key);
+  if (layer) layer.cells.push(cell);
+  else layers.set(key, { fill, opacity, cells: [cell] });
+}
+const unknownState = (prop, got, known) => new Error(oneOf("BandStrip", prop, [...known], got));
+function layoutBands(input) {
+  const { data, getBand, fold, states, visible } = input;
+  const cap = Math.floor(input.width / (fold?.minBandPx ?? DEFAULT_MIN_BAND_PX));
+  const groups = fold && data.length > cap ? groupsOf(data, cap) : data.map((d, start) => ({ start, items: [d] }));
+  const base = /* @__PURE__ */ new Map();
+  const markers = /* @__PURE__ */ new Map();
+  const hits = [];
+  for (const g of groups) {
+    const datum = fold && g.items.length > 1 ? fold.merge(g.items) : g.items[0];
+    if (datum === void 0) continue;
+    const span = getBand(datum);
+    const state = states.get(span.state);
+    if (!state && process.env.NODE_ENV !== "production")
+      throw unknownState("BandSpan.state", span.state, states.keys());
+    if (state && !visible.has(span.state)) continue;
+    const cell = { f0: g.start / data.length, f1: (g.start + g.items.length) / data.length };
+    const opacity = input.emphasis(span.state);
+    paintInto(
+      base,
+      span.fill ?? (state ? alpha(state.color, state.fillOpacity ?? 1) : UNKNOWN_FILL),
+      opacity,
+      { ...cell, y0: 0, y1: 1 }
+    );
+    if (span.marker) {
+      const markerKey = span.marker.state ?? span.state;
+      const markerState = states.get(markerKey);
+      if (!markerState && process.env.NODE_ENV !== "production")
+        throw unknownState("BandSpan.marker.state", markerKey, states.keys());
+      if (!markerState || visible.has(markerKey)) {
+        const inset = (span.marker.inset ?? DEFAULT_MARKER_INSET) / Math.max(input.height, 1);
+        paintInto(markers, markerState?.color ?? UNKNOWN_FILL, input.emphasis(markerKey), {
+          ...cell,
+          y0: inset,
+          y1: 1 - inset
+        });
+      }
+    }
+    if (state) for (const source of g.items) hits.push({ source, state: span.state, datum });
+  }
+  return { base: [...base.values()], markers: [...markers.values()], hits };
+}
+function BandStrip(props) {
+  const { states, getBand, fold, cursorResolution = "leading", tooltip, ...rest } = props;
+  const { data, x } = rest;
+  const series = useMemo(
+    () => states.map((s) => ({
+      key: s.key,
+      label: s.label,
+      color: s.color,
+      mark: "bar",
+      ...s.tooltip !== void 0 && { tooltip: s.tooltip },
+      ...s.legend !== void 0 && { legend: s.legend },
+      ...s.note !== void 0 && { note: s.note },
+      getValue: (d) => getBand(d).state === s.key ? 1 : null,
+      formatValue: (_v, d) => s.formatValue ? s.formatValue(d) ?? NON_FINITE : ""
+    })),
+    [states, getBand]
+  );
+  const marks = useCallback(
+    (plot) => {
+      const { base, markers, hits } = layoutBands({
+        data,
+        getBand,
+        fold,
+        states: new Map(states.map((s) => [s.key, s])),
+        visible: new Set(plot.visible.map((s) => s.key)),
+        width: plot.width,
+        height: plot.height,
+        emphasis: (key) => emphasis(plot.highlighted, { key })
+      });
+      const rows = hits.map((h) => ({
+        x: x(h.source),
+        y: 1,
+        series: h.state,
+        datum: h.datum
+      }));
+      return [
+        ...[...base, ...markers].map(
+          ({ fill, opacity, cells }, i) => decorative(
+            rect(cells, {
+              id: `band-${i}`,
+              x1: "f0",
+              x2: "f1",
+              y1: "y0",
+              y2: "y1",
+              xScale: "zx",
+              fill,
+              inset: 0,
+              ...opacity < 1 && { fillOpacity: opacity }
+            })
+          )
+        ),
+        ...rows.length > 0 ? [barY(rows, { id: "hit", x: rowX, y1: 0, y2: 1, fill: "transparent" })] : []
+      ];
+    },
+    [states, getBand, fold, data, x]
+  );
+  return /* @__PURE__ */ jsx(
+    CartesianRung,
+    {
+      ...rest,
+      series,
+      marks,
+      band: true,
+      y: STRIP_AXIS,
+      xZones: ZX_ANCHOR,
+      cursorResolution,
+      ...tooltip !== void 0 && { tooltip }
+    }
+  );
+}
+export {
+  BandStrip
+};

package/dist/charts/Bars.d.ts

@@ -0,0 +1,19 @@
+import type { ReactElement } from 'react';
+import type { CartesianChartProps, ChartSeries, ChartX } from './types.js';
+/** A bar series. Bars always read the left axis. */
+export type BarsBar<T> = Pick<ChartSeries<T>, 'key' | 'label' | 'color' | 'getValue' | 'formatValue' | 'tooltip' | 'legend' | 'role' | 'note'> & {
+    /** Default 0.85. */
+    fillOpacity?: number;
+};
+/** A line overlay; `axis: 'right'` reads the chart's `y2`. */
+export type BarsLine<T> = Pick<ChartSeries<T>, 'key' | 'label' | 'color' | 'getValue' | 'formatValue' | 'tooltip' | 'legend' | 'role' | 'note' | 'axis' | 'dash' | 'curve' | 'strokeWidth' | 'strokeOpacity'>;
+export type BarsProps<T, X extends ChartX = ChartX> = Omit<CartesianChartProps<T, X>, 'marks' | 'series'> & {
+    bars: readonly BarsBar<T>[];
+    lines?: readonly BarsLine<T>[];
+    /** Default `'stacked'`. `'normalized'` stacks each x to its share of the total. */
+    layout?: 'stacked' | 'grouped' | 'normalized';
+    /** Per-bar opacity (a partial week, an estimate). Overrides the series' `fillOpacity`. */
+    barOpacity?: (d: T, key: string) => number;
+};
+export declare function Bars<T, X extends ChartX = ChartX>(props: BarsProps<T, X>): ReactElement;
+//# sourceMappingURL=Bars.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Bars.d.ts","sourceRoot":"","sources":["../../src/charts/Bars.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAIzC,OAAO,KAAK,EACV,mBAAmB,EAEnB,WAAW,EACX,MAAM,EAGP,MAAM,SAAS,CAAA;AAEhB,oDAAoD;AACpD,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,IAAI,CAC3B,WAAW,CAAC,CAAC,CAAC,EACd,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAChG,GAAG;IACF,oBAAoB;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,8DAA8D;AAC9D,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,IAAI,CAC5B,WAAW,CAAC,CAAC,CAAC,EACZ,KAAK,GACL,OAAO,GACP,OAAO,GACP,UAAU,GACV,aAAa,GACb,SAAS,GACT,QAAQ,GACR,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,aAAa,GACb,eAAe,CAClB,CAAA;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CACxD,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EACzB,OAAO,GAAG,QAAQ,CACnB,GAAG;IACF,IAAI,EAAE,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;IAC3B,KAAK,CAAC,EAAE,SAAS,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAA;IAC9B,mFAAmF;IACnF,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAA;IAC7C,0FAA0F;IAC1F,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;CAC3C,CAAA;AAoBD,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,YAAY,CA2DvF"}