chart-factory 0.1.2

package/src/core/d3-suggest.js

@@ -0,0 +1,565 @@
+/**
+ * ChartFactory.suggest(rows, options?) — runtime chart recommendation.
+ *
+ * Applies the chart-selection layer (docs/chart-guide.md) to real rows:
+ *   1. PROFILE  each field: kind (temporal | numeric | categorical | boolean |
+ *               id), distinct count, null count, numeric/temporal extent.
+ *   2. SIGNATURE from the profiles: measures, dimensions, temporal fields,
+ *               an entity/name field, rows-per-group shape.
+ *   3. RULES    the guide's signature table as scored rules, adjusted by each
+ *               builder's cardinality comfort ranges from the conformance
+ *               metadata (builder-metadata.generated.mjs).
+ *   4. SYNTHESIZE a render-ready { data, config } per candidate in the
+ *               builder's canonical record shape (mapped/grouped/pivoted from
+ *               the input rows — inputs are never mutated).
+ *
+ * Returns { fields, signature, candidates } — candidates sorted by score
+ * (0..1), each { builder, score, why[], caveats[], data, config, transform,
+ * create(selector, overrides?) }.
+ *
+ * This is a heuristic assistant, not an oracle: it can read shape and
+ * cardinality, but not intent. It cannot know that values are parts of one
+ * whole, that a center is defensible, or that two same-scale measures are the
+ * same unit — those judgments surface as caveats on the affected candidates.
+ * Tables are never suggested (they require Table.register()); when precision
+ * beats perception, a caveat says so.
+ */
+
+import { BUILDER_METADATA } from './builder-metadata.generated.mjs';
+
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}([T ].*)?$/;
+const PROFILE_SAMPLE = 1000;
+
+// ---------------------------------------------------------------------------
+// 1. Field profiling
+// ---------------------------------------------------------------------------
+
+function profileField(name, values, rowCount) {
+    const nonNull = values.filter(v => v !== null && v !== undefined && v !== '');
+    const nulls = values.length - nonNull.length;
+    if (nonNull.length === 0) return { name, kind: 'empty', distinct: 0, nulls };
+
+    let dates = 0, numbers = 0, booleans = 0, strings = 0;
+    const nums = [];
+    for (const v of nonNull) {
+        if (v instanceof Date) { dates++; continue; }
+        if (typeof v === 'boolean') { booleans++; continue; }
+        if (typeof v === 'number' && Number.isFinite(v)) { numbers++; nums.push(v); continue; }
+        if (typeof v === 'string') {
+            if (ISO_DATE_RE.test(v.trim())) { dates++; continue; }
+            const n = Number(v);
+            // Numeric strings count as numbers (CSV loaders yield strings),
+            // but not ''-coerced or whitespace values.
+            if (v.trim() !== '' && Number.isFinite(n)) { numbers++; nums.push(n); continue; }
+            strings++;
+            continue;
+        }
+        strings++; // objects/arrays — treat as opaque
+    }
+
+    const distinct = new Set(nonNull.map(v => (v instanceof Date ? v.getTime() : v))).size;
+    const share = (c) => c / nonNull.length;
+    const base = { name, distinct, nulls, count: nonNull.length };
+
+    if (share(dates) >= 0.9) {
+        const times = nonNull
+            .map(v => (v instanceof Date ? v : new Date(v)).getTime())
+            .filter(Number.isFinite)
+            .sort((a, b) => a - b);
+        const gaps = [];
+        for (let i = 1; i < Math.min(times.length, 200); i++) gaps.push(times[i] - times[i - 1]);
+        gaps.sort((a, b) => a - b);
+        const medianGapMs = gaps.length ? gaps[Math.floor(gaps.length / 2)] : null;
+        return { ...base, kind: 'temporal', min: times[0], max: times[times.length - 1], medianGapMs };
+    }
+    if (share(booleans) >= 0.9) return { ...base, kind: 'boolean' };
+    if (share(numbers) >= 0.9) {
+        const min = Math.min(...nums), max = Math.max(...nums);
+        const allInt = nums.every(Number.isInteger);
+        // Year-like integers (1500..2100, several distinct values) can serve
+        // as the temporal axis when no true date field exists.
+        const yearLike = allInt && min >= 1500 && max <= 2100 && distinct >= 3 && distinct === new Set(nums).size;
+        return { ...base, kind: 'numeric', min, max, allInt, yearLike };
+    }
+    // Strings: id-like when (nearly) unique per row, categorical otherwise.
+    if (distinct >= rowCount * 0.9 && rowCount > 6) return { ...base, kind: 'id' };
+    return { ...base, kind: 'categorical' };
+}
+
+export function profileFields(rows) {
+    const sample = rows.length > PROFILE_SAMPLE ? rows.slice(0, PROFILE_SAMPLE) : rows;
+    const keys = new Set();
+    for (const r of sample) for (const k of Object.keys(r || {})) keys.add(k);
+    return [...keys].map(k => profileField(k, sample.map(r => (r || {})[k]), rows.length));
+}
+
+// ---------------------------------------------------------------------------
+// 2. Signature
+// ---------------------------------------------------------------------------
+
+const DAY_MS = 24 * 3600 * 1000;
+const PAIR_PATTERNS = [
+    [/^(before|prev|previous|last|old|start|from|open|low)$/i, /^(after|next|current|new|end|to|close|high)$/i],
+];
+
+function buildSignature(rows, fields) {
+    const byKind = (k) => fields.filter(f => f.kind === k);
+    let temporal = byKind('temporal');
+    let measures = byKind('numeric');
+    const dimensions = byKind('categorical').concat(byKind('boolean'));
+    const idFields = byKind('id');
+
+    // A year-like numeric stands in as the temporal axis when no real one exists.
+    if (temporal.length === 0) {
+        const year = measures.find(f => f.yearLike);
+        if (year) {
+            temporal = [{ ...year, kind: 'temporal', yearStandin: true }];
+            measures = measures.filter(f => f !== year);
+        }
+    }
+
+    // Same-unit measure pairs (before/after, start/end, low/high, 2023/2024):
+    // name patterns, or a year-pair of column names, with overlapping ranges.
+    let pair = null;
+    for (let i = 0; i < measures.length && !pair; i++) {
+        for (let j = 0; j < measures.length && !pair; j++) {
+            if (i === j) continue;
+            const [a, b] = [measures[i], measures[j]];
+            const named = PAIR_PATTERNS.some(([ra, rb]) => ra.test(a.name) && rb.test(b.name));
+            const years = /^\d{4}$/.test(a.name) && /^\d{4}$/.test(b.name) && +a.name < +b.name;
+            if (named || years) pair = [a, b];
+        }
+    }
+    if (!pair && measures.length === 2) {
+        // Range overlap as a weak same-unit proxy (never for named mismatches).
+        const [a, b] = measures;
+        const lo = Math.max(a.min, b.min), hi = Math.min(a.max, b.max);
+        const span = Math.max(a.max, b.max) - Math.min(a.min, b.min);
+        if (span > 0 && (hi - lo) / span > 0.5) pair = null; // note only — do not assert pairing
+    }
+
+    // One row per unique string + a single measure IS a category axis (teams →
+    // wins): the id/categorical distinction collapses, so promote the id field
+    // to the grouping dimension when it's the only candidate.
+    let nameField = idFields[0] || null;
+    if (dimensions.length === 0 && temporal.length === 0 && measures.length === 1 && nameField &&
+        nameField.distinct >= nameField.count * 0.98) {
+        dimensions.push({ ...nameField, kind: 'categorical', promoted: true });
+        nameField = idFields[1] || null;
+    }
+
+    const primaryDim = dimensions.slice().sort((a, b) => a.distinct - b.distinct)[0] || null;
+    const rowsPerGroup = primaryDim ? rows.length / primaryDim.distinct : rows.length;
+    const t = temporal[0] || null;
+    // Daily = the median gap is about one day; sub-daily (hourly) data must
+    // NOT read as daily, or Calendar would aggregate-by-accident.
+    const daily = !!(t && !t.yearStandin && t.medianGapMs !== null &&
+        t.medianGapMs >= 0.5 * DAY_MS && t.medianGapMs <= 1.5 * DAY_MS);
+
+    return {
+        rowCount: rows.length,
+        temporal, measures, dimensions, idFields,
+        nameField,
+        primaryDim, rowsPerGroup, pair, daily,
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: transforms (pure — inputs never mutated) + cardinality scoring
+// ---------------------------------------------------------------------------
+
+const val = (row, f) => {
+    const v = row[f.name];
+    return typeof v === 'string' && f.kind !== 'categorical' && f.kind !== 'id' ? Number(v) : v;
+};
+
+function sortByField(rows, f) {
+    const key = (r) => {
+        const v = r[f.name];
+        return v instanceof Date ? v.getTime() : (typeof v === 'string' && ISO_DATE_RE.test(v) ? Date.parse(v) : v);
+    };
+    return rows.slice().sort((a, b) => key(a) - key(b));
+}
+
+function groupBy(rows, f) {
+    const m = new Map();
+    for (const r of rows) {
+        const k = r[f.name];
+        if (!m.has(k)) m.set(k, []);
+        m.get(k).push(r);
+    }
+    return m;
+}
+
+/** Sum a measure per dimension value → canonical {category, value} rows. */
+function rollupSum(rows, dim, measure) {
+    const m = new Map();
+    for (const r of rows) {
+        const k = r[dim.name];
+        m.set(k, (m.get(k) || 0) + (Number(val(r, measure)) || 0));
+    }
+    return [...m.entries()].map(([category, value]) => ({ category, value }));
+}
+
+function fitRange(n, range) {
+    if (!range) return 0;
+    const [min, max] = range;
+    if ((min === null || n >= min) && (max === null || n <= max)) return 1;
+    return -1;
+}
+
+/**
+ * Adjust a candidate's score by the builder's metadata cardinality ranges.
+ * dims: { series?, categories?, points?, rows?, ... } — observed counts.
+ */
+function applyCardinality(cand, dims) {
+    const card = (BUILDER_METADATA[cand.builder] || {}).cardinality || {};
+    for (const [dim, n] of Object.entries(dims)) {
+        const fit = fitRange(n, card[dim]);
+        if (fit === 1) {
+            cand.score += 0.03;
+            cand.why.push(`${n} ${dim} fits the comfortable ${fmtRange(card[dim])}`);
+        } else if (fit === -1) {
+            cand.score -= 0.25;
+            cand.caveats.push(`${n} ${dim} is outside the comfortable ${fmtRange(card[dim])} — reshape (data.topN / data.rollup / facet) or pick another form`);
+        }
+    }
+    return cand;
+}
+
+function fmtRange([min, max]) {
+    if (min !== null && max !== null) return `${min}–${max}`;
+    if (min !== null) return `${min}+`;
+    return `up to ${max}`;
+}
+
+// ---------------------------------------------------------------------------
+// 3+4. Rules with config synthesis
+// ---------------------------------------------------------------------------
+
+function suggestCandidates(rows, sig) {
+    const out = [];
+    const push = (builder, score, why, cfg, dims = {}, caveats = [], transform = null) => {
+        const cand = { builder, score, why: [].concat(why), caveats: [].concat(caveats), transform, ...cfg };
+        out.push(applyCardinality(cand, dims));
+    };
+    const t = sig.temporal[0] || null;
+    const M = sig.measures, D = sig.dimensions, n = sig.rowCount;
+    const m1 = M[0], m2 = M[1];
+    const dim = sig.primaryDim;
+    const name = sig.nameField;
+
+    // --- temporal + measure(s), no grouping dimension -----------------------
+    if (t && m1 && !dim) {
+        const sorted = sortByField(rows, t);
+        push('Line.createBasic', 0.9,
+            `1 temporal (${t.name}) + 1 measure (${m1.name}) — the default trend chart`,
+            { data: sorted, config: { x: t.name, y: m1.name } },
+            { points: n, series: 1 });
+        push('Area.createBasic', 0.55,
+            `same signature when filled magnitude-from-zero is the message`,
+            { data: sorted, config: { x: t.name, y: m1.name } },
+            { points: n, series: 1 },
+            'only if zero is a meaningful baseline for this measure');
+        if (M.length >= 2) {
+            const series = M.map(m => ({ name: m.name, data: sorted.map(r => ({ x: r[t.name], y: val(r, m) })) }));
+            const sameScaleish = Math.min(...M.map(m => m.min)) >= 0 || true;
+            push('Line.createMulti', 0.85,
+                `${M.length} measures over one temporal axis (${t.name}) — compare as series`,
+                { data: rows, config: { series } },
+                { series: M.length, pointsPerSeries: n },
+                sameScaleish && spanRatio(M) > 100 ? 'measure ranges differ by >100x — likely different units; prefer separate charts in a linkGroup' : [],
+                `built series[] from measures [${M.map(m => m.name).join(', ')}]`);
+        }
+        if (sig.daily && n >= 60) {
+            push('Calendar.createHeatmap', 0.7,
+                `daily grain over ${n} days — weekday/streak rhythm`,
+                { data: rows.map(r => ({ date: r[t.name], value: val(r, m1) })), config: {} },
+                { days: n },
+                [], `mapped to { date: ${t.name}, value: ${m1.name} }`);
+        }
+    }
+
+    // --- temporal + measure + grouping dimension (long/panel data) ----------
+    if (t && m1 && dim) {
+        const sorted = sortByField(rows, t);
+        const groups = groupBy(sorted, dim);
+        const series = [...groups.entries()].map(([g, rs]) => ({ name: String(g), data: rs.map(r => ({ x: r[t.name], y: val(r, m1) })) }));
+        const periodCount = t.distinct;
+        push('Line.createMulti', 0.9,
+            `1 temporal (${t.name}) + 1 measure (${m1.name}) grouped by ${dim.name} (${dim.distinct} series)`,
+            { data: rows, config: { series } },
+            { series: dim.distinct, pointsPerSeries: Math.round(sig.rowsPerGroup) },
+            dim.distinct > 6 ? `past ~6 series consider facet('#grid', { data, by: '${dim.name}', ... })` : [],
+            `grouped rows by ${dim.name} into series[]`);
+        const yearNames = [...groups.keys()].every(k => /^\d{4}$/.test(String(k)));
+        if (yearNames) {
+            push('Line.createYoY', 0.85,
+                `the grouping dimension is years — same measure compared across years wants the recency ramp`,
+                { data: rows, config: { series } },
+                { series: dim.distinct },
+                [], `grouped rows by ${dim.name} (years) into series[]`);
+        }
+        if (M.length === 1 && M[0].min >= 0) {
+            const wideMap = new Map();
+            for (const r of sorted) {
+                const k = r[t.name] instanceof Date ? r[t.name].getTime() : r[t.name];
+                if (!wideMap.has(k)) wideMap.set(k, { x: r[t.name] });
+                wideMap.get(k)[r[dim.name]] = val(r, m1);
+            }
+            const keys = [...groups.keys()].map(String);
+            push('Area.createStacked', 0.7,
+                `composition over time — total and mix together`,
+                { data: [...wideMap.values()], config: { x: 'x', keys } },
+                { series: dim.distinct, points: wideMap.size },
+                ['stacking assumes the series are parts of one whole'],
+                `pivoted wide: one row per ${t.name}, one column per ${dim.name}`);
+        }
+        if (periodCount === 2) {
+            const slopeRows = twoPointRows(sorted, t, dim, m1);
+            if (slopeRows) {
+                push('Slope.createBasic', 0.85,
+                    `exactly two ${t.name} values — every ${dim.name}'s change in one glance`,
+                    { data: slopeRows, config: {} },
+                    { rows: slopeRows.length, periods: 2 },
+                    [], `reshaped to { name: ${dim.name}, before, after }`);
+                push('Dot.createDumbbell', 0.8,
+                    `the two-point change as gap-focused rows — scales past slope's label limit`,
+                    { data: slopeRows.map(r => ({ name: r.name, start: r.before, end: r.after })), config: {} },
+                    { rows: slopeRows.length },
+                    [], `reshaped to { name: ${dim.name}, start, end }`);
+            }
+        }
+    }
+
+    // --- categorical + one measure ------------------------------------------
+    if (!t && m1 && dim && M.length === 1) {
+        if (sig.rowsPerGroup <= 1.5) {
+            const mapped = rows.map(r => ({ category: r[dim.name], value: val(r, m1) }));
+            const ranked = mapped.slice().sort((a, b) => b.value - a.value);
+            const signed = mapped.some(r => r.value < 0) && mapped.some(r => r.value > 0);
+            push('Bar.createBasic', signed ? 0.55 : 0.9,
+                `1 categorical (${dim.name}) + 1 measure (${m1.name}), one row per category — ranked bars`,
+                { data: ranked, config: {} },
+                { rows: dim.distinct },
+                signed ? 'values cross zero — Bar.createDiverging shows the sign structure' : [],
+                `mapped to { category: ${dim.name}, value: ${m1.name} }, sorted desc`);
+            push('Bar.createVertical', 0.6,
+                `columns when the category order itself matters — keep the source order`,
+                { data: mapped.map(r => ({ x: String(r.category), y: r.value })), config: {} },
+                { categories: dim.distinct },
+                [], `mapped to { x: ${dim.name}, y: ${m1.name} }`);
+            if (mapped.every(r => r.value >= 0)) {
+                push('Donut.createBasic', 0.45,
+                    `part-of-whole reading of the same signature`,
+                    { data: mapped.map(r => ({ label: String(r.category), value: r.value })), config: {} },
+                    { slices: dim.distinct },
+                    ['only if the values are parts of one whole — suggest() cannot verify that'],
+                    `mapped to { label: ${dim.name}, value: ${m1.name} }`);
+            }
+            if (mapped.some(r => r.value < 0) && mapped.some(r => r.value > 0)) {
+                push('Bar.createDiverging', 0.85,
+                    `signed values around zero — diverging bars beat plain bars here`,
+                    { data: mapped, config: {} },
+                    { rows: dim.distinct },
+                    [], `mapped to { category: ${dim.name}, value: ${m1.name} }`);
+            }
+        } else if (D.length === 1) {
+            // Distribution reading only when this is the ONLY categorical —
+            // a second categorical (day × hour) means the repeats are
+            // structured cells, not iid samples; the 2-dimension grid rules
+            // below own that signature.
+            const mapped = rows.map(r => ({ category: r[dim.name], value: val(r, m1) }));
+            push('BoxPlot.createBasic', 0.85,
+                `${Math.round(sig.rowsPerGroup)} records per ${dim.name} — distributions per category`,
+                { data: mapped, config: {} },
+                { categories: dim.distinct, points: Math.round(sig.rowsPerGroup) },
+                [], `mapped to { category: ${dim.name}, value: ${m1.name} }`);
+            push('Scatter.createBeeswarm', 0.7,
+                `same question with every individual visible and exact`,
+                { data: mapped, config: {} },
+                { categories: dim.distinct, points: n },
+                [], `mapped to { category: ${dim.name}, value: ${m1.name} }`);
+            if (dim.distinct <= 4) {
+                const series = [...groupBy(rows, dim).entries()]
+                    .map(([g, rs]) => ({ name: String(g), data: rs.map(r => ({ value: val(r, m1) })) }));
+                push('Histogram.createOverlay', 0.6,
+                    `${dim.distinct} groups — distribution shape on shared bins`,
+                    { data: rows, config: { series } },
+                    { series: dim.distinct, points: n },
+                    [], `grouped rows by ${dim.name} into series[] of { value: ${m1.name} }`);
+            }
+        }
+    }
+
+    // --- one bare measure ----------------------------------------------------
+    if (!t && m1 && !dim && M.length === 1) {
+        push('Histogram.createBasic', n >= 30 ? 0.9 : 0.6,
+            `a single measure (${m1.name}) across ${n} records — distribution shape`,
+            { data: rows, config: { valueAccessor: m1.name } },
+            { points: n });
+        push('Scatter.createBeeswarmHorizontal', 0.65,
+            `the same distribution with individuals visible`,
+            { data: rows.map(r => ({ value: val(r, m1), name: name ? String(r[name.name]) : undefined })), config: {} },
+            { points: n },
+            [], `mapped to { value: ${m1.name} }`);
+    }
+
+    // --- two+ measures, no/loose temporal -----------------------------------
+    if (!t && m1 && m2) {
+        const mapped = rows.map(r => ({
+            x: val(r, m1), y: val(r, m2),
+            category: dim ? String(r[dim.name]) : undefined,
+            name: name ? String(r[name.name]) : undefined,
+        }));
+        const scatterCaveats = [];
+        if (M.length > 2) scatterCaveats.push(`remaining measures unencoded: ${M.slice(2).map(m => m.name).join(', ')}`);
+        if (sig.pair) scatterCaveats.push(`${sig.pair[0].name}/${sig.pair[1].name} look like a same-unit pair — a paired form likely reads better`);
+        push('Scatter.createBasic', sig.pair ? 0.72 : 0.88,
+            `2 measures (${m1.name} vs ${m2.name}) — relationship, clusters, outliers` + (dim ? `, colored by ${dim.name}` : ''),
+            { data: mapped, config: {} },
+            { points: n },
+            scatterCaveats,
+            `mapped to { x: ${m1.name}, y: ${m2.name}${dim ? `, category: ${dim.name}` : ''}${name ? `, name: ${name.name}` : ''} }`);
+        if (sig.pair && name) {
+            const [a, b] = sig.pair;
+            push('Dot.createDumbbell', 0.92,
+                `${a.name}/${b.name} read as a same-unit pair per ${name.name} — the gap is the message`,
+                { data: rows.map(r => ({ name: String(r[name.name]), start: val(r, a), end: val(r, b) })), config: {} },
+                { rows: n },
+                [], `reshaped to { name: ${name.name}, start: ${a.name}, end: ${b.name} }`);
+            push('Slope.createBasic', 0.7,
+                `the same pair with crossings and rate-of-change visible`,
+                { data: rows.map(r => ({ name: String(r[name.name]), before: val(r, a), after: val(r, b) })), config: {} },
+                { rows: n, periods: 2 },
+                [], `reshaped to { name: ${name.name}, before: ${a.name}, after: ${b.name} }`);
+        }
+        const overlap = rangeOverlap(m1, m2);
+        if (overlap > 0.5) {
+            push('Scatter.createDiagonal', 0.6,
+                `the two measures share a scale (${Math.round(overlap * 100)}% range overlap) — above/below y = x as the verdict`,
+                { data: mapped, config: {} },
+                { points: n },
+                'only meaningful if the measures share a unit — suggest() infers this from range overlap alone');
+        }
+        if (M.length >= 3) {
+            push('Scatter.createQuadrant', 0.55,
+                `3+ measures — two on position, ${M[2].name} on bubble size`,
+                { data: mapped.map((d, i) => ({ ...d, size: val(rows[i], M[2]) })), config: { sizeAccessor: 'size' } },
+                { points: n },
+                'needs a defensible center to earn the quadrant framing — otherwise use Scatter.createBasic');
+        }
+    }
+
+    // --- two categorical dimensions + measure -------------------------------
+    if (!t && m1 && D.length >= 2 && M.length === 1) {
+        const [d1, d2] = D.slice().sort((a, b) => b.distinct - a.distinct);
+        const flowNames = D.some(d => /source|from|origin/i.test(d.name)) && D.some(d => /target|to|dest/i.test(d.name));
+        if (flowNames) {
+            const src = D.find(d => /source|from|origin/i.test(d.name));
+            const tgt = D.find(d => /target|to|dest/i.test(d.name));
+            push('Sankey.createBasic', 0.9,
+                `${src.name} → ${tgt.name} + ${m1.name} reads as flow`,
+                { data: rows.map(r => ({ source: String(r[src.name]), target: String(r[tgt.name]), value: val(r, m1) })), config: {} },
+                { nodes: src.distinct + tgt.distinct, links: n },
+                [], `mapped to { source: ${src.name}, target: ${tgt.name}, value: ${m1.name} }`);
+        }
+        // Cardinality not scored: the metadata points range describes density
+        // mode; categorical mode wants one record per cell.
+        push('Scatter.createHeatmap', 0.8,
+            `2 categoricals (${d1.name} × ${d2.name}) + 1 measure — a value grid`,
+            { data: rows.map(r => ({ x: String(r[d1.name]), y: String(r[d2.name]), value: val(r, m1) })), config: {} },
+            {},
+            d1.distinct * d2.distinct > 400 ? `${d1.distinct} × ${d2.distinct} cells — consider aggregating first` : [],
+            `mapped to { x: ${d1.name}, y: ${d2.name}, value: ${m1.name} } (categorical mode)`);
+        if (d1.distinct <= 8 && d2.distinct <= 4) {
+            const wide = new Map();
+            for (const r of rows) {
+                const k = String(r[d1.name]);
+                if (!wide.has(k)) wide.set(k, { category: k });
+                wide.get(k)[String(r[d2.name])] = val(r, m1);
+            }
+            const keys = [...new Set(rows.map(r => String(r[d2.name])))];
+            push('Bar.createGrouped', 0.7,
+                `both dimensions small (${d1.distinct} × ${d2.distinct}) — side-by-side bars with a shared baseline`,
+                { data: [...wide.values()], config: { keys } },
+                { rows: d1.distinct, series: d2.distinct },
+                [], `pivoted wide: one row per ${d1.name}, one column per ${d2.name}`);
+        }
+    }
+
+    // --- entity + two temporal fields (interval) -----------------------------
+    if (sig.temporal.length >= 2 && (name || dim)) {
+        const [ta, tb] = sig.temporal.slice().sort((a, b) => a.min - b.min);
+        const label = name || dim;
+        push('Bar.createGantt', 0.85,
+            `two temporal fields (${ta.name}, ${tb.name}) per ${label.name} — intervals on a timeline`,
+            { data: rows.map(r => ({ label: String(r[label.name]), start: r[ta.name], end: r[tb.name] })), config: {} },
+            { rows: n },
+            [], `mapped to { label: ${label.name}, start: ${ta.name}, end: ${tb.name} }`);
+    }
+
+    return out;
+}
+
+function twoPointRows(sortedRows, t, dim, m) {
+    const periods = [...new Set(sortedRows.map(r => String(r[t.name] instanceof Date ? r[t.name].getTime() : r[t.name])))];
+    if (periods.length !== 2) return null;
+    const byGroup = groupBy(sortedRows, dim);
+    const rows = [];
+    for (const [g, rs] of byGroup) {
+        if (rs.length !== 2) continue;
+        rows.push({ name: String(g), before: val(rs[0], m), after: val(rs[1], m) });
+    }
+    return rows.length >= 2 ? rows : null;
+}
+
+function rangeOverlap(a, b) {
+    const lo = Math.max(a.min, b.min), hi = Math.min(a.max, b.max);
+    const span = Math.max(a.max, b.max) - Math.min(a.min, b.min);
+    return span > 0 ? Math.max(0, hi - lo) / span : 0;
+}
+
+function spanRatio(measures) {
+    const spans = measures.map(m => Math.max(Math.abs(m.max), Math.abs(m.min))).filter(s => s > 0);
+    return spans.length ? Math.max(...spans) / Math.min(...spans) : 1;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {Array<object>} rows  Flat row objects (CSV-shaped is fine; numeric
+ *                              strings are coerced during profiling).
+ * @param {{ limit?: number, factory?: object }} [options]
+ *   limit: max candidates returned (default 5).
+ *   factory: the ChartFactory object create() resolves against (injected by
+ *            the export wiring; override only in tests).
+ * @returns {{ fields, signature, candidates }}
+ */
+export function makeSuggest(defaultFactory) {
+    return function suggest(rows, { limit = 5, factory = defaultFactory() } = {}) {
+        if (!Array.isArray(rows) || rows.length === 0) {
+            console.warn('ChartFactory.suggest: rows must be a non-empty array of objects');
+            return { fields: [], signature: null, candidates: [] };
+        }
+        const fields = profileFields(rows);
+        const signature = buildSignature(rows, fields);
+        const candidates = suggestCandidates(rows, signature)
+            .map(c => ({ ...c, score: Math.max(0, Math.min(1, Math.round(c.score * 100) / 100)) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map(c => ({
+                ...c,
+                create(selector, overrides = {}) {
+                    const [family, method] = c.builder.split('.');
+                    return factory[family][method](selector, { data: c.data, ...c.config, ...overrides });
+                },
+            }));
+        if (candidates.length === 0) {
+            console.warn('ChartFactory.suggest: no signature rule matched — see docs/chart-guide.md to choose by hand');
+        }
+        return { fields, signature, candidates };
+    };
+}

package/src/core/example-nav.css

@@ -0,0 +1,62 @@
+/**
+ * Shared Example Navigation Styles
+ *
+ * Usage: Include this CSS alongside example-nav.js
+ *   <link rel="stylesheet" href="../../src/core/example-nav.css">
+ */
+
+/* Navigation bar */
+.example-nav {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    background: var(--color-bg-container);
+    padding: var(--space-3) var(--space-8);
+    border-bottom: 1px solid var(--color-border-light, #e5e5e5);
+    display: flex;
+    gap: var(--space-4);
+    z-index: 100;
+    flex-wrap: wrap;
+}
+
+.example-nav a {
+    font-family: var(--font-family);
+    font-size: var(--font-size-sm);
+    color: var(--color-text-muted);
+    text-decoration: none;
+    padding: var(--space-1) var(--space-2);
+}
+
+.example-nav a:hover {
+    color: var(--color-black);
+}
+
+.example-nav a.active {
+    color: var(--chart-primary);
+    font-weight: var(--font-weight-semibold);
+}
+
+/* Hide nav in modal view */
+/* Modal embeds (?modal=1): neutralize the standalone-page body layout so the
+   chart container is the iframe's entire content — no viewport-height
+   stretching, no gutters, no scrollbar. The parent sizes the iframe from the
+   container height the child reports. */
+body.modal-view {
+    padding: 0 !important;
+    margin: 0 !important;
+    min-height: 0 !important;
+    display: block !important;
+    overflow: hidden;
+    background: var(--color-bg-container, #fff);
+}
+
+body.modal-view .chart-container {
+    width: 100% !important;
+    max-width: none !important;
+    box-shadow: none !important;
+}
+
+body.modal-view .example-nav {
+    display: none;
+}