@kanzo-tech/ui 0.0.1-alpha

package/dist/charts/chart-root.js

@@ -0,0 +1,162 @@
+"use client";
+import { jsx as v, jsxs as Q } from "react/jsx-runtime";
+import { useState as U, useRef as D, useEffect as X, useMemo as Z, useContext as K, createContext as tt } from "react";
+import { ark as ot } from "@ark-ui/react/factory";
+import { Selection as rt } from "@uwdata/mosaic-core";
+import * as C from "@uwdata/vgplot";
+import { cn as nt } from "../lib/cn.js";
+import { chartSeriesColor as et, isColorToken as st, colorTokenName as G, chartColorScale as at } from "./chart-config.js";
+import { compileChartSpec as ct, chartSpecSignature as lt, chartSpecWarnings as ut, buildChartSpec as it } from "./chart-spec.js";
+import { useMosaic as ft } from "./mosaic-provider.js";
+import { resolveTokenColor as I } from "../lib/token-color.js";
+import { TokenizedPlot as mt } from "./tokenized-plot.js";
+const a = C;
+function pt(t) {
+  var o, c;
+  switch (t.kind) {
+    case "mark": {
+      const l = a[t.mark];
+      if (!l) return null;
+      if (t.source === null) return l(t.options);
+      const e = t.source.kind === "values" ? [...t.source.values] : C.from(t.source.table, t.source.filterBy ? { filterBy: t.source.filterBy } : void 0);
+      return l(e, t.options);
+    }
+    case "interactor":
+      return ((o = a[t.interactor]) == null ? void 0 : o.call(a, t.options)) ?? null;
+    case "attribute":
+      return ((c = a[t.name]) == null ? void 0 : c.call(a, t.value)) ?? null;
+    case "raw":
+      return t.value;
+  }
+}
+const g = tt(null);
+function Rt() {
+  const t = K(g);
+  if (!t) throw new Error("useChartContext must be used within a <ChartRoot>.");
+  return t;
+}
+function Mt() {
+  return K(g);
+}
+const ht = {};
+function Tt(t) {
+  const {
+    table: o,
+    filterBy: c,
+    as: l,
+    config: e = ht,
+    height: y = 200,
+    margin: x,
+    aspectRatio: N,
+    facetMargin: S,
+    facetGrid: d,
+    facetLabel: w,
+    attributes: b,
+    locale: k,
+    numberFormat: B,
+    children: i,
+    className: V,
+    plotClassName: _,
+    ref: z,
+    slot: L,
+    ...W
+  } = t, { coordinator: O, crossfilter: E, selected: Y, registerSelection: R } = ft(), [f] = U(() => rt.union()), s = l ?? f, u = c === void 0 ? E : c, M = D(null);
+  X(
+    // Only the selection this root minted is relayed: a caller-supplied `as` was wired by the
+    // caller (`include`, or another root), and relaying it again would double every clause.
+    () => R(s, { relay: s === f }),
+    [R, s, f]
+  );
+  const $ = JSON.stringify(B ?? null), q = Z(
+    () => ({
+      coordinator: O,
+      config: e,
+      table: o,
+      filterBy: u,
+      as: s,
+      color: (r) => {
+        const n = et(e, r);
+        return n === void 0 || !st(n) || typeof document > "u" ? n : I(M.current ?? document.documentElement, G(n));
+      },
+      formatNumber: (r, n) => new Intl.NumberFormat(k, n ?? B).format(r)
+    }),
+    // `numberKey` stands in for the options object's identity; `numberFormat` itself is read fresh.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [O, e, o, u, s, k, $]
+  ), T = ct(i, {
+    table: o,
+    filterBy: u,
+    as: s,
+    config: e,
+    resolveColor: Ct
+  }), m = lt(T), A = JSON.stringify(at(e)), J = D(null);
+  if (process.env.NODE_ENV !== "production" && J.current !== m) {
+    J.current = m;
+    const r = { shared: [E, Y] };
+    for (const n of ut(T, r)) console.warn(`[ChartRoot] ${n}`);
+  }
+  return /* @__PURE__ */ v(g.Provider, { value: q, children: /* @__PURE__ */ Q(
+    ot.div,
+    {
+      className: nt("flex w-full flex-col gap-2", V),
+      ref: (r) => {
+        M.current = r, gt(z, r);
+      },
+      ...W,
+      "data-slot": L ?? "chart-root",
+      children: [
+        /* @__PURE__ */ v(
+          mt,
+          {
+            className: _,
+            deps: [
+              m,
+              A,
+              o,
+              u,
+              s,
+              y,
+              N,
+              JSON.stringify(x ?? null),
+              JSON.stringify(S ?? null),
+              d,
+              w,
+              b
+            ],
+            render: (r, n) => {
+              const F = /* @__PURE__ */ new Map(), H = it(
+                { children: i, width: r, height: y, margin: x, aspectRatio: N, facetMargin: S, facetGrid: d, facetLabel: w, attributes: b },
+                {
+                  table: o,
+                  filterBy: u,
+                  as: s,
+                  config: e,
+                  resolveColor: (p) => {
+                    const h = G(p), P = F.get(h);
+                    if (P !== void 0) return P;
+                    const j = I(n, h);
+                    return F.set(h, j), j;
+                  }
+                }
+              );
+              return C.plot(...H.map(pt).filter((p) => p !== null));
+            }
+          }
+        ),
+        i
+      ]
+    }
+  ) });
+}
+function Ct(t) {
+  return t;
+}
+function gt(t, o) {
+  typeof t == "function" ? t(o) : t && (t.current = o);
+}
+export {
+  Tt as ChartRoot,
+  Rt as useChartContext,
+  Mt as useChartContextOptional
+};
+//# sourceMappingURL=chart-root.js.map

package/dist/charts/chart-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-root.js","sources":["../../src/charts/chart-root.tsx"],"sourcesContent":["\"use client\";\n\nimport { createContext, useContext, useEffect, useMemo, useRef, useState, type ReactNode, type Ref } from \"react\";\nimport type React from \"react\";\nimport { ark } from \"@ark-ui/react/factory\";\nimport { Selection, type Coordinator } from \"@uwdata/mosaic-core\";\nimport * as vg from \"@uwdata/vgplot\";\nimport { cn } from \"../lib/cn.js\";\nimport { chartColorScale, chartSeriesColor, colorTokenName, isColorToken, type ChartConfig } from \"./chart-config.js\";\nimport {\n  buildChartSpec,\n  chartSpecSignature,\n  chartSpecWarnings,\n  compileChartSpec,\n  type ChartDirective,\n  type ChartFacetOptions,\n  type ChartMargin,\n  type ChartSpecContext,\n} from \"./chart-spec.js\";\nimport { useMosaic } from \"./mosaic-provider.js\";\nimport { resolveTokenColor } from \"../lib/token-color.js\";\nimport { TokenizedPlot } from \"./tokenized-plot.js\";\n\n/** vgplot ships `any` for every directive; this is the one place we pin a shape to it. */\ntype VgDirective = (plot: unknown) => void;\nconst directives = vg as unknown as Record<string, ((...args: unknown[]) => VgDirective) | undefined>;\n\nfunction toVgDirective(directive: ChartDirective): VgDirective | null {\n  switch (directive.kind) {\n    case \"mark\": {\n      const fn = directives[directive.mark];\n      if (!fn) return null;\n      // A decorator takes options only; everything else takes (data, options).\n      if (directive.source === null) return fn(directive.options);\n      const data =\n        directive.source.kind === \"values\"\n          ? [...directive.source.values]\n          : vg.from(directive.source.table, directive.source.filterBy ? { filterBy: directive.source.filterBy } : undefined);\n      return fn(data, directive.options);\n    }\n    case \"interactor\":\n      return directives[directive.interactor]?.(directive.options) ?? null;\n    case \"attribute\":\n      return directives[directive.name]?.(directive.value) ?? null;\n    case \"raw\":\n      return directive.value as VgDirective;\n  }\n}\n\nexport interface ChartContextValue {\n  /** The active Mosaic coordinator, for a consumer that queries alongside the plot. */\n  coordinator: Coordinator;\n  config: ChartConfig;\n  table?: string;\n  /** What the marks filter by; `null` = the full relation. */\n  filterBy: Selection | null;\n  /** Where the interactors publish. */\n  as: Selection;\n  /**\n   * The series colour, normalised to `rgb(...)` so it is safe for both CSS and Plot. `undefined`\n   * for a key the config does not name.\n   *\n   * Normalising is what makes it dual-purpose and is also what makes it a **snapshot**: the answer\n   * is read off the DOM when you call it, and nothing re-calls it when the theme or the scheme\n   * changes. `ChartLegend` deliberately does not use this — its only sink is a `style`, so it\n   * passes `var(--chart-N)` through and lets the browser follow the theme for free. Take the same\n   * route for anything that only ends up in CSS; pair this with `useThemeTick` when you need the\n   * literal, which is to say when you are handing it to Plot.\n   */\n  color: (key: string) => string | undefined;\n  /** The chart's locale number formatter — one vocabulary for axes, legend and tooltip. */\n  formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;\n}\n\nconst ChartContext = createContext<ChartContextValue | null>(null);\n\n/**\n * The chart context — config, selections, coordinator, and the `color` / `formatNumber` helpers\n * that keep a series' identity in one place. Throws outside a `<ChartRoot>`.\n *\n * Available to DOM parts (`ChartLegend`, a custom tooltip, a readout). **Not** to descriptors:\n * `ChartRoot` reads their props off the element before React renders them, so a mark cannot pull\n * anything out of context — pass the value down from the component that owns the `<ChartRoot>`.\n */\nexport function useChartContext(): ChartContextValue {\n  const ctx = useContext(ChartContext);\n  if (!ctx) throw new Error(\"useChartContext must be used within a <ChartRoot>.\");\n  return ctx;\n}\n\n/** The chart context, or `null` — for parts that also work standalone, like `ChartLegend`. */\nexport function useChartContextOptional(): ChartContextValue | null {\n  return useContext(ChartContext);\n}\n\nexport interface ChartRootProps\n  extends Omit<React.ComponentProps<typeof ark.div>, \"children\">,\n    ChartFacetOptions {\n  /** The relation registered in the coordinator. Omit it when every mark carries its own `data`. */\n  table?: string;\n  /** What the marks filter by. Defaults to the `<MosaicProvider>` crossfilter; `null` = unfiltered. */\n  filterBy?: Selection | null;\n  /**\n   * Where the child interactors publish, and what `ChartHighlight` reads back. Defaults to a\n   * selection this root owns, relayed into the provider — see the note on `ChartRoot`. Pass one and\n   * you own its wiring: nothing is relayed for you, though the provider's `reset()` still clears it.\n   */\n  as?: Selection;\n  /** Series key → `{ label, color, icon }`. A non-empty config pins the plot's colour scale. */\n  config?: ChartConfig;\n  /** Plot height in px; the width is measured from the container. Default 200. */\n  height?: number;\n  margin?: number | ChartMargin;\n  aspectRatio?: number;\n  /**\n   * Raw `vg.*` directives for anything the layer does not wrap. Applied last, so they win.\n   * Keep the array referentially stable — a new array rebuilds the plot.\n   */\n  attributes?: readonly unknown[];\n  /** BCP-47 tag for `formatNumber`. Defaults to the runtime locale. */\n  locale?: string;\n  /** Default options for `formatNumber` — the chart's number vocabulary in one place. */\n  numberFormat?: Intl.NumberFormatOptions;\n  /** Descriptors (marks, interactors, axes) plus real DOM parts such as `ChartLegend`. */\n  children?: ReactNode;\n  /** Class for the plot host itself, inside the root. */\n  plotClassName?: string;\n}\n\nconst EMPTY_CONFIG: ChartConfig = {};\n\n/**\n * Why every chart owns a selection instead of sharing the page's.\n *\n * `ChartHighlight` does not filter — it asks the mark's **own** query which rows are selected, by\n * appending the predicate as an extra output column: `q._groupby.length ? q.select({__: pred})`.\n * On an aggregating mark that query has a `GROUP BY`, so a predicate naming a column this plot does\n * not group by is `Binder Error: column \"provider\" must appear in the GROUP BY clause`. The query\n * dies, vgplot swallows it, and **the plot keeps its previous render** — no error, no empty state,\n * nothing but a console line. It costs hours to find, because the symptom looks like a broken\n * crossfilter three components away.\n *\n * A page-wide publish target guarantees that failure the moment a second chart filters by a second\n * column. So each root publishes into a union of its own: those clauses, by construction, name only\n * columns this plot's own interactors could produce — which are the columns its marks group by. The\n * clauses are relayed on into the provider (`selected` → `crossfilter`) with `source` and `clients`\n * intact, so every other chart filters exactly as before and this one still does not filter itself.\n */\nexport function ChartRoot(props: ChartRootProps) {\n  const {\n    table,\n    filterBy,\n    as,\n    config = EMPTY_CONFIG,\n    height = 200,\n    margin,\n    aspectRatio,\n    facetMargin,\n    facetGrid,\n    facetLabel,\n    attributes,\n    locale,\n    numberFormat,\n    children,\n    className,\n    plotClassName,\n    ref,\n    slot,\n    ...rest\n  } = props;\n  const { coordinator, crossfilter, selected, registerSelection } = useMosaic();\n  // A plain union, so it hides nothing from its own publisher — a crossfilter would, and\n  // `ChartHighlight` would read an empty predicate and dim nothing.\n  const [own] = useState(() => Selection.union());\n  const target = as ?? own;\n  const source = filterBy === undefined ? crossfilter : filterBy;\n  const host = useRef<HTMLDivElement | null>(null);\n\n  useEffect(\n    // Only the selection this root minted is relayed: a caller-supplied `as` was wired by the\n    // caller (`include`, or another root), and relaying it again would double every clause.\n    () => registerSelection(target, { relay: target === own }),\n    [registerSelection, target, own],\n  );\n\n  const numberKey = JSON.stringify(numberFormat ?? null);\n  const context = useMemo<ChartContextValue>(\n    () => ({\n      coordinator,\n      config,\n      table,\n      filterBy: source,\n      as: target,\n      color: (key) => {\n        const value = chartSeriesColor(config, key);\n        if (value === undefined || !isColorToken(value) || typeof document === \"undefined\") return value;\n        // Resolve against the element the chart lives in, so a scoped theme override wins.\n        return resolveTokenColor(host.current ?? document.documentElement, colorTokenName(value));\n      },\n      formatNumber: (value, options) =>\n        new Intl.NumberFormat(locale, options ?? numberFormat).format(value),\n    }),\n    // `numberKey` stands in for the options object's identity; `numberFormat` itself is read fresh.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [coordinator, config, table, source, target, locale, numberKey],\n  );\n\n  // Compiled twice on purpose: once here with an identity colour resolver, purely to fingerprint\n  // the grammar for `deps`, and once inside the render below against the live DOM. The pure pass\n  // is what keeps a re-render from re-running every query.\n  const pure = compileChartSpec(children, {\n    table, filterBy: source, as: target, config, resolveColor: identity,\n  });\n  const signature = chartSpecSignature(pure);\n  const colorKey = JSON.stringify(chartColorScale(config));\n\n  // Keyed by signature so an unchanged chart warns once, not on every render.\n  const warned = useRef<string | null>(null);\n  if (process.env.NODE_ENV !== \"production\" && warned.current !== signature) {\n    warned.current = signature;\n    const context = { shared: [crossfilter, selected] };\n    for (const warning of chartSpecWarnings(pure, context)) console.warn(`[ChartRoot] ${warning}`);\n  }\n\n  return (\n    <ChartContext.Provider value={context}>\n      <ark.div\n        className={cn(\"flex w-full flex-col gap-2\", className)}\n        ref={(node: HTMLDivElement | null) => {\n          host.current = node;\n          assignRef(ref, node);\n        }}\n        {...rest}\n        data-slot={slot ?? \"chart-root\"}\n      >\n        <TokenizedPlot\n          className={plotClassName}\n          deps={[\n            signature,\n            colorKey,\n            table,\n            source,\n            target,\n            height,\n            aspectRatio,\n            JSON.stringify(margin ?? null),\n            JSON.stringify(facetMargin ?? null),\n            facetGrid,\n            facetLabel,\n            attributes,\n          ]}\n          render={(width, plotHost) => {\n            const cache = new Map<string, string>();\n            const ctx: ChartSpecContext = {\n              table,\n              filterBy: source,\n              as: target,\n              config,\n              resolveColor: (token) => {\n                const name = colorTokenName(token);\n                const hit = cache.get(name);\n                if (hit !== undefined) return hit;\n                const resolved = resolveTokenColor(plotHost, name);\n                cache.set(name, resolved);\n                return resolved;\n              },\n            };\n            const spec = buildChartSpec(\n              { children, width, height, margin, aspectRatio, facetMargin, facetGrid, facetLabel, attributes },\n              ctx,\n            );\n            return vg.plot(...spec.map(toVgDirective).filter((d): d is VgDirective => d !== null));\n          }}\n        />\n        {children}\n      </ark.div>\n    </ChartContext.Provider>\n  );\n}\n\nfunction identity(token: string): string {\n  return token;\n}\n\n/** The root keeps its own handle on the host (for token resolution) without stealing the caller's. */\nfunction assignRef(ref: Ref<HTMLDivElement> | undefined, node: HTMLDivElement | null): void {\n  if (typeof ref === \"function\") ref(node);\n  else if (ref) ref.current = node;\n}\n"],"names":[],"mappings":";;;;;;;;;;;;AAyBA;AAEA;;AACE;AAAkB;AAEd;AACA;AAEA;AACA;AAIA;AAAiC;AACnC;AAEE;AAAgE;AAEhE;AAAwD;AAExD;AAAiB;AAEvB;AA2BA;AAUO;AACL;AACA;AACA;AACF;AAGO;AACL;AACF;AAoCA;AAmBO;AACL;AAAM;AACJ;AACA;AACA;AACS;AACA;AACT;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACG;AAUL;AAAA;AAAA;AAAA;AAG2D;AAC1B;AAGjC;AACgB;AACP;AACL;AACA;AACA;AACU;AACN;AAEF;AACA;AAEwF;AAC1F;AAEqE;AAAA;AAAA;AAAA;AAIT;AAMxB;AACtC;AAAiB;AAAY;AAAQ;AAAsB;AAO7D;AACE;AACA;AACA;AAA6F;AAG/F;AAEI;AAAK;AAAJ;AACsD;AAEnD;AACmB;AACrB;AACI;AACe;AAEnB;AAAA;AAAC;AAAA;AACY;AACL;AACJ;AACA;AACA;AACA;AACA;AACA;AACA;AAC6B;AACK;AAClC;AACA;AACA;AAAA;AAGA;AAea;AACyE;AAfxD;AAC5B;AACU;AACN;AACJ;AAEE;AAEA;AACA;AACA;AACO;AACT;AAAA;AAMF;AAAqF;AACvF;AAAA;AAAA;AAED;AAAA;AAAA;AAIT;AAEA;AACE;AACF;AAGA;AACE;AAEF;;;;;;"}

package/dist/charts/chart-spec.d.ts

@@ -0,0 +1,126 @@
+import { ReactNode } from 'react';
+import { Selection } from '@uwdata/mosaic-core';
+import { ChartConfig } from './chart-config.js';
+/**
+ * The plot spec as plain data.
+ *
+ * `ChartRoot` compiles its descriptor children to this list and only then maps it onto `vg.*`.
+ * The indirection is what makes the compiler pure: no coordinator, no DOM, no vgplot — so the
+ * grammar is unit-testable and the vgplot binding is a single switch. (`isAggregateExpression` is
+ * the one import, a pure AST predicate mosaic-sql exports for exactly this question.)
+ */
+export type ChartMarkSource = {
+    readonly kind: "table";
+    readonly table: string;
+    readonly filterBy: Selection | null;
+} | {
+    readonly kind: "values";
+    readonly values: readonly unknown[];
+}
+/** A decorator mark (`frame`, `gridX`, `gridY`) — takes options only, never data. */
+ | null;
+export interface ChartMarkDirective {
+    readonly kind: "mark";
+    readonly mark: string;
+    readonly source: ChartMarkSource;
+    readonly options: Readonly<Record<string, unknown>>;
+}
+export interface ChartInteractorDirective {
+    readonly kind: "interactor";
+    readonly interactor: string;
+    readonly options: Readonly<Record<string, unknown>>;
+}
+export interface ChartAttributeDirective {
+    readonly kind: "attribute";
+    readonly name: string;
+    readonly value: unknown;
+}
+/** The escape hatch: a `vg.*` directive the layer does not wrap, passed through untouched. */
+export interface ChartRawDirective {
+    readonly kind: "raw";
+    readonly value: unknown;
+}
+export type ChartDirective = ChartMarkDirective | ChartInteractorDirective | ChartAttributeDirective | ChartRawDirective;
+export interface ChartSpecContext {
+    /** The relation every table-backed mark reads from. */
+    readonly table?: string;
+    /** What marks filter by; `null` means "the full relation". */
+    readonly filterBy: Selection | null;
+    /** Where interactors publish. */
+    readonly as: Selection | null;
+    readonly config: ChartConfig;
+    /** Turns a `var(--token)` / `--token` reference into a Plot-safe colour. */
+    readonly resolveColor: (token: string) => string;
+}
+export type ChartCompile<P> = (props: P, ctx: ChartSpecContext) => ChartDirective | ChartDirective[];
+/** An inert child: renders nothing, carries its compilation on a static. */
+export interface ChartDescriptor<P> {
+    (props: P): null;
+    readonly displayName: string;
+    readonly __chart: ChartCompile<P>;
+}
+export declare function chartDescriptor<P>(displayName: string, compile: ChartCompile<P>): ChartDescriptor<P>;
+/** The descriptor children, in source order. Fragments and arrays flatten; `null`/`false` vanish. */
+export declare function compileChartSpec(children: ReactNode, ctx: ChartSpecContext): ChartDirective[];
+export interface ChartMargin {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/**
+ * The plot-wide half of faceting. The panels themselves come from a mark's `fx` / `fy` channels
+ * (`<ChartBarY fx="region" />`); per-scale options go on `ChartFacetX` / `ChartFacetY`.
+ */
+export interface ChartFacetOptions {
+    /**
+     * Space around each facet panel — the gutter *between* small multiples.
+     *
+     * Not where the panel titles go: those are drawn in the **plot's** top margin, so a `margin`
+     * with a small `top` renders them into nothing and the panels come out anonymous. Leave ~26px.
+     */
+    facetMargin?: number | ChartMargin;
+    /** Draw the grid across the facet panels. */
+    facetGrid?: boolean;
+    /** The shared label for the facet axes; `null` removes it. */
+    facetLabel?: string | null;
+}
+export interface ChartSpecOptions extends ChartFacetOptions {
+    children: ReactNode;
+    /** Measured from the container by `TokenizedPlot`; vgplot defaults to 640 without it. */
+    width: number;
+    height: number;
+    margin?: number | ChartMargin;
+    aspectRatio?: number;
+    attributes?: readonly unknown[];
+}
+/**
+ * The whole plot: frame attributes, the config's colour scale, the children, then the raw
+ * escape hatch last so a consumer directive can override anything the layer decided.
+ */
+export declare function buildChartSpec(options: ChartSpecOptions, ctx: ChartSpecContext): ChartDirective[];
+export interface ChartSpecWarningContext {
+    /**
+     * Selections shared by the whole `<MosaicProvider>` — anyone's clause can land in these, so they
+     * are never safe as a `ChartHighlight` target on an aggregating mark.
+     */
+    readonly shared?: readonly unknown[];
+}
+/**
+ * Combinations that fail at *runtime*, reported at build time.
+ *
+ * Both entries here are silent failures — the kind that costs an afternoon because nothing on
+ * screen says anything is wrong.
+ *
+ * 1. An interval brush over a band scale throws `Unrecognized scale type: band` from Mosaic's
+ *    pre-aggregator on pointer-enter — and because that pre-aggregator is coordinator-scoped, the
+ *    blast radius is every other chart on the page, which go blank with no error of their own.
+ * 2. A `ChartHighlight` pointed at a page-wide selection over an aggregating mark. The highlight
+ *    appends its predicate as an extra column on the mark's own `GROUP BY` query, so the first
+ *    clause naming a column this plot does not group by is a DuckDB binder error; the query dies
+ *    and the plot silently keeps its previous render. The default `by` is the root's own selection
+ *    and cannot hit this — only an explicit `by`/`as` naming a shared selection can.
+ */
+export declare function chartSpecWarnings(spec: ChartDirective[], context?: ChartSpecWarningContext): string[];
+export declare function chartSpecSignature(directives: readonly ChartDirective[]): string;
+//# sourceMappingURL=chart-spec.d.ts.map

package/dist/charts/chart-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-spec.d.ts","sourceRoot":"","sources":["../../src/charts/chart-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpF;;;;;;;GAOG;AAEH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE;AAClE,qFAAqF;GACnF,IAAI,CAAC;AAET,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,8FAA8F;AAC9F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,wBAAwB,GACxB,uBAAuB,GACvB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IACpC,iCAAiC;IACjC,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAClD;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,cAAc,GAAG,cAAc,EAAE,CAAC;AAErG,4EAA4E;AAC5E,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACjB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;CACnC;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAEpG;AA4BD,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAI7F;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACnC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,QAAQ,EAAE,SAAS,CAAC;IACpB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACjC;AAgBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,EAAE,gBAAgB,GAAG,cAAc,EAAE,CA4BjG;AA0BD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,MAAM,EAAE,CA8CrG;AAuCD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAEhF"}

package/dist/charts/chart-spec.js

@@ -0,0 +1,133 @@
+import { isValidElement as y, Fragment as k } from "react";
+import { isAggregateExpression as v } from "@uwdata/mosaic-sql";
+import { chartColorScale as w, isColorToken as $ } from "./chart-config.js";
+function B(t, e) {
+  return Object.assign(() => null, { displayName: t, __chart: e });
+}
+function C(t) {
+  return typeof t == "function" && typeof t.__chart == "function";
+}
+const m = 16;
+function f(t, e, r, i) {
+  if (t == null || typeof t == "boolean" || i > m) return;
+  if (Array.isArray(t)) {
+    for (const o of t) f(o, e, r, i + 1);
+    return;
+  }
+  if (!y(t)) return;
+  if (t.type === k) {
+    f(t.props.children, e, r, i + 1);
+    return;
+  }
+  if (!C(t.type)) return;
+  const n = t.type.__chart(t.props, e);
+  Array.isArray(n) ? r.push(...n) : r.push(n);
+}
+function A(t, e) {
+  const r = [];
+  return f(t, e, r, 0), r;
+}
+const d = { top: "Top", right: "Right", bottom: "Bottom", left: "Left" };
+function g(t, e) {
+  if (e === void 0) return [];
+  const r = typeof e == "number" ? { top: e, right: e, bottom: e, left: e } : e;
+  return Object.keys(d).filter((i) => r[i] !== void 0).map((i) => ({ kind: "attribute", name: `${t}${d[i]}`, value: r[i] }));
+}
+function G(t, e) {
+  const r = [
+    { kind: "attribute", name: "width", value: t.width },
+    { kind: "attribute", name: "height", value: t.height },
+    ...g("margin", t.margin),
+    ...g("facetMargin", t.facetMargin)
+  ];
+  t.aspectRatio !== void 0 && r.push({ kind: "attribute", name: "aspectRatio", value: t.aspectRatio }), t.facetGrid !== void 0 && r.push({ kind: "attribute", name: "facetGrid", value: t.facetGrid }), t.facetLabel !== void 0 && r.push({ kind: "attribute", name: "facetLabel", value: t.facetLabel });
+  const i = w(e.config);
+  i && (r.push({ kind: "attribute", name: "colorDomain", value: i.domain }), r.push({
+    kind: "attribute",
+    name: "colorRange",
+    value: i.range.map((n) => $(n) ? e.resolveColor(n) : n)
+  })), r.push(...A(t.children, e));
+  for (const n of t.attributes ?? []) r.push({ kind: "raw", value: n });
+  return r;
+}
+const O = {
+  barY: "x",
+  waffleY: "x",
+  cellX: "x",
+  barX: "y",
+  waffleX: "y",
+  cellY: "y"
+};
+function c(t) {
+  return `<Chart${t[0].toUpperCase()}${t.slice(1)}>`;
+}
+function S(t) {
+  return Object.values(t.options).some(
+    (e) => v(e) !== 0
+  );
+}
+function j(t) {
+  var e;
+  return !!((e = t.resolver) != null && e.cross);
+}
+function U(t, e) {
+  const r = [], i = t.filter((o) => o.kind === "mark"), n = (e == null ? void 0 : e.shared) ?? [];
+  for (const o of t) {
+    if (o.kind !== "interactor") continue;
+    if (o.interactor === "highlight") {
+      const s = o.options.by;
+      if (!s) continue;
+      if (j(s)) {
+        r.push(
+          "<ChartHighlight> reads a cross-filtered selection, which by definition hides a clause from the client that published it — so the predicate comes back empty and nothing is ever dimmed. Drop `by` to use the root's own selection, or point it at a plain union."
+        );
+        continue;
+      }
+      const p = i.find(S);
+      n.includes(s) && p && r.push(
+        `<ChartHighlight by={…}> targets a selection shared by the whole <MosaicProvider>, and ${c(p.mark)} aggregates. The highlight appends its predicate as a column on that GROUP BY query, so as soon as another chart publishes a clause over a column this plot does not group by, DuckDB answers "must appear in the GROUP BY clause", the query dies and this plot silently keeps its previous render. Drop \`by\` — the root's own selection only ever names columns this plot groups by.`
+      );
+      continue;
+    }
+    const a = o.interactor === "intervalX" ? "x" : o.interactor === "intervalY" ? "y" : null;
+    if (!a) continue;
+    const h = i.find((s) => O[s.mark] === a);
+    h && r.push(
+      `${c(o.interactor)} brushes a band scale (${c(h.mark)} makes ${a} categorical). Mosaic throws "Unrecognized scale type: band" on hover and blanks every other chart sharing the coordinator. Use <ChartToggle${a.toUpperCase()}> for categories, or bin ${a} first.`
+    );
+  }
+  return r;
+}
+const b = /* @__PURE__ */ new WeakMap();
+let D = 0;
+function u(t) {
+  let e = b.get(t);
+  return e === void 0 && (e = ++D, b.set(t, e)), e;
+}
+function l(t, e) {
+  if (typeof t == "function") return `fn#${u(t)}`;
+  if (typeof t == "symbol") return `sym#${String(t.description)}`;
+  if (t === null || typeof t != "object") return t;
+  if (e > m) return `deep#${u(t)}`;
+  if (Array.isArray(t)) return t.map((n) => l(n, e + 1));
+  const r = Object.getPrototypeOf(t);
+  if (r === Object.prototype || r === null)
+    return Object.fromEntries(Object.entries(t).map(([n, o]) => [n, l(o, e + 1)]));
+  let i = "[object]";
+  try {
+    i = String(t);
+  } catch {
+  }
+  return i.startsWith("[object") ? `obj#${u(t)}` : i;
+}
+function Y(t) {
+  return JSON.stringify(l(t, 0));
+}
+export {
+  G as buildChartSpec,
+  B as chartDescriptor,
+  Y as chartSpecSignature,
+  U as chartSpecWarnings,
+  A as compileChartSpec
+};
+//# sourceMappingURL=chart-spec.js.map

package/dist/charts/chart-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-spec.js","sources":["../../src/charts/chart-spec.ts"],"sourcesContent":["import { Fragment, isValidElement, type ReactNode } from \"react\";\nimport type { Selection } from \"@uwdata/mosaic-core\";\nimport { isAggregateExpression } from \"@uwdata/mosaic-sql\";\nimport { chartColorScale, isColorToken, type ChartConfig } from \"./chart-config.js\";\n\n/**\n * The plot spec as plain data.\n *\n * `ChartRoot` compiles its descriptor children to this list and only then maps it onto `vg.*`.\n * The indirection is what makes the compiler pure: no coordinator, no DOM, no vgplot — so the\n * grammar is unit-testable and the vgplot binding is a single switch. (`isAggregateExpression` is\n * the one import, a pure AST predicate mosaic-sql exports for exactly this question.)\n */\n\nexport type ChartMarkSource =\n  | { readonly kind: \"table\"; readonly table: string; readonly filterBy: Selection | null }\n  | { readonly kind: \"values\"; readonly values: readonly unknown[] }\n  /** A decorator mark (`frame`, `gridX`, `gridY`) — takes options only, never data. */\n  | null;\n\nexport interface ChartMarkDirective {\n  readonly kind: \"mark\";\n  readonly mark: string;\n  readonly source: ChartMarkSource;\n  readonly options: Readonly<Record<string, unknown>>;\n}\n\nexport interface ChartInteractorDirective {\n  readonly kind: \"interactor\";\n  readonly interactor: string;\n  readonly options: Readonly<Record<string, unknown>>;\n}\n\nexport interface ChartAttributeDirective {\n  readonly kind: \"attribute\";\n  readonly name: string;\n  readonly value: unknown;\n}\n\n/** The escape hatch: a `vg.*` directive the layer does not wrap, passed through untouched. */\nexport interface ChartRawDirective {\n  readonly kind: \"raw\";\n  readonly value: unknown;\n}\n\nexport type ChartDirective =\n  | ChartMarkDirective\n  | ChartInteractorDirective\n  | ChartAttributeDirective\n  | ChartRawDirective;\n\nexport interface ChartSpecContext {\n  /** The relation every table-backed mark reads from. */\n  readonly table?: string;\n  /** What marks filter by; `null` means \"the full relation\". */\n  readonly filterBy: Selection | null;\n  /** Where interactors publish. */\n  readonly as: Selection | null;\n  readonly config: ChartConfig;\n  /** Turns a `var(--token)` / `--token` reference into a Plot-safe colour. */\n  readonly resolveColor: (token: string) => string;\n}\n\nexport type ChartCompile<P> = (props: P, ctx: ChartSpecContext) => ChartDirective | ChartDirective[];\n\n/** An inert child: renders nothing, carries its compilation on a static. */\nexport interface ChartDescriptor<P> {\n  (props: P): null;\n  readonly displayName: string;\n  readonly __chart: ChartCompile<P>;\n}\n\nexport function chartDescriptor<P>(displayName: string, compile: ChartCompile<P>): ChartDescriptor<P> {\n  return Object.assign(() => null, { displayName, __chart: compile }) as ChartDescriptor<P>;\n}\n\nfunction isChartDescriptor(type: unknown): type is ChartDescriptor<unknown> {\n  return typeof type === \"function\" && typeof (type as { __chart?: unknown }).__chart === \"function\";\n}\n\n/** Guards against a pathological tree; nothing legitimate nests fragments this deep. */\nconst MAX_DEPTH = 16;\n\nfunction collect(node: ReactNode, ctx: ChartSpecContext, out: ChartDirective[], depth: number): void {\n  if (node == null || typeof node === \"boolean\" || depth > MAX_DEPTH) return;\n  if (Array.isArray(node)) {\n    for (const child of node) collect(child as ReactNode, ctx, out, depth + 1);\n    return;\n  }\n  if (!isValidElement(node)) return;\n  if (node.type === Fragment) {\n    collect((node.props as { children?: ReactNode }).children, ctx, out, depth + 1);\n    return;\n  }\n  // Anything else is a DOM child (ChartLegend, a caption…) — rendered, never compiled. A\n  // descriptor hidden inside a consumer's own component is invisible here, as in Recharts.\n  if (!isChartDescriptor(node.type)) return;\n  const produced = node.type.__chart(node.props, ctx);\n  if (Array.isArray(produced)) out.push(...produced);\n  else out.push(produced);\n}\n\n/** The descriptor children, in source order. Fragments and arrays flatten; `null`/`false` vanish. */\nexport function compileChartSpec(children: ReactNode, ctx: ChartSpecContext): ChartDirective[] {\n  const out: ChartDirective[] = [];\n  collect(children, ctx, out, 0);\n  return out;\n}\n\nexport interface ChartMargin {\n  top?: number;\n  right?: number;\n  bottom?: number;\n  left?: number;\n}\n\n/**\n * The plot-wide half of faceting. The panels themselves come from a mark's `fx` / `fy` channels\n * (`<ChartBarY fx=\"region\" />`); per-scale options go on `ChartFacetX` / `ChartFacetY`.\n */\nexport interface ChartFacetOptions {\n  /**\n   * Space around each facet panel — the gutter *between* small multiples.\n   *\n   * Not where the panel titles go: those are drawn in the **plot's** top margin, so a `margin`\n   * with a small `top` renders them into nothing and the panels come out anonymous. Leave ~26px.\n   */\n  facetMargin?: number | ChartMargin;\n  /** Draw the grid across the facet panels. */\n  facetGrid?: boolean;\n  /** The shared label for the facet axes; `null` removes it. */\n  facetLabel?: string | null;\n}\n\nexport interface ChartSpecOptions extends ChartFacetOptions {\n  children: ReactNode;\n  /** Measured from the container by `TokenizedPlot`; vgplot defaults to 640 without it. */\n  width: number;\n  height: number;\n  margin?: number | ChartMargin;\n  aspectRatio?: number;\n  attributes?: readonly unknown[];\n}\n\nconst MARGIN_SIDES = { top: \"Top\", right: \"Right\", bottom: \"Bottom\", left: \"Left\" } as const;\n\nfunction marginDirectives(\n  prefix: \"margin\" | \"facetMargin\",\n  margin: number | ChartMargin | undefined,\n): ChartAttributeDirective[] {\n  if (margin === undefined) return [];\n  const sides: ChartMargin =\n    typeof margin === \"number\" ? { top: margin, right: margin, bottom: margin, left: margin } : margin;\n  return (Object.keys(MARGIN_SIDES) as (keyof ChartMargin)[])\n    .filter((side) => sides[side] !== undefined)\n    .map((side) => ({ kind: \"attribute\", name: `${prefix}${MARGIN_SIDES[side]}`, value: sides[side] }));\n}\n\n/**\n * The whole plot: frame attributes, the config's colour scale, the children, then the raw\n * escape hatch last so a consumer directive can override anything the layer decided.\n */\nexport function buildChartSpec(options: ChartSpecOptions, ctx: ChartSpecContext): ChartDirective[] {\n  const directives: ChartDirective[] = [\n    { kind: \"attribute\", name: \"width\", value: options.width },\n    { kind: \"attribute\", name: \"height\", value: options.height },\n    ...marginDirectives(\"margin\", options.margin),\n    ...marginDirectives(\"facetMargin\", options.facetMargin),\n  ];\n  if (options.aspectRatio !== undefined) {\n    directives.push({ kind: \"attribute\", name: \"aspectRatio\", value: options.aspectRatio });\n  }\n  if (options.facetGrid !== undefined) {\n    directives.push({ kind: \"attribute\", name: \"facetGrid\", value: options.facetGrid });\n  }\n  if (options.facetLabel !== undefined) {\n    directives.push({ kind: \"attribute\", name: \"facetLabel\", value: options.facetLabel });\n  }\n  const scale = chartColorScale(ctx.config);\n  if (scale) {\n    directives.push({ kind: \"attribute\", name: \"colorDomain\", value: scale.domain });\n    directives.push({\n      kind: \"attribute\",\n      name: \"colorRange\",\n      value: scale.range.map((c) => (isColorToken(c) ? ctx.resolveColor(c) : c)),\n    });\n  }\n  directives.push(...compileChartSpec(options.children, ctx));\n  for (const raw of options.attributes ?? []) directives.push({ kind: \"raw\", value: raw });\n  return directives;\n}\n\n/** Marks whose primary channel is a band scale, which an interval brush cannot read. */\nconst BAND_MARKS: Record<string, \"x\" | \"y\"> = {\n  barY: \"x\", waffleY: \"x\", cellX: \"x\",\n  barX: \"y\", waffleX: \"y\", cellY: \"y\",\n};\n\nfunction component(name: string): string {\n  return `<Chart${name[0]!.toUpperCase()}${name.slice(1)}>`;\n}\n\n/** A mark whose query carries a `GROUP BY` — any channel holding an aggregate expression. */\nfunction isAggregating(mark: ChartMarkDirective): boolean {\n  // `isAggregateExpression` walks a SQL AST and answers 0 for anything that is not a node, so a\n  // plain `y=\"region\"` costs one type check rather than a guard here.\n  return Object.values(mark.options).some(\n    (value) => isAggregateExpression(value as Parameters<typeof isAggregateExpression>[0]) !== 0,\n  );\n}\n\n/** A cross-filtered selection never reports its own clause back to the client that published it. */\nfunction isCross(selection: Selection): boolean {\n  return Boolean(selection.resolver?.cross);\n}\n\nexport interface ChartSpecWarningContext {\n  /**\n   * Selections shared by the whole `<MosaicProvider>` — anyone's clause can land in these, so they\n   * are never safe as a `ChartHighlight` target on an aggregating mark.\n   */\n  readonly shared?: readonly unknown[];\n}\n\n/**\n * Combinations that fail at *runtime*, reported at build time.\n *\n * Both entries here are silent failures — the kind that costs an afternoon because nothing on\n * screen says anything is wrong.\n *\n * 1. An interval brush over a band scale throws `Unrecognized scale type: band` from Mosaic's\n *    pre-aggregator on pointer-enter — and because that pre-aggregator is coordinator-scoped, the\n *    blast radius is every other chart on the page, which go blank with no error of their own.\n * 2. A `ChartHighlight` pointed at a page-wide selection over an aggregating mark. The highlight\n *    appends its predicate as an extra column on the mark's own `GROUP BY` query, so the first\n *    clause naming a column this plot does not group by is a DuckDB binder error; the query dies\n *    and the plot silently keeps its previous render. The default `by` is the root's own selection\n *    and cannot hit this — only an explicit `by`/`as` naming a shared selection can.\n */\nexport function chartSpecWarnings(spec: ChartDirective[], context?: ChartSpecWarningContext): string[] {\n  const warnings: string[] = [];\n  const marks = spec.filter((d): d is ChartMarkDirective => d.kind === \"mark\");\n  const shared = context?.shared ?? [];\n\n  for (const d of spec) {\n    if (d.kind !== \"interactor\") continue;\n\n    if (d.interactor === \"highlight\") {\n      const by = d.options.by as Selection | null | undefined;\n      if (!by) continue;\n      if (isCross(by)) {\n        warnings.push(\n          \"<ChartHighlight> reads a cross-filtered selection, which by definition hides a clause \" +\n            \"from the client that published it — so the predicate comes back empty and nothing is \" +\n            \"ever dimmed. Drop `by` to use the root's own selection, or point it at a plain union.\",\n        );\n        continue;\n      }\n      const aggregating = marks.find(isAggregating);\n      if (shared.includes(by) && aggregating) {\n        warnings.push(\n          `<ChartHighlight by={…}> targets a selection shared by the whole <MosaicProvider>, and ` +\n            `${component(aggregating.mark)} aggregates. The highlight appends its predicate as a ` +\n            \"column on that GROUP BY query, so as soon as another chart publishes a clause over a \" +\n            \"column this plot does not group by, DuckDB answers \\\"must appear in the GROUP BY \" +\n            \"clause\\\", the query dies and this plot silently keeps its previous render. Drop `by` \" +\n            \"— the root's own selection only ever names columns this plot groups by.\",\n        );\n      }\n      continue;\n    }\n\n    const axis = d.interactor === \"intervalX\" ? \"x\" : d.interactor === \"intervalY\" ? \"y\" : null;\n    if (!axis) continue;\n    const clash = marks.find((m) => BAND_MARKS[m.mark] === axis);\n    if (clash) {\n      warnings.push(\n        `${component(d.interactor)} brushes a band scale ` +\n          `(${component(clash.mark)} makes ${axis} categorical). ` +\n          \"Mosaic throws \\\"Unrecognized scale type: band\\\" on hover and blanks every other chart \" +\n          `sharing the coordinator. Use <ChartToggle${axis.toUpperCase()}> for categories, or bin ${axis} first.`,\n      );\n    }\n  }\n  return warnings;\n}\n\n/**\n * A stable fingerprint of a compiled spec, for `TokenizedPlot`'s dependency list — the plot is\n * rebuilt (and its queries re-run) only when the grammar actually changed, not on every render.\n * SQL expression nodes (`count()`, `bin(x)`) stringify to their SQL; selections, params and\n * functions fall back to identity, which is stable as long as the caller does not rebuild them.\n */\nconst identities = new WeakMap<object, number>();\nlet nextIdentity = 0;\n\nfunction identityOf(value: object): number {\n  let id = identities.get(value);\n  if (id === undefined) {\n    id = ++nextIdentity;\n    identities.set(value, id);\n  }\n  return id;\n}\n\nfunction tag(value: unknown, depth: number): unknown {\n  if (typeof value === \"function\") return `fn#${identityOf(value)}`;\n  if (typeof value === \"symbol\") return `sym#${String(value.description)}`;\n  if (value === null || typeof value !== \"object\") return value;\n  if (depth > MAX_DEPTH) return `deep#${identityOf(value)}`;\n  if (Array.isArray(value)) return value.map((v) => tag(v, depth + 1));\n  const proto: unknown = Object.getPrototypeOf(value);\n  if (proto === Object.prototype || proto === null) {\n    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, tag(v, depth + 1)]));\n  }\n  let text = \"[object]\";\n  try {\n    text = String(value);\n  } catch {\n    /* a toString that throws is no worse than no toString */\n  }\n  return text.startsWith(\"[object\") ? `obj#${identityOf(value)}` : text;\n}\n\nexport function chartSpecSignature(directives: readonly ChartDirective[]): string {\n  return JSON.stringify(tag(directives, 0));\n}\n"],"names":["chartDescriptor","displayName","compile","isChartDescriptor","type","MAX_DEPTH","collect","node","ctx","out","depth","child","isValidElement","Fragment","produced","compileChartSpec","children","MARGIN_SIDES","marginDirectives","prefix","margin","sides","side","buildChartSpec","options","directives","scale","chartColorScale","c","isColorToken","raw","BAND_MARKS","component","name","isAggregating","mark","value","isAggregateExpression","isCross","selection","_a","chartSpecWarnings","spec","context","warnings","marks","d","shared","by","aggregating","axis","clash","m","identities","nextIdentity","identityOf","id","tag","v","proto","k","text","chartSpecSignature"],"mappings":"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"}

package/dist/charts/chart-stat.d.ts

@@ -0,0 +1,23 @@
+import { ExprValue } from '@uwdata/mosaic-sql';
+import { ReactNode } from 'react';
+import { StatTileProps } from '../simples/stat-tile.js';
+/**
+ * `StatTile` with the figure it shows read from the relation, under the same crossfilter as the
+ * plots. The connected half of the pair, which is the engine rule: `StatTile` takes a number and
+ * lives in the root barrel, this one queries for it and lives here.
+ */
+export interface ChartStatProps extends Omit<StatTileProps, "value" | "trend"> {
+    /** The relation. Defaults to the enclosing `ChartRoot`'s table. */
+    table?: string;
+    /** The aggregate to show — `count()`, `avg("latency")`, any `mosaic-sql` expression. */
+    value: ExprValue;
+    /** Formats the number for display. Defaults to the chart's `formatNumber`. */
+    format?: (value: number) => string;
+    /** Shown while the first query is in flight. */
+    fallback?: ReactNode;
+}
+export declare function ChartStat(props: ChartStatProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element;
+export declare namespace ChartStat {
+    var displayName: string;
+}
+//# sourceMappingURL=chart-stat.d.ts.map

package/dist/charts/chart-stat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-stat.d.ts","sourceRoot":"","sources":["../../src/charts/chart-stat.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAIvE;;;;GAIG;AAEH,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5E,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,KAAK,EAAE,SAAS,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,4SAoB9C;yBApBe,SAAS"}

package/dist/charts/chart-stat.js

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as m } from "react/jsx-runtime";
+import { Query as p } from "@uwdata/mosaic-sql";
+import { Skeleton as c } from "../simples/skeleton.js";
+import { StatTile as h } from "../simples/stat-tile.js";
+import { useChartContextOptional as C } from "./chart-root.js";
+import { useChartQuery as b } from "./use-chart-query.js";
+function w(n) {
+  const { table: i, value: o, format: e, fallback: u, ...s } = n, r = C(), t = i ?? (r == null ? void 0 : r.table), { row: a } = b({
+    query: (f) => t ? p.from(t).select({ value: o }).where(f) : null,
+    deps: [t, o]
+  });
+  if (!t)
+    throw new Error("ChartStat needs a `table`, or a <ChartRoot table> around it.");
+  if (a === void 0)
+    return u ?? /* @__PURE__ */ m(c, { className: "h-24 w-full" });
+  const l = Number(a.value ?? 0);
+  return /* @__PURE__ */ m(h, { ...s, value: e ? e(l) : l });
+}
+w.displayName = "ChartStat";
+export {
+  w as ChartStat
+};
+//# sourceMappingURL=chart-stat.js.map

package/dist/charts/chart-stat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-stat.js","sources":["../../src/charts/chart-stat.tsx"],"sourcesContent":["\"use client\";\n\nimport type { ExprValue } from \"@uwdata/mosaic-sql\";\nimport { Query } from \"@uwdata/mosaic-sql\";\nimport type { ReactNode } from \"react\";\nimport { Skeleton } from \"../simples/skeleton.js\";\nimport { StatTile, type StatTileProps } from \"../simples/stat-tile.js\";\nimport { useChartContextOptional } from \"./chart-root.js\";\nimport { useChartQuery } from \"./use-chart-query.js\";\n\n/**\n * `StatTile` with the figure it shows read from the relation, under the same crossfilter as the\n * plots. The connected half of the pair, which is the engine rule: `StatTile` takes a number and\n * lives in the root barrel, this one queries for it and lives here.\n */\n\nexport interface ChartStatProps extends Omit<StatTileProps, \"value\" | \"trend\"> {\n  /** The relation. Defaults to the enclosing `ChartRoot`'s table. */\n  table?: string;\n  /** The aggregate to show — `count()`, `avg(\"latency\")`, any `mosaic-sql` expression. */\n  value: ExprValue;\n  /** Formats the number for display. Defaults to the chart's `formatNumber`. */\n  format?: (value: number) => string;\n  /** Shown while the first query is in flight. */\n  fallback?: ReactNode;\n}\n\nexport function ChartStat(props: ChartStatProps) {\n  const { table, value, format, fallback, ...tile } = props;\n  const chart = useChartContextOptional();\n  const relation = table ?? chart?.table;\n\n  const { row } = useChartQuery({\n    query: (filter) =>\n      relation ? Query.from(relation).select({ value }).where(filter) : null,\n    deps: [relation, value],\n  });\n\n  if (!relation) {\n    throw new Error(\"ChartStat needs a `table`, or a <ChartRoot table> around it.\");\n  }\n  if (row === undefined) {\n    return fallback ?? <Skeleton className=\"h-24 w-full\" />;\n  }\n\n  const raw = Number(row.value ?? 0);\n  return <StatTile {...tile} value={format ? format(raw) : raw} />;\n}\n\n// The chart context is optional: a tile sits in a dashboard grid, outside any plot.\nChartStat.displayName = \"ChartStat\";\n"],"names":["ChartStat"],"mappings":";;;;;;;AA2BO;AACL;AAI8B;AAEwC;AAC9C;AAGxB;AACE;AAEF;AACE;AAGF;AACA;AACF;AAGAA;;;;"}

package/dist/charts/id-set-client.d.ts

@@ -0,0 +1,42 @@
+import { MosaicClient, Selection } from '@uwdata/mosaic-core';
+import { FilterExpr } from '@uwdata/mosaic-sql';
+/**
+ * The crossfilter adapter for a view whose positions are not in the database.
+ *
+ * A `MosaicClient` asks for two things, and this is both:
+ *
+ *   `query(filter)` — which rows survive the page's filters? The coordinator answers with a column
+ *     of ids, and the view fades everything else. The **observable** half.
+ *   `publish(ids)` — the user selected these. A points clause, `id IN (…)`, which every other chart
+ *     on the page filters by. The **controllable** half.
+ *
+ * The id list is not a shortcut, it is the only thing such a view can say. A Plot brush publishes
+ * `weight BETWEEN …`, an interval in data space, because Plot's `x` IS a column. A GPU simulation's
+ * `x` exists nowhere in the database, so no predicate over columns can describe the loop the user
+ * drew. Enumerating what was hit is the honest translation — and its cost is the length of the `IN`
+ * list, which is the real ceiling on the whole approach.
+ *
+ * Nothing here knows what draws. It is named for what it exchanges rather than for the renderer it
+ * was first written against, because a canvas, a map and an imperative widget all reach the
+ * crossfilter through exactly this shape.
+ */
+export interface IdSetClientOptions {
+    /** The relation. Its `idField` column is what gets published and matched. */
+    table: string;
+    idField: string;
+    /** What the view fades by. */
+    filterBy: Selection;
+    /** Where the selection publishes. */
+    as: Selection;
+    /** The surviving ids, in relation order, on every filter change. */
+    onSurvivors: (ids: readonly unknown[]) => void;
+}
+export declare class IdSetClient extends MosaicClient {
+    #private;
+    constructor(options: IdSetClientOptions);
+    query(filter?: FilterExpr): import('@uwdata/mosaic-sql').SelectQuery;
+    queryResult(data: unknown): this;
+    /** `null` retracts the selection: an empty clause has a null predicate, which the resolver drops. */
+    publish(ids: readonly unknown[] | null): void;
+}
+//# sourceMappingURL=id-set-client.d.ts.map

package/dist/charts/id-set-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-set-client.d.ts","sourceRoot":"","sources":["../../src/charts/id-set-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAgB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,qCAAqC;IACrC,EAAE,EAAE,SAAS,CAAC;IACd,oEAAoE;IACpE,WAAW,EAAE,CAAC,GAAG,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,CAAC;CAChD;AAED,qBAAa,WAAY,SAAQ,YAAY;;gBAM/B,OAAO,EAAE,kBAAkB;IAQ9B,KAAK,CAAC,MAAM,GAAE,UAAe;IAI7B,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAKzC,qGAAqG;IACrG,OAAO,CAAC,GAAG,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,GAAG,IAAI;CAY9C"}