@unovis/mcp 1.7.0-mcp.0

package/dist/recipes/nested-donut.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { commonInput, dataRecords, fieldName, assertFieldsExist, baseSpec, field } from './shared.js';
+export const nestedDonutInputShape = {
+    data: dataRecords,
+    layers: z.array(fieldName).min(1).max(4)
+        .describe('Fields defining the hierarchy rings, innermost ring first, e.g. ["region", "country"]'),
+    value: fieldName.optional()
+        .describe('Field with the numeric segment weight. Records are counted when omitted'),
+    centralLabel: z.string().optional().describe('Text in the middle of the donut'),
+    centralSubLabel: z.string().optional().describe('Smaller text under the central label'),
+    layerPadding: z.number().min(0).max(20).default(0).describe('Gap between rings in pixels'),
+    cornerRadius: z.number().min(0).max(20).default(0).describe('Segment corner radius in pixels'),
+    showSegmentLabels: z.boolean().default(true).describe('Show the category name on each segment (labels that do not fit are hidden)'),
+    ...commonInput,
+};
+export const nestedDonutRecipe = {
+    name: 'generate_nested_donut_chart',
+    title: 'Nested donut / sunburst chart',
+    description: 'Generate a nested donut (sunburst) chart showing hierarchical part-of-whole data as concentric rings, ' +
+        'innermost ring first. Segments are sized by the value field, or by record count when it is omitted. ' +
+        'Example: data=[{"region":"EMEA","country":"Germany","sales":420},{"region":"EMEA","country":"France","sales":310}], layers=["region","country"], value="sales".',
+    inputShape: nestedDonutInputShape,
+    toSpec: (input) => {
+        const data = input.data;
+        assertFieldsExist(data, [...input.layers, input.value]);
+        return {
+            container: 'single',
+            ...baseSpec(input),
+            components: [{
+                    type: 'NestedDonut',
+                    config: {
+                        layers: input.layers.map(layer => field(layer)),
+                        // 'outwards' places layers[0] on the innermost ring, leaves outward
+                        direction: 'outwards',
+                        ...(input.value ? { value: field(input.value, 'number') } : {}),
+                        centralLabel: input.centralLabel,
+                        centralSubLabel: input.centralSubLabel,
+                        layerPadding: input.layerPadding,
+                        cornerRadius: input.cornerRadius,
+                        showSegmentLabels: input.showSegmentLabels,
+                    },
+                }],
+            data,
+        };
+    },
+};
+//# sourceMappingURL=nested-donut.js.map

package/dist/recipes/nested-donut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-donut.js","sourceRoot":"","sources":["../../src/recipes/nested-donut.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGrG,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;SACrC,QAAQ,CAAC,uFAAuF,CAAC;IACpG,KAAK,EAAE,SAAS,CAAC,QAAQ,EAAE;SACxB,QAAQ,CAAC,yEAAyE,CAAC;IACtF,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAC/E,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACvF,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC1F,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAC9F,iBAAiB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,4EAA4E,CAAC;IACnI,GAAG,WAAW;CACf,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAyC;IACrE,IAAI,EAAE,6BAA6B;IACnC,KAAK,EAAE,+BAA+B;IACtC,WAAW,EAAE,wGAAwG;QACnH,sGAAsG;QACtG,iKAAiK;IACnK,UAAU,EAAE,qBAAqB;IACjC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;QAChB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAoB,CAAA;QACvC,iBAAiB,CAAC,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;QAEvD,OAAO;YACL,SAAS,EAAE,QAAQ;YACnB,GAAG,QAAQ,CAAC,KAAK,CAAC;YAClB,UAAU,EAAE,CAAC;oBACX,IAAI,EAAE,aAAa;oBACnB,MAAM,EAAE;wBACN,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;wBAC/C,oEAAoE;wBACpE,SAAS,EAAE,UAAU;wBACrB,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC/D,YAAY,EAAE,KAAK,CAAC,YAAY;wBAChC,eAAe,EAAE,KAAK,CAAC,eAAe;wBACtC,YAAY,EAAE,KAAK,CAAC,YAAY;wBAChC,YAAY,EAAE,KAAK,CAAC,YAAY;wBAChC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;qBAC3C;iBACF,CAAC;YACF,IAAI;SACL,CAAA;IACH,CAAC;CACF,CAAA"}

package/dist/recipes/radial-bar.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { Recipe } from './types.js';
+export declare const radialBarInputShape: {
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    framework: z.ZodDefault<z.ZodEnum<["ts", "react", "svelte", "vue", "angular", "solid"]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["svg", "png", "html", "interactive", "config", "code"]>>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+    value: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    maxValue: z.ZodOptional<z.ZodNumber>;
+    arcWidth: z.ZodDefault<z.ZodNumber>;
+    arcPadding: z.ZodDefault<z.ZodNumber>;
+    cornerRadius: z.ZodOptional<z.ZodNumber>;
+    centralLabel: z.ZodOptional<z.ZodString>;
+    centralSubLabel: z.ZodOptional<z.ZodString>;
+    showBackground: z.ZodDefault<z.ZodBoolean>;
+    legend: z.ZodDefault<z.ZodBoolean>;
+};
+export declare const radialBarRecipe: Recipe<typeof radialBarInputShape>;

package/dist/recipes/radial-bar.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { commonInput, dataRecords, fieldName, assertFieldsExist, baseSpec, field } from './shared.js';
+export const radialBarInputShape = {
+    data: dataRecords,
+    value: fieldName.describe('Field with the numeric value of each ring'),
+    label: fieldName.optional().describe('Field with the ring name (used for the legend)'),
+    maxValue: z.number().positive().optional()
+        .describe('Value at which a ring forms a full circle. Defaults to the largest value in the data'),
+    arcWidth: z.number().min(2).max(100).default(16).describe('Ring thickness in pixels'),
+    arcPadding: z.number().min(0).max(40).default(4).describe('Gap between rings in pixels'),
+    cornerRadius: z.number().min(0).max(50).optional()
+        .describe('Rounded bar ends, in pixels. Defaults to half the ring thickness'),
+    centralLabel: z.string().optional().describe('Text in the middle of the rings'),
+    centralSubLabel: z.string().optional().describe('Smaller text under the central label'),
+    showBackground: z.boolean().default(true).describe('Show a faded full-circle track behind each ring'),
+    legend: z.boolean().default(true).describe('Show a legend (requires the label field)'),
+    ...commonInput,
+};
+export const radialBarRecipe = {
+    name: 'generate_radial_bar_chart',
+    title: 'Radial bar chart',
+    description: 'Generate a radial bar chart (activity rings): one concentric ring per record, ' +
+        'filled proportionally to its value. Good for progress toward goals or comparing a few values. ' +
+        'Example: data=[{"metric":"Move","pct":84},{"metric":"Exercise","pct":62}], value="pct", label="metric", maxValue=100.',
+    inputShape: radialBarInputShape,
+    toSpec: (input) => {
+        const data = input.data;
+        assertFieldsExist(data, [input.value, input.label]);
+        const legend = input.legend && input.label
+            ? data.map((d, i) => ({ name: String(d[input.label]), paletteIndex: i, color: input.colors?.[i % (input.colors.length || 1)] }))
+            : undefined;
+        return {
+            container: 'single',
+            ...baseSpec(input),
+            components: [{
+                    type: 'RadialBar',
+                    config: {
+                        value: field(input.value, 'number'),
+                        ...(input.maxValue !== undefined ? { maxValue: input.maxValue } : {}),
+                        trackWidth: input.arcWidth,
+                        trackPadding: input.arcPadding,
+                        cornerRadius: input.cornerRadius ?? Math.floor(input.arcWidth / 2),
+                        centralLabel: input.centralLabel,
+                        centralSubLabel: input.centralSubLabel,
+                        showBackground: input.showBackground,
+                    },
+                }],
+            legend,
+            data,
+        };
+    },
+};
+//# sourceMappingURL=radial-bar.js.map

package/dist/recipes/radial-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"radial-bar.js","sourceRoot":"","sources":["../../src/recipes/radial-bar.ts"],"names":[],"mappings":"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"}

package/dist/recipes/sankey.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { Recipe } from './types.js';
+export declare const sankeyInputShape: {
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    framework: z.ZodDefault<z.ZodEnum<["ts", "react", "svelte", "vue", "angular", "solid"]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["svg", "png", "html", "interactive", "config", "code"]>>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    links: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        target: z.ZodString;
+        value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        source: string;
+        target: string;
+    }, {
+        value: number;
+        source: string;
+        target: string;
+    }>, "many">;
+    nodes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        label?: string | undefined;
+    }, {
+        id: string;
+        label?: string | undefined;
+    }>, "many">>;
+    nodeWidth: z.ZodDefault<z.ZodNumber>;
+    nodePadding: z.ZodDefault<z.ZodNumber>;
+    showValues: z.ZodDefault<z.ZodBoolean>;
+    valueSuffix: z.ZodDefault<z.ZodString>;
+};
+export declare const sankeyRecipe: Recipe<typeof sankeyInputShape>;

package/dist/recipes/sankey.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { commonInput, baseSpec, ChartInputError } from './shared.js';
+const sankeyNode = z.object({
+    id: z.string().min(1),
+    label: z.string().optional().describe('Display name (defaults to id)'),
+}).describe('A node; optional if all nodes can be derived from links');
+const sankeyLink = z.object({
+    source: z.string().min(1).describe('Source node id'),
+    target: z.string().min(1).describe('Target node id'),
+    value: z.number().positive().describe('Flow volume'),
+});
+export const sankeyInputShape = {
+    links: z.array(sankeyLink).min(1).describe('Flows between nodes, e.g. [{"source":"A","target":"B","value":10}]'),
+    nodes: z.array(sankeyNode).optional().describe('Node definitions; derived from links when omitted'),
+    nodeWidth: z.number().min(2).max(100).default(25).describe('Node bar width in pixels'),
+    nodePadding: z.number().min(0).max(100).default(8).describe('Vertical padding between nodes'),
+    showValues: z.boolean().default(true).describe('Show node totals as sub-labels'),
+    valueSuffix: z.string().default('').describe('Unit appended to node values, e.g. " GB"'),
+    ...commonInput,
+};
+export const sankeyRecipe = {
+    name: 'generate_sankey_diagram',
+    title: 'Sankey diagram',
+    description: 'Generate a Sankey diagram visualizing flows between stages/nodes (e.g. traffic, budgets, energy). ' +
+        'Provide links as {source, target, value}; nodes are derived automatically. The graph must be acyclic. ' +
+        'Example: links=[{"source":"Salary","target":"Budget","value":5000},{"source":"Budget","target":"Rent","value":2000}].',
+    inputShape: sankeyInputShape,
+    toSpec: (input) => {
+        const declared = new Map((input.nodes ?? []).map(n => [n.id, n]));
+        const ids = new Set();
+        for (const link of input.links) {
+            ids.add(link.source);
+            ids.add(link.target);
+            if (link.source === link.target)
+                throw new ChartInputError(`Self-referencing link: "${link.source}" → "${link.target}"`);
+        }
+        for (const node of declared.keys())
+            ids.add(node);
+        const nodes = Array.from(ids).map(id => ({
+            id,
+            label: declared.get(id)?.label ?? id,
+        }));
+        return {
+            container: 'single',
+            ...baseSpec(input),
+            components: [{
+                    type: 'Sankey',
+                    config: {
+                        label: { $field: 'label' },
+                        nodeWidth: input.nodeWidth,
+                        nodePadding: input.nodePadding,
+                        labelFit: 'trim',
+                        labelMaxWidth: Math.max(80, input.width * 0.16),
+                        ...(input.showValues ? { subLabel: { $format: { field: 'value', suffix: input.valueSuffix } } } : {}),
+                    },
+                }],
+            data: { nodes, links: input.links },
+        };
+    },
+};
+//# sourceMappingURL=sankey.js.map

package/dist/recipes/sankey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sankey.js","sourceRoot":"","sources":["../../src/recipes/sankey.ts"],"names":[],"mappings":"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"}

package/dist/recipes/scatter.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import type { Recipe } from './types.js';
+export declare const scatterInputShape: {
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    framework: z.ZodDefault<z.ZodEnum<["ts", "react", "svelte", "vue", "angular", "solid"]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["svg", "png", "html", "interactive", "config", "code"]>>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    xAxisLabel: z.ZodOptional<z.ZodString>;
+    yAxisLabel: z.ZodOptional<z.ZodString>;
+    showGridLines: z.ZodDefault<z.ZodBoolean>;
+    legend: z.ZodDefault<z.ZodBoolean>;
+    referenceLines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        axis: z.ZodDefault<z.ZodEnum<["x", "y"]>>;
+        value: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        lineWidth: z.ZodDefault<z.ZodNumber>;
+        style: z.ZodDefault<z.ZodEnum<["dashed", "solid", "dotted"]>>;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        style: "solid" | "dashed" | "dotted";
+        axis: "x" | "y";
+        lineWidth: number;
+        label?: string | undefined;
+        color?: string | undefined;
+    }, {
+        value: number;
+        label?: string | undefined;
+        color?: string | undefined;
+        style?: "solid" | "dashed" | "dotted" | undefined;
+        axis?: "x" | "y" | undefined;
+        lineWidth?: number | undefined;
+    }>, "many">>;
+    referenceBands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        axis: z.ZodDefault<z.ZodEnum<["x", "y"]>>;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        axis: "x" | "y";
+        from: number;
+        to: number;
+        label?: string | undefined;
+        color?: string | undefined;
+    }, {
+        from: number;
+        to: number;
+        label?: string | undefined;
+        color?: string | undefined;
+        axis?: "x" | "y" | undefined;
+    }>, "many">>;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+    x: z.ZodString;
+    y: z.ZodString;
+    size: z.ZodOptional<z.ZodString>;
+    sizeRange: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    pointSize: z.ZodDefault<z.ZodNumber>;
+    colorBy: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    shape: z.ZodDefault<z.ZodEnum<["circle", "cross", "diamond", "square", "star", "triangle", "wye"]>>;
+};
+export declare const scatterRecipe: Recipe<typeof scatterInputShape>;

package/dist/recipes/scatter.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { commonInput, xyInput, dataRecords, fieldName, assertFieldsExist, baseSpec, distinctValues, field, seriesLegend, xyAxes, xyDecorations, decorationComponents, } from './shared.js';
+/** Category color: custom palette entries cycle; otherwise theme palette variables
+ * (resolved to literal colors per theme during SVG post-processing) */
+const categoryColor = (i, colors) => colors?.length ? colors[i % colors.length] : `var(--vis-color${i % 6})`;
+/** Neutral grey for points whose category is missing (works on both themes) */
+const UNKNOWN_CATEGORY_COLOR = '#94A0AB';
+export const scatterInputShape = {
+    data: dataRecords,
+    x: fieldName.describe('Field for X values (numeric)'),
+    y: fieldName.describe('Field for Y values (numeric)'),
+    size: fieldName.optional()
+        .describe('Numeric field mapped to point size (bubble chart). Values are scaled into sizeRange'),
+    sizeRange: z.tuple([z.number().min(1).max(200), z.number().min(1).max(200)]).default([8, 40])
+        .describe('Point diameter range [min, max] in pixels, used when size is set'),
+    pointSize: z.number().min(1).max(100).default(10)
+        .describe('Fixed point diameter in pixels, used when size is not set'),
+    colorBy: fieldName.optional()
+        .describe('Categorical field: points are colored by its value and a legend is shown'),
+    label: fieldName.optional()
+        .describe('Field with point labels. Overlapping labels are hidden automatically'),
+    shape: z.enum(['circle', 'cross', 'diamond', 'square', 'star', 'triangle', 'wye']).default('circle')
+        .describe('Point shape'),
+    ...xyDecorations,
+    ...xyInput,
+    ...commonInput,
+};
+export const scatterRecipe = {
+    name: 'generate_scatter_plot',
+    title: 'Scatter plot',
+    description: 'Generate a scatter plot (or bubble chart) showing the relationship between two numeric fields. ' +
+        'Optional: size field for bubbles, colorBy category field for colored groups with a legend, label field for point labels. ' +
+        'Example: data=[{"gdp":43000,"lifeExp":81.2,"pop":38.2,"region":"Europe","country":"..."},...], ' +
+        'x="gdp", y="lifeExp", size="pop", colorBy="region", label="country".',
+    inputShape: scatterInputShape,
+    toSpec: (input) => {
+        const data = input.data;
+        assertFieldsExist(data, [input.x, input.y, input.size, input.colorBy, input.label]);
+        // Categorical coloring: distinct categories map onto the palette in
+        // first-seen order; the legend mirrors the same order/colors.
+        let color;
+        let legend;
+        if (input.colorBy) {
+            const categories = distinctValues(data, input.colorBy).map(String);
+            const mapping = {};
+            categories.forEach((category, i) => { mapping[category] = categoryColor(i, input.colors); });
+            color = { $mapField: { field: input.colorBy, mapping, fallback: UNKNOWN_CATEGORY_COLOR } };
+            legend = seriesLegend(categories, input.legend, input.colors);
+        }
+        const axes = xyAxes(input);
+        const deco = decorationComponents(input);
+        return {
+            container: 'xy',
+            ...baseSpec(input),
+            components: [...deco.bands, {
+                    type: 'Scatter',
+                    config: {
+                        x: field(input.x, 'number'),
+                        y: field(input.y, 'number'),
+                        shape: input.shape,
+                        ...(input.size
+                            ? { size: field(input.size, 'number'), sizeRange: input.sizeRange }
+                            : { size: input.pointSize }),
+                        ...(color ? { color } : {}),
+                        ...(input.label ? { label: { $field: input.label } } : {}),
+                    },
+                }, ...deco.lines],
+            xAxis: { ...axes.xAxis, tickFormat: { $numTickFormat: true } },
+            yAxis: { ...axes.yAxis, tickFormat: { $numTickFormat: true } },
+            legend,
+            data,
+        };
+    },
+};
+//# sourceMappingURL=scatter.js.map

package/dist/recipes/scatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scatter.js","sourceRoot":"","sources":["../../src/recipes/scatter.ts"],"names":[],"mappings":"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"}

package/dist/recipes/shared.d.ts

@@ -0,0 +1,144 @@
+/** Shared schema fragments and helpers for chart recipes.
+ *
+ * Conventions:
+ *  - data is always an array of flat records
+ *  - accessors are field names (never code)
+ *  - every option has a description and a sane default
+ *  - enums over free-form strings, bounded numbers
+ */
+import { z } from 'zod';
+import { ChartInputError } from '../render/materialize.js';
+import type { AccessorRef, AxisSpec, ChartSpec, ComponentSpec, LegendItemSpec } from '../render/spec.js';
+export { ChartInputError };
+export declare const dataValue: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export declare const dataRecords: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, "many">;
+export declare const fieldName: z.ZodString;
+export declare const commonInput: {
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    framework: z.ZodDefault<z.ZodEnum<["ts", "react", "svelte", "vue", "angular", "solid"]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["svg", "png", "html", "interactive", "config", "code"]>>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    scale: z.ZodDefault<z.ZodNumber>;
+};
+export declare const xyInput: {
+    xAxisLabel: z.ZodOptional<z.ZodString>;
+    yAxisLabel: z.ZodOptional<z.ZodString>;
+    showGridLines: z.ZodDefault<z.ZodBoolean>;
+    legend: z.ZodDefault<z.ZodBoolean>;
+};
+/** Reference-line / shaded-band decorations available on XY charts */
+export declare const xyDecorations: {
+    referenceLines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        axis: z.ZodDefault<z.ZodEnum<["x", "y"]>>;
+        value: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        lineWidth: z.ZodDefault<z.ZodNumber>;
+        style: z.ZodDefault<z.ZodEnum<["dashed", "solid", "dotted"]>>;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        style: "solid" | "dashed" | "dotted";
+        axis: "x" | "y";
+        lineWidth: number;
+        label?: string | undefined;
+        color?: string | undefined;
+    }, {
+        value: number;
+        label?: string | undefined;
+        color?: string | undefined;
+        style?: "solid" | "dashed" | "dotted" | undefined;
+        axis?: "x" | "y" | undefined;
+        lineWidth?: number | undefined;
+    }>, "many">>;
+    referenceBands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        axis: z.ZodDefault<z.ZodEnum<["x", "y"]>>;
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        axis: "x" | "y";
+        from: number;
+        to: number;
+        label?: string | undefined;
+        color?: string | undefined;
+    }, {
+        from: number;
+        to: number;
+        label?: string | undefined;
+        color?: string | undefined;
+        axis?: "x" | "y" | undefined;
+    }>, "many">>;
+};
+export interface DecorationInput {
+    referenceLines?: {
+        axis: 'x' | 'y';
+        value: number;
+        label?: string;
+        color?: string;
+        lineWidth: number;
+        style: 'dashed' | 'solid' | 'dotted';
+    }[];
+    referenceBands?: {
+        axis: 'x' | 'y';
+        from: number;
+        to: number;
+        label?: string;
+        color?: string;
+    }[];
+}
+/** Decoration components: bands render behind the data, lines on top */
+export declare function decorationComponents(input: DecorationInput): {
+    bands: ComponentSpec[];
+    lines: ComponentSpec[];
+};
+export type DataRecord = Record<string, string | number | boolean | null>;
+export declare const field: (name: string, as?: "number" | "string" | "date") => AccessorRef;
+export declare const toArray: <T>(value: T | T[]) => T[];
+/** Throw an actionable error when referenced fields are missing from the data */
+export declare function assertFieldsExist(data: DataRecord[], fields: (string | undefined)[]): void;
+/** True when every value of a field (in the first few records) is numeric */
+export declare function isNumericField(data: DataRecord[], fieldName: string): boolean;
+/** Distinct values of a field, in first-seen order */
+export declare function distinctValues(data: DataRecord[], fieldName: string): (string | number)[];
+export interface CategoricalX {
+    /** x accessor: the field itself (numeric) or a category index */
+    x: AccessorRef;
+    /** Category names when x is ordinal (drives tickFormat/numTicks) */
+    categories?: string[];
+}
+/** Numeric fields map directly; string categories map to their index with
+ * labeled ticks (Unovis XY scales are numeric). */
+export declare function categoricalX(data: DataRecord[], fieldName: string, isTime?: boolean): CategoricalX;
+/** Axis spec for a categorical dimension: one labeled tick per category.
+ * Explicit integer tickValues — approximate d3 tick counts can emit
+ * fractional ticks that would round into duplicate category labels. */
+export declare function categoryAxis(base: AxisSpec, categories: string[]): AxisSpec;
+/** Calendar-aligned tick values for date axes. Linear-scale ticks land at
+ * arbitrary times of day, which the date formatter would render as
+ * time-of-day labels ("08:53 AM" on a 3-month chart) — align ticks to
+ * month/day/hour/minute boundaries instead. */
+export declare function dateTickValues(min: number, max: number, target?: number): number[] | undefined;
+/** Tick values for a time axis derived from the data extent of a date field */
+export declare function timeTickValuesFromData(data: DataRecord[], fieldName: string): number[] | undefined;
+export declare function seriesLegend(labels: string[], enabled: boolean, colors?: string[]): LegendItemSpec[] | undefined;
+/** Common ChartSpec fields from common tool inputs */
+export declare function baseSpec(input: {
+    width: number;
+    height: number;
+    theme: 'light' | 'dark';
+    title?: string;
+    colors?: string[];
+}): Pick<ChartSpec, 'width' | 'height' | 'theme' | 'title' | 'colors'>;
+export declare function xyAxes(input: {
+    xAxisLabel?: string;
+    yAxisLabel?: string;
+    showGridLines: boolean;
+}): {
+    xAxis: AxisSpec;
+    yAxis: AxisSpec;
+};