useMosaic

The Mosaic context in one call — the engine, the page's one selection and the joins its relations are read over.

Brush the histogram, click a region, and the count in the group above moves with them. The button calls selection.reset(): every clause goes, and every chart that published one clears with it.

Usage

useMosaic lives on the @kanzo-tech/ui/analytics subpath, never the root barrel: the Mosaic/DuckDB stack is heavy and its peers are optional, so import { Button } from "@kanzo-tech/ui" never pulls it in.

import { useMosaic } from "@kanzo-tech/ui/analytics";

const { engine, selection, joins } = useMosaic();

It reads the context MosaicProvider publishes, and throws outside one. It is the one hook: a page has one selection, and nothing else to choose between.

selection

The page's one selection, owned by the provider — nobody passes one. Every chart, control and stat on the page filters by it and publishes into it, and a part of your own that should follow the brush does the same: a MosaicClient with filterBy: selection, or useChartQuery.

It is Mosaic's crossfilter — a chart is exempt from its own clause, so the bars under a brush do not vanish — with one addition, made through Mosaic's own extension point, its resolver: a clause published on one relation reaches a part reading another, crossed by key over the provider's joins, or keeping none of it where there is no way across (why).

Retracting is Mosaic's own. selection.reset([clause]) takes a clause out and calls its source back, which is how a chip's × clears the brush that published it; selection.reset() is Clear filters. There is no second selection upstream for a reset to miss.

joins

The join graph the provider was handed — readJoinGraph for an attached GraphAr graph — or null. A part's relation names a type or a path over it.

engine

The engine you handed MosaicProvider — engine.query(sql, { signal }) — for the work the client protocol does not cover — a fixed topology to draw, a schema, a one-off read that no brush should change. It is deliberately outside the crossfilter. A statement read once and drawn — a schema, a catalog — is useQueryRows, which suspends on it rather than wiring an effect.

A number that should follow the brush does not belong here. A widget that runs engine.query() in an effect looks correct on its first paint and then reports unfiltered totals beside filtered charts — which nobody reads as a stale widget, they read it as a broken crossfilter. Use useChartQuery, or ChartStat for the tile case.

API Reference

useMosaic(): MosaicContextValue

Field	Type	What it is
`engine`	`Engine`	the caller's engine; its coordinator is registered as vgplot's active one
`selection`	`Selection`	the page's one selection: what every part filters by and publishes into
`joins`	`JoinGraph \| null`	the graph the page's relations are read over
`onFailure`	`(error: unknown) => void`	hands a failed read to the provider's `onFailure`

Throws useMosaic must be used within a <MosaicProvider>. when there is no provider above it.