Add Chart Builder: no-JSON Vega-Lite composer from a dataset (M4)

src/app/stores/ChartBuilderStore.ts

@@ -0,0 +1,180 @@
+/**
+ * Chart Builder state (spec §06).
+ *
+ * Backs the Chart Builder modal: a no-JSON composer that turns a dataset + a mark
+ * + four channel mappings into a Vega-Lite spec saved as a new snippet. All the
+ * spec grammar and the Tier-B defaults/guards live in the portable core
+ * (`@core/chart-builder`); this store is the thin app-layer state + actions over
+ * that, plus the create-flow side effects (new snippet, toast, activate, close).
+ *
+ * `init(datasetId)` loads the dataset's columns and pre-populates a smart default
+ * config; with no dataset it lands empty so the modal can show "No dataset loaded".
+ * The mark is sticky after open (changing a column does not re-derive it) so the
+ * user's choice is never overridden mid-edit.
+ */
+
+import { create } from 'zustand';
+import {
+  buildSnippetSpecText,
+  defaultBuilderConfig,
+  defaultFieldType,
+  generateChartName,
+  isBuilderConfigValid,
+  isChannelTypeAllowed,
+  validFieldTypes,
+  type BuilderColumns,
+  type BuilderConfig,
+  type ChannelName,
+  type FieldType,
+  type MarkType,
+} from '@core/chart-builder';
+import type { ColumnType } from '@core/type-inference';
+import { closeModal } from '../modals/ModalCoordinator';
+import { useDatasetStore } from './DatasetStore';
+import { notify } from './NotificationStore';
+import { useSnippetStore } from './SnippetStore';
+
+/** An empty config — no dataset, nothing mapped (the "No dataset loaded" state). */
+const EMPTY_CONFIG: BuilderConfig = { datasetName: '', mark: 'bar', encodings: {} };
+const EMPTY_COLUMNS: BuilderColumns = { columns: [], columnTypes: [] };
+
+export interface ChartBuilderState {
+  /** The dataset being built from, or null when none is loaded. */
+  datasetId: number | null;
+  /** The dataset's columns + inferred types (drives the dropdowns and defaults). */
+  columns: BuilderColumns;
+  /** The working configuration the preview and the produced spec read from. */
+  config: BuilderConfig;
+
+  /** Load a dataset and pre-populate a smart default config (spec §06 → Opening). */
+  init: (datasetId: number | null) => void;
+  setMark: (mark: MarkType) => void;
+  /** Map a column to a channel (null = "None"); seeds the channel's default type. */
+  setChannelColumn: (channel: ChannelName, columnName: string | null) => void;
+  setChannelType: (channel: ChannelName, type: FieldType) => void;
+  /** Swap the X and Y mappings (a one-click axis flip). */
+  swapXY: () => void;
+  setWidth: (width: number | undefined) => void;
+  setHeight: (height: number | undefined) => void;
+  /** Build the spec, create + activate a linked snippet, toast, and close. */
+  createSnippet: (now?: Date) => boolean;
+  reset: () => void;
+}
+
+/** The inferred type of a named column, defaulting to `string` if unknown. */
+function columnType(columns: BuilderColumns, name: string): ColumnType {
+  return columns.columnTypes.find((c) => c.name === name)?.type ?? 'string';
+}
+
+export const useChartBuilderStore = create<ChartBuilderState>((set, get) => ({
+  datasetId: null,
+  columns: EMPTY_COLUMNS,
+  config: EMPTY_CONFIG,
+
+  init: (datasetId) => {
+    const dataset =
+      datasetId === null
+        ? undefined
+        : useDatasetStore.getState().datasets.find((d) => d.id === datasetId);
+    if (!dataset) {
+      set({ datasetId: null, columns: EMPTY_COLUMNS, config: EMPTY_CONFIG });
+      return;
+    }
+    const columns: BuilderColumns = {
+      columns: dataset.columns,
+      columnTypes: dataset.columnTypes,
+    };
+    set({
+      datasetId: dataset.id,
+      columns,
+      config: defaultBuilderConfig(dataset.name, columns),
+    });
+  },
+
+  setMark: (mark) => set((s) => ({ config: { ...s.config, mark } })),
+
+  setChannelColumn: (channel, columnName) =>
+    set((s) => {
+      const encodings = { ...s.config.encodings };
+      if (columnName === null) {
+        encodings[channel] = null;
+      } else {
+        // Default to the column's natural type, but if that type isn't allowed on
+        // this channel (e.g. a category on Size), fall back to the first valid type
+        // that is — the UI also disables unsuitable columns, this is the guard.
+        const valid = validFieldTypes(columnType(s.columns, columnName));
+        const type =
+          valid.find((t) => isChannelTypeAllowed(channel, t)) ??
+          defaultFieldType(columnType(s.columns, columnName));
+        encodings[channel] = { field: columnName, type };
+      }
+      return { config: { ...s.config, encodings } };
+    }),
+
+  setChannelType: (channel, type) =>
+    set((s) => {
+      const current = s.config.encodings[channel];
+      if (!current) return s; // no field on this channel → nothing to retype
+      return {
+        config: {
+          ...s.config,
+          encodings: { ...s.config.encodings, [channel]: { ...current, type } },
+        },
+      };
+    }),
+
+  swapXY: () =>
+    set((s) => ({
+      config: {
+        ...s.config,
+        encodings: {
+          ...s.config.encodings,
+          x: s.config.encodings.y ?? null,
+          y: s.config.encodings.x ?? null,
+        },
+      },
+    })),
+
+  setWidth: (width) => set((s) => ({ config: { ...s.config, width } })),
+  setHeight: (height) => set((s) => ({ config: { ...s.config, height } })),
+
+  createSnippet: (now) => {
+    const { config } = get();
+    if (!isBuilderConfigValid(config)) return false; // guarded by a disabled action too
+
+    const name = generateChartName(config);
+    const specText = buildSnippetSpecText(config);
+    // createSnippet mirrors datasetRefs from the spec, so the new snippet is linked
+    // to its dataset (§09F) without extra wiring. Provenance kept in meta (§06).
+    useSnippetStore.getState().createSnippet({
+      name,
+      spec: specText,
+      now,
+      meta: { createdWith: 'chart-builder', builtFromDataset: config.datasetName },
+    });
+
+    notify({
+      kind: 'success',
+      title: 'Snippet created',
+      message: `"${name}" was added to your library and opened in the editor.`,
+    });
+    void closeModal(true); // the create is the user's confirmation — no discard prompt
+    get().reset();
+    return true;
+  },
+
+  reset: () => set({ datasetId: null, columns: EMPTY_COLUMNS, config: EMPTY_CONFIG }),
+}));
+
+/**
+ * Selector: whether the config can be saved (≥1 channel mapped, spec §06 →
+ * Validation). Returns a boolean (stable under Object.is), so it is safe to
+ * subscribe to directly. Non-blocking *guidance* (`builderWarnings`) deliberately
+ * has NO selector here — it builds a fresh array of objects each call, which no
+ * subscription equality can stabilize; the component derives it via `useMemo` over
+ * the stable `config` reference instead (see ChartBuilderModal).
+ */
+export const selectBuilderValid = (s: ChartBuilderState) => isBuilderConfigValid(s.config);
+
+/** Selector: the built spec as JSON text, for the live preview. */
+export const selectBuilderSpecText = (s: ChartBuilderState) => buildSnippetSpecText(s.config);