@sqlrooms/mosaic 0.29.0-rc.2 → 0.29.0-rc.4

package/README.md

@@ -41,6 +41,36 @@ export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
 );
 ```
 
+Mosaic's pre-aggregation optimization creates `preagg_*` cache tables lazily
+when users interact with cross-filtered selections. By default Mosaic writes
+those tables to the persistent `mosaic` schema. If the DuckDB database is a user
+project file, point pre-aggregates at an attached cache database or disable them:
+
+```tsx
+const mosaicCacheDatabase = '__sqlrooms_mosaic_cache';
+
+const connector = createWebSocketDuckDbConnector({
+  initializationQuery: [
+    `ATTACH IF NOT EXISTS ':memory:' AS ${mosaicCacheDatabase}`,
+    `CREATE SCHEMA IF NOT EXISTS ${mosaicCacheDatabase}.mosaic`,
+  ].join('; '),
+});
+
+export const {roomStore, useRoomStore} = createRoomStore<RoomState>(
+  (set, get, store) => ({
+    // ... db slice using connector
+    ...createMosaicSlice({
+      preagg: {
+        schema: `${mosaicCacheDatabase}.mosaic`,
+      },
+    })(set, get, store),
+  }),
+);
+```
+
+Set `preagg.enabled` to `false` when you prefer to avoid pre-aggregate tables
+entirely.
+
 The Mosaic connection is automatically initialized when the DuckDB connector is ready. You can check the connection status:
 
 ```tsx
@@ -137,6 +167,185 @@ For the common case, prefer the compound `MosaicProfiler` API. `useMosaicProfile
 is still available when you need direct access to the profiler state for custom
 layout, sizing, or advanced composition.
 
+### Mosaic Dashboard Panels
+
+`MosaicDashboard` is a compound dashboard surface backed by generic dashboard
+panels instead of a chart-only list. Configure supported panel renderers and
+runtime add-panel actions when creating the dashboard slice.
+
+```tsx
+import {
+  createDefaultMosaicDashboardPanelRenderers,
+  createMosaicDashboardProfilerPanelConfig,
+  createMosaicDashboardChartPanelConfig,
+  createMosaicDashboardSlice,
+  MosaicDashboard,
+} from '@sqlrooms/mosaic';
+
+const dashboardSlice = createMosaicDashboardSlice({
+  panelRenderers: createDefaultMosaicDashboardPanelRenderers(),
+  // Optional: pass chartTypes/chartBuilders to customize Add Chart.
+  // Optional: pass addPanelActions to add app-specific menu entries.
+});
+
+function Dashboard() {
+  return <MosaicDashboard dashboardId="main" />;
+}
+
+function addProfiler(store: RoomStore) {
+  store.getState().mosaicDashboard.addPanel(
+    'main',
+    createMosaicDashboardProfilerPanelConfig({
+      source: {tableName: 'earthquakes'},
+    }),
+  );
+}
+
+function addBoxPlotChart(store: RoomStore) {
+  store.getState().mosaicDashboard.addPanel(
+    'main',
+    createMosaicDashboardChartPanelConfig('Magnitude by Region', {
+      chartType: 'box-plot',
+      settings: {
+        x: 'region',
+        y: 'magnitude',
+      },
+    }),
+  );
+}
+```
+
+Dashboards have a creation-time `layoutType` of either `dock` or `grid`.
+Existing persisted dashboards default to `dock`; pass `'grid'` to
+`createDashboard(title, 'grid')` or `ensureDashboard(id, title, 'grid')` when
+creating a dashboard that should use the scrollable grid renderer. Re-ensuring
+an existing dashboard does not convert between layout types.
+
+Dashboard panel sources may specify a `tableName` or trusted `sqlQuery`; when a
+panel omits a source it falls back to the dashboard selected table. Panel renderer
+definitions and chart builder definitions are runtime-only and intentionally
+live outside persisted dashboard config.
+
+### AI Chart Tools
+
+`createChartTools` generates assistant tools for the built-in chart types. The
+injected `ChartToolDeps.resolveResources(params, context)` callback receives the
+tool execution context as its second argument. Client apps should prefer
+execution-scoped context, such as a captured AI run context, over live UI state
+when resolving implicit dashboard targets. Explicit `params.artifactId` should
+still take precedence.
+
+```ts
+import {
+  createChartTools,
+  createDefaultChartTypes,
+  type ChartToolDeps,
+} from '@sqlrooms/mosaic';
+
+const deps: ChartToolDeps = {
+  resolveResources: (params, context) => {
+    const sessionId = context?.sessionId;
+    const runContext = context?.aiRunContext;
+    const contextArtifactId = getDashboardArtifactIdFromRunContext(
+      runContext,
+      sessionId,
+    );
+
+    // Prefer execution-scoped context over live UI state for implicit targets.
+    // Explicit tool input still wins over anything derived from context.
+    const artifactId =
+      params.artifactId ??
+      contextArtifactId ??
+      getCurrentDashboardArtifactId();
+    const tableName = params.tableName ?? getSelectedTableName(artifactId);
+
+    return {
+      artifactId,
+      tableName,
+      columns: getTableColumns(tableName),
+    };
+  },
+  createChart: ({artifactId, tableName, title, config}) =>
+    addChartPanel({artifactId, tableName, title, config}),
+};
+
+const chartTools = createChartTools(
+  createDefaultChartTypes({includeCustomSpec: false}),
+  deps,
+);
+```
+
+### Box Plot Chart Type
+
+The built-in Box Plot chart type (`'box-plot'`) is a specialized chart that uses
+a custom renderer instead of Vega-Lite. It calculates quartiles, whiskers, and
+outliers directly in DuckDB using SQL queries, then renders them with Observable
+Plot primitives. This approach provides better performance and more accurate
+statistical calculations than Observable Plot's built-in `boxY` mark.
+
+Box plots support:
+
+- Grouped box plots by categorical variable (x-axis)
+- Y-axis brushing for interactive filtering
+- Cross-filtering integration with other dashboard charts
+- Custom quartile calculation using DuckDB's `quantile_cont` function
+
+The renderer is modular and organized in the `chart-types/box-plot/renderer/`
+directory with separate concerns:
+
+- **BoxPlotPanelRenderer.tsx** - Main React component with drag interactions
+- **BoxPlotClient.ts** - Mosaic client for SQL-based data queries
+- **plot.ts** - Observable Plot rendering logic
+- **utils.ts** - Statistical calculations and coordinate transformations
+- **constants.ts** - Theme colors and layout constants
+
+### Chart Builder Compound Components
+
+The chart builder UI can be used as a compound component API for flexible composition:
+
+```tsx
+import {
+  ChartBuilderRoot,
+  ChartBuilderTrigger,
+  ChartBuilderDialogContent,
+  ChartBuilderContent,
+} from '@sqlrooms/mosaic';
+
+function MyDashboard() {
+  const columns = [...]; // Your table columns
+
+  return (
+    <ChartBuilderRoot
+      tableName="earthquakes"
+      columns={columns}
+      onCreateChart={(spec, title) => {
+        // Handle chart creation
+      }}
+      onCreateChartOutput={(output, title) => {
+        // Optional: handle non-spec outputs such as dashboard panel chart types.
+      }}
+    >
+      <ChartBuilderTrigger />
+      <ChartBuilderDialogContent>
+        <ChartBuilderContent />
+      </ChartBuilderDialogContent>
+    </ChartBuilderRoot>
+  );
+}
+```
+
+Available compound components:
+
+- `ChartBuilderRoot` - Context provider and dialog wrapper
+- `ChartBuilderTrigger` - Button to open the dialog
+- `ChartBuilderDialogContent` - Dialog content wrapper
+- `ChartBuilderContent` - Main chart builder UI (type grid + fields + actions)
+- `ChartBuilderTypeGrid` - Chart type selector grid
+- `ChartBuilderFields` - Field selector inputs
+- `ChartBuilderActions` - Back/Create buttons
+
+For simpler use cases, the legacy `ChartBuilderDialog` component is still available but deprecated.
+
 ### Working with Selections
 
 Selections enable cross-filtering between multiple visualizations. You can get or create a named selection from the store:

package/dist/MosaicChartBuilder.d.ts

@@ -1,32 +1,63 @@
+import type { ReactElement } from 'react';
+import { ChartBuilderActions } from './chart-builders/ChartBuilderActions';
+import { ChartBuilderContent } from './chart-builders/ChartBuilderContent';
+import { ChartBuilderDialog, ChartBuilderDialogContent, ChartBuilderTrigger } from './chart-builders/ChartBuilderDialog';
+import { ChartBuilderRoot, type ChartBuilderRootProps } from './chart-builders/ChartBuilderRoot';
+import { ChartBuilderFields } from './chart-builders/ChartBuilderFields';
+import { ChartBuilderTypeGrid } from './chart-builders/ChartBuilderTypeGrid';
+import { FieldSelectorInput } from './chart-builders/FieldSelectorInput';
 /**
  * Compound component for building Mosaic charts from templates.
  *
- * Use `MosaicChartBuilder.Content` for an inline builder, or
- * `MosaicChartBuilder.Dialog` for a dialog-wrapped version.
+ * Use `<MosaicChartBuilder>` as the root; it provides context and wraps a
+ * Radix Dialog.
  *
- * @example Inline usage
+ * @example Compound usage (recommended)
  * ```tsx
- * <MosaicChartBuilder.Content
+ * <MosaicChartBuilder
  *   tableName="my_table"
  *   columns={columns}
  *   onCreateChart={handleCreate}
- * />
+ * >
+ *   <MosaicChartBuilder.Trigger />
+ *   <MosaicChartBuilder.Dialog />
+ * </MosaicChartBuilder>
  * ```
  *
- * @example Dialog usage
+ * @example Custom trigger button
  * ```tsx
- * <MosaicChartBuilder.Dialog
- *   open={isOpen}
- *   onOpenChange={setOpen}
+ * <MosaicChartBuilder
+ *   tableName="my_table"
+ *   columns={columns}
+ *   onCreateChart={handleCreate}
+ * >
+ *   <MosaicChartBuilder.Trigger variant="ghost" size="icon">
+ *     <PlusIcon />
+ *   </MosaicChartBuilder.Trigger>
+ *   <MosaicChartBuilder.Dialog />
+ * </MosaicChartBuilder>
+ * ```
+ *
+ * @example Inline builder (no dialog)
+ * ```tsx
+ * <MosaicChartBuilder.Content
  *   tableName="my_table"
  *   columns={columns}
  *   onCreateChart={handleCreate}
  * />
  * ```
  */
-export declare const MosaicChartBuilder: {
-    readonly Content: import("react").FC<import(".").ChartBuilderContentProps>;
-    readonly Dialog: import("react").FC<import(".").ChartBuilderDialogProps>;
-    readonly FieldSelector: import("react").FC<import(".").FieldSelectorInputProps>;
+type MosaicChartBuilderCompoundComponent = ((props: ChartBuilderRootProps) => ReactElement) & {
+    Root: typeof ChartBuilderRoot;
+    Trigger: typeof ChartBuilderTrigger;
+    Dialog: typeof ChartBuilderDialogContent;
+    Content: typeof ChartBuilderContent;
+    TypeGrid: typeof ChartBuilderTypeGrid;
+    Fields: typeof ChartBuilderFields;
+    Actions: typeof ChartBuilderActions;
+    FieldSelector: typeof FieldSelectorInput;
+    LegacyDialog: typeof ChartBuilderDialog;
 };
+export declare const MosaicChartBuilder: MosaicChartBuilderCompoundComponent;
+export {};
 //# sourceMappingURL=MosaicChartBuilder.d.ts.map

package/dist/MosaicChartBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MosaicChartBuilder.d.ts","sourceRoot":"","sources":["../src/MosaicChartBuilder.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAC"}
+{"version":3,"file":"MosaicChartBuilder.d.ts","sourceRoot":"","sources":["../src/MosaicChartBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,OAAO,CAAC;AACxC,OAAO,EAAC,mBAAmB,EAAC,MAAM,sCAAsC,CAAC;AACzE,OAAO,EAAC,mBAAmB,EAAC,MAAM,sCAAsC,CAAC;AACzE,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACpB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAC,oBAAoB,EAAC,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,KAAK,mCAAmC,GAAG,CAAC,CAC1C,KAAK,EAAE,qBAAqB,KACzB,YAAY,CAAC,GAAG;IACnB,IAAI,EAAE,OAAO,gBAAgB,CAAC;IAC9B,OAAO,EAAE,OAAO,mBAAmB,CAAC;IACpC,MAAM,EAAE,OAAO,yBAAyB,CAAC;IACzC,OAAO,EAAE,OAAO,mBAAmB,CAAC;IACpC,QAAQ,EAAE,OAAO,oBAAoB,CAAC;IACtC,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,OAAO,EAAE,OAAO,mBAAmB,CAAC;IACpC,aAAa,EAAE,OAAO,kBAAkB,CAAC;IACzC,YAAY,EAAE,OAAO,kBAAkB,CAAC;CACzC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,mCAsB9B,CAAC"}

package/dist/MosaicChartBuilder.js

@@ -1,35 +1,27 @@
+import { ChartBuilderActions } from './chart-builders/ChartBuilderActions';
 import { ChartBuilderContent } from './chart-builders/ChartBuilderContent';
-import { ChartBuilderDialog } from './chart-builders/ChartBuilderDialog';
+import { ChartBuilderDialog, ChartBuilderDialogContent, ChartBuilderTrigger, } from './chart-builders/ChartBuilderDialog';
+import { ChartBuilderRoot, } from './chart-builders/ChartBuilderRoot';
+import { ChartBuilderFields } from './chart-builders/ChartBuilderFields';
+import { ChartBuilderTypeGrid } from './chart-builders/ChartBuilderTypeGrid';
 import { FieldSelectorInput } from './chart-builders/FieldSelectorInput';
-/**
- * Compound component for building Mosaic charts from templates.
- *
- * Use `MosaicChartBuilder.Content` for an inline builder, or
- * `MosaicChartBuilder.Dialog` for a dialog-wrapped version.
- *
- * @example Inline usage
- * ```tsx
- * <MosaicChartBuilder.Content
- *   tableName="my_table"
- *   columns={columns}
- *   onCreateChart={handleCreate}
- * />
- * ```
- *
- * @example Dialog usage
- * ```tsx
- * <MosaicChartBuilder.Dialog
- *   open={isOpen}
- *   onOpenChange={setOpen}
- *   tableName="my_table"
- *   columns={columns}
- *   onCreateChart={handleCreate}
- * />
- * ```
- */
-export const MosaicChartBuilder = {
+export const MosaicChartBuilder = Object.assign(ChartBuilderRoot, {
+    Root: ChartBuilderRoot,
+    /** Default trigger button; customize via ButtonProps or children. */
+    Trigger: ChartBuilderTrigger,
+    /** Dialog content pane with chart-builder steps. */
+    Dialog: ChartBuilderDialogContent,
+    /** Standalone builder UI (no dialog wrapper). */
     Content: ChartBuilderContent,
-    Dialog: ChartBuilderDialog,
+    /** Built-in chart-type picker grid. */
+    TypeGrid: ChartBuilderTypeGrid,
+    /** Field selectors for the currently selected chart type. */
+    Fields: ChartBuilderFields,
+    /** Back/Create actions for the current chart type selection. */
+    Actions: ChartBuilderActions,
+    /** Field selector primitive. */
     FieldSelector: FieldSelectorInput,
-};
+    /** Legacy one-shot dialog (backward-compatible). */
+    LegacyDialog: ChartBuilderDialog,
+});
 //# sourceMappingURL=MosaicChartBuilder.js.map

package/dist/MosaicChartBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"MosaicChartBuilder.js","sourceRoot":"","sources":["../src/MosaicChartBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,mBAAmB,EAAC,MAAM,sCAAsC,CAAC;AACzE,OAAO,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,OAAO,EAAE,mBAAmB;IAC5B,MAAM,EAAE,kBAAkB;IAC1B,aAAa,EAAE,kBAAkB;CACzB,CAAC","sourcesContent":["import {ChartBuilderContent} from './chart-builders/ChartBuilderContent';\nimport {ChartBuilderDialog} from './chart-builders/ChartBuilderDialog';\nimport {FieldSelectorInput} from './chart-builders/FieldSelectorInput';\n\n/**\n * Compound component for building Mosaic charts from templates.\n *\n * Use `MosaicChartBuilder.Content` for an inline builder, or\n * `MosaicChartBuilder.Dialog` for a dialog-wrapped version.\n *\n * @example Inline usage\n * ```tsx\n * <MosaicChartBuilder.Content\n *   tableName=\"my_table\"\n *   columns={columns}\n *   onCreateChart={handleCreate}\n * />\n * ```\n *\n * @example Dialog usage\n * ```tsx\n * <MosaicChartBuilder.Dialog\n *   open={isOpen}\n *   onOpenChange={setOpen}\n *   tableName=\"my_table\"\n *   columns={columns}\n *   onCreateChart={handleCreate}\n * />\n * ```\n */\nexport const MosaicChartBuilder = {\n  Content: ChartBuilderContent,\n  Dialog: ChartBuilderDialog,\n  FieldSelector: FieldSelectorInput,\n} as const;\n"]}
+{"version":3,"file":"MosaicChartBuilder.js","sourceRoot":"","sources":["../src/MosaicChartBuilder.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,mBAAmB,EAAC,MAAM,sCAAsC,CAAC;AACzE,OAAO,EAAC,mBAAmB,EAAC,MAAM,sCAAsC,CAAC;AACzE,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,gBAAgB,GAEjB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAC,oBAAoB,EAAC,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAC,kBAAkB,EAAC,MAAM,qCAAqC,CAAC;AA0DvE,MAAM,CAAC,MAAM,kBAAkB,GAC7B,MAAM,CAAC,MAAM,CACX,gBAAkE,EAClE;IACE,IAAI,EAAE,gBAAgB;IACtB,qEAAqE;IACrE,OAAO,EAAE,mBAAmB;IAC5B,oDAAoD;IACpD,MAAM,EAAE,yBAAyB;IACjC,iDAAiD;IACjD,OAAO,EAAE,mBAAmB;IAC5B,uCAAuC;IACvC,QAAQ,EAAE,oBAAoB;IAC9B,6DAA6D;IAC7D,MAAM,EAAE,kBAAkB;IAC1B,gEAAgE;IAChE,OAAO,EAAE,mBAAmB;IAC5B,gCAAgC;IAChC,aAAa,EAAE,kBAAkB;IACjC,oDAAoD;IACpD,YAAY,EAAE,kBAAkB;CACjC,CACF,CAAC","sourcesContent":["import type {ReactElement} from 'react';\nimport {ChartBuilderActions} from './chart-builders/ChartBuilderActions';\nimport {ChartBuilderContent} from './chart-builders/ChartBuilderContent';\nimport {\n  ChartBuilderDialog,\n  ChartBuilderDialogContent,\n  ChartBuilderTrigger,\n} from './chart-builders/ChartBuilderDialog';\nimport {\n  ChartBuilderRoot,\n  type ChartBuilderRootProps,\n} from './chart-builders/ChartBuilderRoot';\nimport {ChartBuilderFields} from './chart-builders/ChartBuilderFields';\nimport {ChartBuilderTypeGrid} from './chart-builders/ChartBuilderTypeGrid';\nimport {FieldSelectorInput} from './chart-builders/FieldSelectorInput';\n\n/**\n * Compound component for building Mosaic charts from templates.\n *\n * Use `<MosaicChartBuilder>` as the root; it provides context and wraps a\n * Radix Dialog.\n *\n * @example Compound usage (recommended)\n * ```tsx\n * <MosaicChartBuilder\n *   tableName=\"my_table\"\n *   columns={columns}\n *   onCreateChart={handleCreate}\n * >\n *   <MosaicChartBuilder.Trigger />\n *   <MosaicChartBuilder.Dialog />\n * </MosaicChartBuilder>\n * ```\n *\n * @example Custom trigger button\n * ```tsx\n * <MosaicChartBuilder\n *   tableName=\"my_table\"\n *   columns={columns}\n *   onCreateChart={handleCreate}\n * >\n *   <MosaicChartBuilder.Trigger variant=\"ghost\" size=\"icon\">\n *     <PlusIcon />\n *   </MosaicChartBuilder.Trigger>\n *   <MosaicChartBuilder.Dialog />\n * </MosaicChartBuilder>\n * ```\n *\n * @example Inline builder (no dialog)\n * ```tsx\n * <MosaicChartBuilder.Content\n *   tableName=\"my_table\"\n *   columns={columns}\n *   onCreateChart={handleCreate}\n * />\n * ```\n */\n\ntype MosaicChartBuilderCompoundComponent = ((\n  props: ChartBuilderRootProps,\n) => ReactElement) & {\n  Root: typeof ChartBuilderRoot;\n  Trigger: typeof ChartBuilderTrigger;\n  Dialog: typeof ChartBuilderDialogContent;\n  Content: typeof ChartBuilderContent;\n  TypeGrid: typeof ChartBuilderTypeGrid;\n  Fields: typeof ChartBuilderFields;\n  Actions: typeof ChartBuilderActions;\n  FieldSelector: typeof FieldSelectorInput;\n  LegacyDialog: typeof ChartBuilderDialog;\n};\n\nexport const MosaicChartBuilder: MosaicChartBuilderCompoundComponent =\n  Object.assign(\n    ChartBuilderRoot as (props: ChartBuilderRootProps) => ReactElement,\n    {\n      Root: ChartBuilderRoot,\n      /** Default trigger button; customize via ButtonProps or children. */\n      Trigger: ChartBuilderTrigger,\n      /** Dialog content pane with chart-builder steps. */\n      Dialog: ChartBuilderDialogContent,\n      /** Standalone builder UI (no dialog wrapper). */\n      Content: ChartBuilderContent,\n      /** Built-in chart-type picker grid. */\n      TypeGrid: ChartBuilderTypeGrid,\n      /** Field selectors for the currently selected chart type. */\n      Fields: ChartBuilderFields,\n      /** Back/Create actions for the current chart type selection. */\n      Actions: ChartBuilderActions,\n      /** Field selector primitive. */\n      FieldSelector: FieldSelectorInput,\n      /** Legacy one-shot dialog (backward-compatible). */\n      LegacyDialog: ChartBuilderDialog,\n    },\n  );\n"]}

package/dist/MosaicSlice.d.ts

@@ -6,6 +6,12 @@ import type { Table as ArrowTable } from 'apache-arrow';
 import { z } from 'zod';
 export declare const MosaicSliceConfig: z.ZodObject<{}, z.core.$strip>;
 export type MosaicSliceConfig = z.infer<typeof MosaicSliceConfig>;
+export type MosaicPreAggregateOptions = {
+    /** Database schema/namespace for Mosaic pre-aggregate tables. */
+    schema?: string;
+    /** Enable or disable Mosaic's pre-aggregation optimization. */
+    enabled?: boolean;
+};
 export type MosaicClientOptions = {
     /** Unique identifier for this client */
     id?: string;
@@ -17,6 +23,8 @@ export type MosaicClientOptions = {
     query: (filter: unknown) => ReturnType<typeof Query.from>;
     /** Callback when query results are received */
     queryResult?: (result: ArrowTable) => void;
+    /** Callback when query execution fails */
+    queryError?: (error: Error) => void;
 };
 export type TrackedClient = {
     id: string;
@@ -24,21 +32,29 @@ export type TrackedClient = {
     createdAt: number;
     isLoading: boolean;
     data: unknown | null;
+    error?: Error;
     selection?: Selection;
     queryResultCallback?: (result: ArrowTable) => void;
 };
+export type MosaicIdleConnection = {
+    status: 'idle';
+};
+export type MosaicLoadingConnection = {
+    status: 'loading';
+};
+export type MosaicReadyConnection = {
+    status: 'ready';
+    connector?: Connector;
+    coordinator: Coordinator;
+};
+export type MosaicErrorConnection = {
+    status: 'error';
+    error: unknown;
+};
+export type MosaicConnection = MosaicIdleConnection | MosaicLoadingConnection | MosaicReadyConnection | MosaicErrorConnection;
 export type MosaicSliceState = {
     mosaic: SliceFunctions & {
-        connection: {
-            status: 'idle' | 'loading';
-        } | {
-            status: 'ready';
-            connector?: Connector;
-            coordinator: Coordinator;
-        } | {
-            status: 'error';
-            error: unknown;
-        };
+        connection: MosaicConnection;
         config: MosaicSliceConfig;
         /** Record of registered clients by id */
         clients: Record<string, TrackedClient>;
@@ -53,6 +69,7 @@ export type MosaicSliceState = {
         ensureClient: (options: MosaicClientOptions & {
             id: string;
             onQueryResult?: (result: ArrowTable) => void;
+            onQueryError?: (error: Error) => void;
         }) => void;
         /** Disconnect and remove a client by id */
         destroyClient: (id: string) => void;
@@ -64,6 +81,7 @@ export declare function createDefaultMosaicConfig(props?: Partial<MosaicSliceCon
 export type CreateMosaicSliceProps = {
     config?: Partial<MosaicSliceConfig>;
     coordinator?: Coordinator;
+    preagg?: MosaicPreAggregateOptions;
 };
 export declare function createMosaicSlice(props?: CreateMosaicSliceProps): import("zustand").StateCreator<MosaicSliceState>;
 export type DuckDbSliceStateWithMosaic = DuckDbSliceState & MosaicSliceState;

package/dist/MosaicSlice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MosaicSlice.d.ts","sourceRoot":"","sources":["../src/MosaicSlice.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MosaicSlice.d.ts","sourceRoot":"","sources":["../src/MosaicSlice.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EACL,SAAS,EACT,WAAW,EAEX,UAAU,EACV,SAAS,EAEV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAC,KAAK,EAAC,MAAM,oBAAoB,CAAC;AACzC,OAAO,KAAK,EAAC,KAAK,IAAI,UAAU,EAAC,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB,eAAO,MAAM,iBAAiB,gCAAe,CAAC;AAC9C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,MAAM,MAAM,yBAAyB,GAAG;IACtC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAGF,MAAM,MAAM,mBAAmB,GAAG;IAChC,wCAAwC;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8DAA8D;IAC9D,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,UAAU,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1D,+CAA+C;IAC/C,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAC3C,0CAA0C;IAC1C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC,CAAC;AAGF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC;AACpD,MAAM,MAAM,uBAAuB,GAAG;IAAC,MAAM,EAAE,SAAS,CAAA;CAAC,CAAC;AAC1D,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,EAAE,WAAW,CAAC;CAC1B,CAAC;AACF,MAAM,MAAM,qBAAqB,GAAG;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAC,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,uBAAuB,GACvB,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,cAAc,GAAG;QACvB,UAAU,EAAE,gBAAgB,CAAC;QAC7B,MAAM,EAAE,iBAAiB,CAAC;QAC1B,yCAAyC;QACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;QACvC,oEAAoE;QACpE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACtC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,0DAA0D;QAC1D,YAAY,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,KACtC,SAAS,CAAC;QACf,6CAA6C;QAC7C,YAAY,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,MAAM,CAAC;QACvD,4FAA4F;QAC5F,YAAY,EAAE,CACZ,OAAO,EAAE,mBAAmB,GAAG;YAC7B,EAAE,EAAE,MAAM,CAAC;YACX,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;YAC7C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;SACvC,KACE,IAAI,CAAC;QACV,2CAA2C;QAC3C,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;QACpC,kDAAkD;QAClD,iBAAiB,EAAE,MAAM,IAAI,CAAC;KAC/B,CAAC;CACH,CAAC;AAEF,wBAAgB,yBAAyB,CACvC,KAAK,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACjC,iBAAiB,CAInB;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,CAAC,EAAE,yBAAyB,CAAC;CACpC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,KAAK,GAAE,sBAA2B,oDAuTnE;AAiBD,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE7E,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,CAAC,GACjD,CAAC,CAIH"}

package/dist/MosaicSlice.js

@@ -27,17 +27,22 @@ export function createMosaicSlice(props = {}) {
                 try {
                     if (props.coordinator) {
                         resolvedCoordinator = props.coordinator;
+                        applyMosaicPreAggregateOptions(resolvedCoordinator, props.preagg);
                     }
                     else {
                         const dbConnector = await get().db.getConnector();
                         resolvedCoordinator = coordinator();
                         mosaicConnector = isWasmDuckDbConnector(dbConnector)
                             ? await wasmConnector({
-                                // @ts-expect-error - We install a different version of duckdb-wasm
+                                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                                // @ts-ignore - We might be using a different version of duckdb-wasm than mosaic expects
                                 duckDb: dbConnector.getDb(),
+                                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                                // @ts-ignore - same version mismatch
                                 connection: dbConnector.getConnection(),
                             })
                             : createDuckDbMosaicConnector(dbConnector);
+                        applyMosaicPreAggregateOptions(resolvedCoordinator, props.preagg);
                         resolvedCoordinator.databaseConnector(mosaicConnector);
                     }
                 }
@@ -58,6 +63,11 @@ export function createMosaicSlice(props = {}) {
             async destroy() {
                 get().mosaic.destroyAllClients();
             },
+            setConfig(config) {
+                set((state) => produce(state, (draft) => {
+                    draft.mosaic.config = config;
+                }));
+            },
             getSelection(name, type = 'crossfilter') {
                 const existing = get().mosaic.selections[name];
                 if (existing)
@@ -90,16 +100,39 @@ export function createMosaicSlice(props = {}) {
                         if (tracked) {
                             tracked.data = data;
                             tracked.isLoading = false;
+                            tracked.error = undefined;
                         }
                     }));
                     // Call external callback if provided
                     options.queryResult?.(toArrowClientResult(data));
                 };
+                const wrappedQueryPending = () => {
+                    set((state) => produce(state, (draft) => {
+                        const tracked = draft.mosaic.clients[id];
+                        if (tracked) {
+                            tracked.isLoading = true;
+                            tracked.error = undefined;
+                        }
+                    }));
+                };
+                const wrappedQueryError = (error) => {
+                    set((state) => produce(state, (draft) => {
+                        const tracked = draft.mosaic.clients[id];
+                        if (tracked) {
+                            tracked.isLoading = false;
+                            tracked.error = error;
+                        }
+                    }));
+                    client.enabled = false;
+                    options.queryError?.(error);
+                };
                 const client = makeClient({
                     coordinator: connection.coordinator,
                     selection,
                     query: options.query,
                     queryResult: wrappedQueryResult,
+                    queryPending: wrappedQueryPending,
+                    queryError: wrappedQueryError,
                 });
                 set((state) => produce(state, (draft) => {
                     draft.mosaic.clients[id] = {
@@ -108,6 +141,7 @@ export function createMosaicSlice(props = {}) {
                         createdAt: Date.now(),
                         isLoading: true,
                         data: null,
+                        error: undefined,
                         selection,
                         queryResultCallback: options.queryResult
                             ? (result) => options.queryResult(toArrowClientResult(result))
@@ -145,6 +179,7 @@ export function createMosaicSlice(props = {}) {
                         if (tracked) {
                             tracked.data = data;
                             tracked.isLoading = false;
+                            tracked.error = undefined;
                         }
                     }));
                     const arrowData = toArrowClientResult(data);
@@ -153,11 +188,34 @@ export function createMosaicSlice(props = {}) {
                     // Also call original queryResult if provided
                     options.queryResult?.(arrowData);
                 };
+                const wrappedQueryPending = () => {
+                    set((state) => produce(state, (draft) => {
+                        const tracked = draft.mosaic.clients[options.id];
+                        if (tracked) {
+                            tracked.isLoading = true;
+                            tracked.error = undefined;
+                        }
+                    }));
+                };
+                const wrappedQueryError = (error) => {
+                    set((state) => produce(state, (draft) => {
+                        const tracked = draft.mosaic.clients[options.id];
+                        if (tracked) {
+                            tracked.isLoading = false;
+                            tracked.error = error;
+                        }
+                    }));
+                    client.enabled = false;
+                    options.onQueryError?.(error);
+                    options.queryError?.(error);
+                };
                 const client = makeClient({
                     coordinator: connection.coordinator,
                     selection,
                     query: options.query,
                     queryResult: wrappedQueryResult,
+                    queryPending: wrappedQueryPending,
+                    queryError: wrappedQueryError,
                 });
                 set((state) => produce(state, (draft) => {
                     draft.mosaic.clients[options.id] = {
@@ -166,6 +224,7 @@ export function createMosaicSlice(props = {}) {
                         createdAt: Date.now(),
                         isLoading: true,
                         data: null,
+                        error: undefined,
                         selection,
                         queryResultCallback: options.onQueryResult
                             ? (result) => options.onQueryResult(toArrowClientResult(result))
@@ -174,24 +233,20 @@ export function createMosaicSlice(props = {}) {
                 }));
             },
             destroyClient(id) {
-                const { connection, clients } = get().mosaic;
+                const { clients } = get().mosaic;
                 const tracked = clients[id];
                 if (!tracked)
                     return;
-                if (connection.status === 'ready') {
-                    connection.coordinator.disconnect(tracked.client);
-                }
+                tracked.client.destroy();
                 set((state) => produce(state, (draft) => {
                     delete draft.mosaic.clients[id];
                 }));
             },
             destroyAllClients() {
-                const { connection, clients } = get().mosaic;
-                if (connection.status === 'ready') {
-                    Object.values(clients).forEach((tracked) => {
-                        connection.coordinator.disconnect(tracked.client);
-                    });
-                }
+                const { clients } = get().mosaic;
+                Object.values(clients).forEach((tracked) => {
+                    tracked.client.destroy();
+                });
                 set((state) => produce(state, (draft) => {
                     draft.mosaic.clients = {};
                 }));
@@ -199,6 +254,17 @@ export function createMosaicSlice(props = {}) {
         },
     }));
 }
+function applyMosaicPreAggregateOptions(mosaicCoordinator, options) {
+    if (!options) {
+        return;
+    }
+    if (options.schema !== undefined) {
+        mosaicCoordinator.preaggregator.schema = options.schema;
+    }
+    if (options.enabled !== undefined) {
+        mosaicCoordinator.preaggregator.enabled = options.enabled;
+    }
+}
 export function useStoreWithMosaic(selector) {
     return useBaseRoomStore((state) => selector(state));
 }