@lightdash/cli 1.101.0 → 1.103.0

package/dist/vendor/template/.claude/skills/frontend-design/SKILL.md

@@ -27,13 +27,13 @@ Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
 ## Frontend Aesthetics Guidelines
 
 Focus on:
-- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Typography**: In this sandbox, webfonts cannot load — the app iframe's CSP blocks external stylesheets, so a Google Fonts `@import` or injected `<link>` fails at runtime and silently falls back (never emit one). Build characterful typography from the fonts that ARE here: pair personalities from the system font space — `ui-serif`/Georgia display over a plain sans body, `ui-monospace` for data and labels, `ui-rounded` where playful — and push contrast with weight, size jumps, letter-spacing, small-caps, and case. A Georgia-headline-over-mono-labels pairing reads as designed; vary which pairing you choose between generations.
 - **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
 - **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
 - **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
 - **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
 
-NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+NEVER use generic AI-generated aesthetics like a plain default sans-serif stack for everything, cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
 
 Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
 

package/dist/vendor/template/references/d3.md

@@ -10,6 +10,7 @@
 - Example 2 — Sankey (flows between stages)
 - Example 3 — Sunburst (hierarchical part-of-whole)
 - Example 4 — Word cloud (term frequency)
+- Example 5 — Geo choropleth & globe (maps from GeoJSON)
 - Common D3 mistakes
 
 The template ships with `d3`, `d3-sankey`, and `d3-cloud` pre-installed. Sunburst, treemap, pack, icicle, force, geo, hexbin, and chord all use d3 core (`d3.hierarchy`, `d3.partition`, `d3.tree`, `d3.forceSimulation`, etc.) — no extra packages required.
@@ -528,6 +529,201 @@ export function FeedbackWordCloud() {
 - Cap input rows (`.limit(80)`-ish). The layout is `O(n²)` in placement attempts; a 500-word cloud will hang the iframe for several seconds.
 - Don't rotate to arbitrary angles. Stick to `0` and `90` (or `0`, `-30`, `30`). Mixed-angle clouds look chaotic and labels become unreadable.
 
+## Example 5 — Geo choropleth & globe (maps from GeoJSON)
+
+Maps in data apps are SVG projections drawn with `d3-geo` (in d3 core). There are no tile basemaps — the iframe CSP blocks tile servers and external stylesheets — and that's fine: `d3.geoPath` renders crisp vector maps without them. Shapes come as **GeoJSON through a linked external connection**: the prompt lists it as a file under `/tmp/external-data/{alias}.json` — read that file for the alias, origin, and exact path, and see `/app/references/external-apis.md` for the `externalFetch` contract. Use plain GeoJSON sources only — TopoJSON needs `topojson-client`, which is **not installed**.
+
+The pattern: fetch the FeatureCollection once via `externalFetch`, run the metric query with `useLightdash`, join rows onto features by a stable key, and paint one `<path>` per feature.
+
+```tsx
+import { useEffect, useMemo, useRef, useState } from 'react';
+import * as d3 from 'd3';
+import { Loader2 } from 'lucide-react';
+import { query, useLightdash, useLightdashClient } from '@lightdash/query-sdk';
+import { useGlobalFilters } from '@/lib/filters';
+import { CHART_COLORS } from '@/lib/theme';
+
+const EXPLORE = 'orders';
+const COUNTRY_FIELD = 'customer_country_code'; // adjust: must return ISO-3 codes
+const GEO_ALIAS = 'world_geojson';             // adjust: the linked connection's alias
+const GEO_PATH =
+    '/gh/nvkelso/natural-earth-vector/geojson/ne_110m_admin_0_countries.geojson';
+
+type Feature = GeoJSON.Feature<GeoJSON.Geometry, Record<string, unknown>>;
+
+const baseQuery = query(EXPLORE)
+    .label('Revenue by country (choropleth)')
+    .dimensions([COUNTRY_FIELD])
+    .metrics(['total_revenue'])
+    .limit(500);
+
+export function WorldChoropleth() {
+    const client = useLightdashClient();
+    const { filtersFor, addFilter } = useGlobalFilters();
+    const q = useMemo(
+        () => baseQuery.filters(filtersFor(EXPLORE)),
+        [filtersFor],
+    );
+    const { data, loading } = useLightdash(q);
+
+    const [geo, setGeo] = useState<GeoJSON.FeatureCollection | null>(null);
+    const [geoError, setGeoError] = useState<string | null>(null);
+    const svgRef = useRef<SVGSVGElement | null>(null);
+
+    // Fetch shapes once. externalFetch parses JSON — res.body IS the FeatureCollection.
+    useEffect(() => {
+        let cancelled = false;
+        client
+            .externalFetch(GEO_ALIAS, { method: 'GET', path: GEO_PATH })
+            .then((res) => {
+                if (!cancelled) setGeo(res.body as GeoJSON.FeatureCollection);
+            })
+            .catch((err) => {
+                if (!cancelled) setGeoError(err.message);
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [client]);
+
+    useEffect(() => {
+        if (!svgRef.current || !geo || !data) return;
+        const svg = d3.select(svgRef.current);
+        svg.selectAll('*').remove();
+
+        const width = 720;
+        const height = 400;
+        svg.attr('viewBox', `0 0 ${width} ${height}`);
+
+        // Stable ISO-3 key per feature. Natural Earth's ISO_A3 is the
+        // placeholder '-99' (a truthy string!) for France, Norway and others —
+        // `p.ISO_A3 || p.ADM0_A3` returns '-99' for them. ADM0_A3 comes FIRST.
+        const countryKey = (f: Feature) =>
+            String(f.properties.ADM0_A3 ?? f.properties.ISO_A3_EH);
+
+        const byCountry = new Map(
+            data.map((d) => [String(d[COUNTRY_FIELD]), Number(d.total_revenue)]),
+        );
+        const valueFor = (f: Feature) => byCountry.get(countryKey(f)) ?? null;
+
+        const max = d3.max(data, (d) => Number(d.total_revenue)) ?? 1;
+        const opacity = d3.scaleSqrt().domain([0, max]).range([0.15, 1]);
+
+        const projection = d3.geoNaturalEarth1().fitSize([width, height], geo);
+        const path = d3.geoPath(projection);
+
+        svg.append('g')
+            .selectAll('path')
+            .data(geo.features as Feature[])
+            .join('path')
+            .attr('d', path)
+            .attr('fill', CHART_COLORS[0])
+            .attr('fill-opacity', (f) => {
+                const v = valueFor(f);
+                return v == null ? 0.06 : opacity(v); // near-invisible = no data
+            })
+            .attr('stroke', 'currentColor')
+            .attr('stroke-opacity', 0.2)
+            .attr('stroke-width', 0.5)
+            .style('cursor', 'pointer')
+            .on('click', (_event, f) => {
+                addFilter({
+                    field: COUNTRY_FIELD,
+                    operator: 'equals',
+                    value: countryKey(f),
+                    explore: EXPLORE,
+                });
+            })
+            .append('title')
+            .text((f) => String(f.properties.NAME));
+    }, [geo, data, addFilter]);
+
+    if (geoError) {
+        return (
+            <div className="flex items-center justify-center h-[400px] text-sm text-muted-foreground">
+                Could not load map shapes: {geoError}
+            </div>
+        );
+    }
+    if (loading || !geo) {
+        return (
+            <div className="flex items-center justify-center h-[400px]">
+                <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+            </div>
+        );
+    }
+    return <svg ref={svgRef} className="w-full h-auto" />;
+}
+```
+
+**Globe variant.** Swap the projection for `d3.geoOrthographic()` and add drag-to-rotate. Tag every projected path with a shared class so one redraw updates them all, and always cancel the animation frame on cleanup:
+
+```tsx
+const projection = d3
+    .geoOrthographic()
+    .scale(180)
+    .translate([width / 2, height / 2])
+    .clipAngle(90);
+const path = d3.geoPath(projection);
+
+// Ocean + countries all get class 'geo' so redraws hit everything projected
+svg.append('path')
+    .datum({ type: 'Sphere' })
+    .attr('class', 'geo')
+    .attr('d', path)
+    .attr('fill', 'currentColor')
+    .attr('fill-opacity', 0.05);
+// ... country paths as above, plus .attr('class', 'geo') ...
+
+const redraw = () => svg.selectAll<SVGPathElement, unknown>('.geo').attr('d', path);
+
+svg.call(
+    d3.drag<SVGSVGElement, unknown>().on('drag', (event) => {
+        const [lambda, phi, gamma] = projection.rotate();
+        projection.rotate([
+            lambda + event.dx * 0.3,
+            Math.max(-70, Math.min(70, phi - event.dy * 0.3)),
+            gamma,
+        ]);
+        redraw();
+    }),
+);
+
+// Optional auto-rotation — MUST be cancelled in the effect cleanup
+let raf = 0;
+const spin = () => {
+    const [lambda, phi, gamma] = projection.rotate();
+    projection.rotate([lambda + 0.1, phi, gamma]);
+    redraw();
+    raf = requestAnimationFrame(spin);
+};
+raf = requestAnimationFrame(spin);
+return () => cancelAnimationFrame(raf);
+```
+
+**Region focus.** To map one region, filter the features and fit the projection to the subset:
+
+```tsx
+const europe = {
+    type: 'FeatureCollection' as const,
+    features: geo.features.filter((f) => f.properties.CONTINENT === 'Europe'),
+};
+const projection = d3.geoMercator().fitExtent(
+    [[16, 16], [width - 16, height - 16]],
+    europe,
+);
+```
+
+**Geo-specific notes:**
+- **Join on `ADM0_A3`, never `ISO_A3` — and never `p.ISO_A3 || p.ADM0_A3`.** Natural Earth's `ISO_A3` is the placeholder `'-99'` for France, Norway, N. Cyprus, Somaliland, and Kosovo, and `'-99'` is truthy, so an ISO_A3-first fallback chain silently returns it. Use the `countryKey` helper above. If the query dimension returns ISO alpha-2 (`FR`), map it to alpha-3 before joining.
+- **GeoJSON only.** `topojson-client` is not installed — request `.geojson` sources through the connection; never try to decode TopoJSON by hand.
+- **The choropleth ramp is opacity on `CHART_COLORS[0]`**, not a hand-picked palette. Use `scaleSqrt` (or `scaleSequentialLog` for heavy-tailed metrics like population/GDP). Give no-data features near-zero opacity rather than a special color.
+- **System fonts only.** Loading Google Fonts (or any external stylesheet) is CSP-blocked — it fails at the console and falls back anyway. Don't emit `<link>` or `@import` for fonts.
+- **Rotation cleanup is mandatory.** An un-cancelled `requestAnimationFrame` loop keeps mutating a detached SVG after refetch/unmount. Return `() => cancelAnimationFrame(raf)` from the effect.
+- **Redraw by class, not rebuild.** Drag/spin only changes the projection — update with `selectAll('.geo').attr('d', path)`. Rebuilding the DOM per frame will not hold 60fps with 177 country paths.
+- **Overlays don't intercept clicks.** Anything painted above the countries (graticule, atmosphere gradient, sphere outline) needs `.attr('pointer-events', 'none')` or country click-to-filter breaks.
+- The 1:110m world file (~0.8 MB, 177 features) is the right resolution for a world view; only reach for 1:50m when zoomed into a region, and expect the admin to raise the connection's response size for it.
+
 ## Common D3 mistakes
 
 | Mistake | Fix |
@@ -543,3 +739,6 @@ export function FeedbackWordCloud() {
 | Word cloud: painting synchronously | `d3-cloud` is async — paint inside `.on('end', ...)` only. Return `() => layout.stop()` from the effect for cleanup. |
 | Word cloud: not capping rows | `O(n²)` layout. Cap with `.limit(80)`-ish on the query. |
 | Measuring container width with `getBoundingClientRect` | Set `viewBox` once and let CSS scale via `className="w-full h-auto"`. |
+| Geo: joining rows on `ISO_A3` (or `p.ISO_A3 \|\| p.ADM0_A3` fallback chains) | `ISO_A3` is the truthy placeholder `'-99'` for France, Norway and others — `ADM0_A3` comes first: `p.ADM0_A3 ?? p.ISO_A3_EH`. |
+| Geo: fetching shapes with raw `fetch()` or a tile server | CSP blocks both. GeoJSON comes through `externalFetch` on a linked connection; maps are SVG projections, no tiles. |
+| Geo: auto-rotate loop without cleanup | Return `() => cancelAnimationFrame(raf)` from the effect or the loop outlives the chart. |

package/dist/vendor/template/skill.md

@@ -695,6 +695,8 @@ For any external HTTP API call, read `/app/references/external-apis.md` and use
 
 **Use the `frontend-design` skill before writing any UI code.** It drives the aesthetic direction — pick a distinctive look for *this* app rather than defaulting to generic shadcn-on-dark-mode. This guide does not prescribe layout, typography, color, or composition; that's `frontend-design`'s job.
 
+One environment constraint overrides `frontend-design`'s typography advice: **webfonts cannot load in the app iframe.** The runtime CSP blocks external stylesheets — a Google Fonts `@import` or `<link>` fails at the console and silently falls back, so it only adds noise. Never emit one. Distinctive typography here comes from expressive *system-stack* pairings (`ui-serif`/Georgia display over a sans body, `ui-monospace` for data, small-caps, letter-spacing, weight contrast) — a Georgia-headline-over-monospace-labels pairing reads as designed, not generic.
+
 Express that direction **through the theme tokens, in both modes**. "Distinctive" is never a licence to pin one colour scheme: the viewer's Lightdash decides light or dark, and an app that ignores it reads as broken for half its audience. If a look only works on a dark background, it is not a look you can ship — rebuild it so the same design resolves correctly in both.
 
 Lightdash-specific constraints that apply on top of `frontend-design`'s direction:
@@ -1228,7 +1230,7 @@ Only when the user asks for adjustable panel sizing (or two sibling areas genuin
 
 If a Recharts component covers it, **use Recharts** — even if a D3 version would be marginally prettier. The cost of D3 is more code, more chances for memory leaks, and harder integration with the action menu.
 
-When you do need D3, **read `/app/references/d3.md` first.** It contains the React-19 + D3 integration pattern, four worked examples (bar, sankey, sunburst, word cloud), the cross-cutting rules (`CHART_COLORS`, `filtersFor`, action menu, no-cross-refetch animation), and a common-mistakes table. Don't try to wire D3 from memory — load the reference.
+When you do need D3, **read `/app/references/d3.md` first.** It contains the React-19 + D3 integration pattern, five worked examples (bar, sankey, sunburst, word cloud, geo choropleth/globe), the cross-cutting rules (`CHART_COLORS`, `filtersFor`, action menu, no-cross-refetch animation), and a common-mistakes table. Don't try to wire D3 from memory — load the reference.
 
 ## `drillDown()` Reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "1.101.0",
+  "version": "1.103.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,8 @@
     "unique-names-generator": "4.7.1",
     "uuid": "11.1.1",
     "yaml": "2.8.3",
-    "@lightdash/common": "1.101.0",
-    "@lightdash/warehouses": "1.101.0"
+    "@lightdash/common": "1.103.0",
+    "@lightdash/warehouses": "1.103.0"
   },
   "devDependencies": {
     "@types/inquirer": "8.2.4",