@keyfunc/keybricks-ds 1.0.0

package/components/charts/Surface3D.vue

@@ -0,0 +1,63 @@
+<script setup>
+import { ref, computed } from 'vue'
+import { fmtNum, niceTicks } from './chart-geometry.js'
+import { makeProj, facePath, faceDepth, shade, lightOf, heatColor } from './chart-3d.js'
+// 3D surface z = f(x,y); drag to orbit. Cells shade on the heat ramp by height.
+const props = defineProps({ values:{type:Array,default:()=>[]}, width:{type:Number,default:420}, height:{type:Number,default:300}, yaw:{type:Number,default:38}, pitch:{type:Number,default:32}, zScale:{type:Number,default:0.55}, wire:{type:Boolean,default:true}, xLabel:{type:String,default:'x'}, yLabel:{type:String,default:'y'}, interactive:{type:Boolean,default:true}, valueFormat:{type:Function,default:fmtNum}, style:Object })
+const rot = ref({ yaw: props.yaw, pitch: props.pitch })
+const hover = ref(null)
+// Drag state on the DOM node: a closure var is reset by re-render mid-drag.
+function down(e){ e.currentTarget.__kbDrag = { x:e.clientX, y:e.clientY, ...rot.value }; e.currentTarget.setPointerCapture && e.currentTarget.setPointerCapture(e.pointerId) }
+function move(e){ const s = e.currentTarget.__kbDrag; if(!s) return; rot.value = { yaw: s.yaw+(e.clientX-s.x)*0.45, pitch: Math.max(8, Math.min(80, s.pitch+(e.clientY-s.y)*0.35)) } }
+function up(e){ e.currentTarget.__kbDrag = null }
+const g = computed(() => {
+  const rows = props.values.length, cols = props.values[0] ? props.values[0].length : 0
+  let lo = Infinity, hi = -Infinity
+  props.values.forEach(r=>r.forEach(v=>{ if(v<lo) lo=v; if(v>hi) hi=v }))
+  const span = hi-lo || 1
+  const scale = Math.min(props.width, props.height)*0.42
+  const P = makeProj(props.width/2, props.height/2 + props.height*0.05, scale, rot.value.yaw, rot.value.pitch)
+  const pt = (r,c) => P((c/(cols-1))-0.5, (((props.values[r][c]-lo)/span)-0.5)*props.zScale*2, (r/(rows-1))-0.5)
+  const quads = []
+  for (let r=0;r<rows-1;r++) for (let c=0;c<cols-1;c++) {
+    const pts = [pt(r,c), pt(r,c+1), pt(r+1,c+1), pt(r+1,c)]
+    const avg = (props.values[r][c]+props.values[r][c+1]+props.values[r+1][c]+props.values[r+1][c+1])/4
+    quads.push({ d: facePath(pts), t:(avg-lo)/span, avg, r, c, depth: faceDepth(pts), light: lightOf(pts[0],pts[1],pts[3]),
+      cx: pts.reduce((s,p)=>s+p.x,0)/4, cy: pts.reduce((s,p)=>s+p.y,0)/4 })
+  }
+  quads.sort((a,b)=>b.depth-a.depth)
+  const yB = -props.zScale-0.06
+  const base = [P(-0.5,yB,-0.5), P(0.5,yB,-0.5), P(0.5,yB,0.5), P(-0.5,yB,0.5)]
+  const corner = P(-0.5,yB,0.5)
+  const axes3 = [
+    { a:corner, b:P(0.5,yB,0.5), label:props.xLabel, lp:P(0,yB-0.16,0.5), anchor:'middle' },
+    { a:corner, b:P(-0.5,yB,-0.5), label:props.yLabel, lp:P(-0.62,yB-0.12,0), anchor:'end' },
+    { a:corner, b:P(-0.5,props.zScale,0.5) },
+  ]
+  const zt = niceTicks(lo,hi,3)
+  const zTicks = zt.ticks.filter(t=>t>=lo&&t<=hi).map(t=>({ p:P(-0.5, ((t-lo)/span-0.5)*props.zScale*2, 0.5), v:props.valueFormat(t) }))
+  return { quads, basePath: facePath(base), axes3, zTicks }
+})
+function fill(q){ return shade(heatColor(q.t), Math.max(-0.35, Math.min(0.3, q.light*0.4)) + (hover.value===q ? 0.18 : 0)) }
+</script>
+<template>
+  <div :style="{position:'relative',display:'inline-block',lineHeight:0,...style}">
+    <svg :width="width" :height="height" @pointerdown="down" @pointermove="move" @pointerup="up" @pointerleave="up"
+      role="img" :style="{cursor:interactive?'grab':'default',touchAction:'none'}">
+      <path :d="g.basePath" fill="var(--bg-inset)" stroke="var(--chart-axis)" stroke-width="1"/>
+      <line v-for="(ax,i) in g.axes3" :key="'ae'+i" :x1="ax.a.x" :y1="ax.a.y" :x2="ax.b.x" :y2="ax.b.y" stroke="var(--chart-guide)" stroke-width="1"/>
+      <text v-for="(ax,i) in g.axes3.filter(a=>a.label)" :key="'al'+i" :x="ax.lp.x" :y="ax.lp.y+3" :text-anchor="ax.anchor"
+        style="font-family:var(--font-sans);font-size:10px;fill:var(--text-secondary)">{{ ax.label }}</text>
+      <g v-for="(t,i) in g.zTicks" :key="'zt'+i">
+        <line :x1="t.p.x-4" :y1="t.p.y" :x2="t.p.x" :y2="t.p.y" stroke="var(--chart-guide)" stroke-width="1"/>
+        <text :x="t.p.x-7" :y="t.p.y+3" text-anchor="end" style="font-family:var(--font-mono);font-size:9px;fill:var(--chart-label)">{{ t.v }}</text>
+      </g>
+      <path v-for="(q,i) in g.quads" :key="i" :d="q.d" :fill="fill(q)" :stroke="wire?'var(--bg-surface)':'none'" stroke-width="0.5"
+        @mouseenter="interactive && (hover=q)" @mouseleave="interactive && (hover=null)"/>
+    </svg>
+    <div v-if="hover && interactive" :style="{position:'absolute',left:hover.cx+'px',top:hover.cy+'px',transform:hover.cx>width*0.6?'translate(calc(-100% - 10px),-50%)':'translate(10px,-50%)',pointerEvents:'none',zIndex:5,background:'var(--bg-surface)',border:'1px solid var(--border-card)',borderRadius:'var(--radius-md)',boxShadow:'var(--shadow-menu)',padding:'7px 10px',lineHeight:'normal',whiteSpace:'nowrap'}">
+      <div style="font-family:var(--font-sans);font-size:var(--text-2xs);color:var(--text-muted);padding-bottom:3px">row {{ hover.r+1 }} · col {{ hover.c+1 }}</div>
+      <div style="font-family:var(--font-mono);font-size:var(--text-xs);color:var(--text-heading)">{{ valueFormat(hover.avg) }}</div>
+    </div>
+  </div>
+</template>

package/components/charts/TreemapChart.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+export interface TreemapItem { label: string; value: number; color?: string; }
+/** Squarified treemap; labels render only where they fit, hover dims the rest. */
+export interface TreemapChartProps {
+  items?: TreemapItem[];
+  width?: number; height?: number;
+  valueFormat?: (v: number) => string;
+  interactive?: boolean;
+  style?: React.CSSProperties;
+}
+export declare function TreemapChart(props: TreemapChartProps): JSX.Element;

package/components/charts/TreemapChart.jsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { fmtNum, treemap, seriesColor } from "./chart-geometry.js";
+import { ChartTooltip, wrapStyle } from "./ChartKit.jsx";
+
+/**
+ * Squarified treemap — composition at a glance (cost base, storage by dataset).
+ * items: [{label, value, color?}]. Labels render only where they fit.
+ */
+export function TreemapChart({ items = [], width = 560, height = 260, valueFormat = fmtNum, interactive = true, style }) {
+  const [hover, setHover] = React.useState(null);
+  const cells = treemap(items, width, height);
+  const total = items.reduce((s, i) => s + i.value, 0) || 1;
+  const colorOf = (it) => it.color || seriesColor(items.indexOf(it));
+  const h = hover != null ? cells[hover] : null;
+  return (
+    <div style={{ ...wrapStyle, ...style }}>
+      <svg width={width} height={height} role="img">
+        {cells.map((c, i) => (
+          <g key={i} onMouseEnter={interactive ? () => setHover(i) : undefined} onMouseLeave={interactive ? () => setHover(null) : undefined} style={{ cursor: interactive ? "default" : undefined }}>
+            <rect x={c.x + 1} y={c.y + 1} width={Math.max(1, c.w - 2)} height={Math.max(1, c.h - 2)} rx="3" fill={colorOf(c.item)}
+              opacity={hover == null ? 0.85 : hover === i ? 1 : 0.35} style={{ transition: "opacity var(--dur-fast) var(--ease-out)" }} />
+            {c.w > 74 && c.h > 34 ? <>
+              <text x={c.x + 9} y={c.y + 18} style={{ fontFamily: "var(--font-sans)", fontSize: 11, fill: "var(--on-accent)" }}>{c.item.label}</text>
+              <text x={c.x + 9} y={c.y + 32} style={{ fontFamily: "var(--font-mono)", fontSize: 10, fill: "var(--on-accent)", opacity: 0.85 }}>{valueFormat(c.item.value)}</text>
+            </> : null}
+          </g>
+        ))}
+      </svg>
+      {h && interactive ? (
+        <ChartTooltip x={h.x + h.w / 2} y={h.y + h.h / 2} flip={h.x + h.w / 2 > width * 0.62} title={h.item.label}
+          rows={[{ label: "value", value: valueFormat(h.item.value) }, { label: "share", value: ((h.item.value / total) * 100).toFixed(1) + "%" }]} />
+      ) : null}
+    </div>
+  );
+}

package/components/charts/TreemapChart.vue

@@ -0,0 +1,27 @@
+<script setup>
+import { ref, computed } from 'vue'
+import { fmtNum, treemap, SERIES } from './chart-geometry.js'
+// Squarified treemap; labels render only where they fit, hover dims the rest.
+const props = defineProps({ items:{type:Array,default:()=>[]}, width:{type:Number,default:560}, height:{type:Number,default:260}, valueFormat:{type:Function,default:fmtNum}, interactive:{type:Boolean,default:true}, style:Object })
+const hover = ref(null)
+const cells = computed(() => treemap(props.items, props.width, props.height).map(c => ({ ...c, color: c.item.color || SERIES[props.items.indexOf(c.item)%SERIES.length] })))
+const total = computed(() => props.items.reduce((s,i)=>s+i.value,0)||1)
+</script>
+<template>
+  <div :style="{position:'relative',display:'inline-block',lineHeight:0,...style}">
+    <svg :width="width" :height="height" role="img">
+      <g v-for="(c,i) in cells" :key="i" @mouseenter="interactive && (hover=i)" @mouseleave="interactive && (hover=null)">
+        <rect :x="c.x+1" :y="c.y+1" :width="Math.max(1,c.w-2)" :height="Math.max(1,c.h-2)" rx="3" :fill="c.color"
+          :opacity="hover==null?.85:hover===i?1:.35" style="transition:opacity var(--dur-fast) var(--ease-out)"/>
+        <template v-if="c.w>74 && c.h>34">
+          <text :x="c.x+9" :y="c.y+18" style="font-family:var(--font-sans);font-size:11px;fill:var(--on-accent)">{{ c.item.label }}</text>
+          <text :x="c.x+9" :y="c.y+32" style="font-family:var(--font-mono);font-size:10px;fill:var(--on-accent);opacity:.85">{{ valueFormat(c.item.value) }}</text>
+        </template>
+      </g>
+    </svg>
+    <div v-if="hover!=null && interactive" :style="{position:'absolute',left:(cells[hover].x+cells[hover].w/2)+'px',top:(cells[hover].y+cells[hover].h/2)+'px',transform:(cells[hover].x+cells[hover].w/2)>width*0.62?'translate(calc(-100% - 10px),-50%)':'translate(10px,-50%)',pointerEvents:'none',zIndex:5,background:'var(--bg-surface)',border:'1px solid var(--border-card)',borderRadius:'var(--radius-md)',boxShadow:'var(--shadow-menu)',padding:'7px 10px',lineHeight:'normal'}">
+      <div style="font-family:var(--font-sans);font-size:var(--text-2xs);color:var(--text-muted);white-space:nowrap;padding-bottom:2px">{{ cells[hover].item.label }}</div>
+      <div style="font-family:var(--font-mono);font-size:var(--text-xs);color:var(--text-heading);white-space:nowrap">{{ valueFormat(cells[hover].item.value) }} · {{ ((cells[hover].item.value/total)*100).toFixed(1) }}%</div>
+    </div>
+  </div>
+</template>

package/components/charts/WaterfallChart.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+export interface WaterfallStep { label: string; /** Signed delta; ignored when total */ value?: number; /** Re-baseline bar showing the running sum (subtotal / result) */ total?: boolean; }
+/** Finance bridge: green gains, red losses, neutral totals, dashed running-sum connectors. */
+export interface WaterfallChartProps {
+  steps?: WaterfallStep[];
+  width?: number; height?: number;
+  axes?: boolean; showValues?: boolean; interactive?: boolean;
+  valueFormat?: (v: number) => string;
+  style?: React.CSSProperties;
+}
+export declare function WaterfallChart(props: WaterfallChartProps): JSX.Element;

package/components/charts/WaterfallChart.jsx

@@ -0,0 +1,59 @@
+import React from "react";
+import { fmtNum, waterfall, niceTicks, scaleLin } from "./chart-geometry.js";
+import { ChartTooltip, PlotGrid, wrapStyle } from "./ChartKit.jsx";
+
+/**
+ * Waterfall bridge — plan → actual, revenue → net income. steps: [{label, value}] plus
+ * {label, total:true} rows that re-baseline (subtotals/result). Positive --chart-pos,
+ * negative --chart-neg, totals --chart-total; dashed connectors carry the running sum.
+ * Hovering a bar dims the rest and reports the delta and the running total.
+ */
+export function WaterfallChart({ steps = [], width = 560, height = 260, axes = true, valueFormat = fmtNum, showValues = true, interactive = true, style }) {
+  const [hover, setHover] = React.useState(null);
+  const bars = waterfall(steps);
+  const pad = { l: axes ? 44 : 4, r: 8, t: showValues ? 22 : 10, b: 40 };
+  const [lo0, hi0] = [Math.min(0, ...bars.map((b) => b.y0)), Math.max(0, ...bars.map((b) => b.y1))];
+  const { ticks, lo, hi } = niceTicks(lo0, hi0, 4);
+  const sy = scaleLin(lo, hi, height - pad.b, pad.t);
+  const slot = (width - pad.l - pad.r) / bars.length;
+  const bw = Math.min(slot * 0.58, 40);
+  const fill = { pos: "var(--chart-pos)", neg: "var(--chart-neg)", total: "var(--chart-total)" };
+  const move = (e) => {
+    if (!interactive) return;
+    const r = e.currentTarget.getBoundingClientRect();
+    const i = Math.floor((e.clientX - r.left - pad.l) / slot);
+    setHover(i >= 0 && i < bars.length ? i : null);
+  };
+  const h = hover != null ? bars[hover] : null;
+  return (
+    <div style={{ ...wrapStyle, ...style }}>
+      <svg width={width} height={height} onMouseMove={move} onMouseLeave={() => setHover(null)} role="img">
+        {axes ? <PlotGrid w={width} h={height} pad={pad} ticks={ticks} sy={sy} xLabels={[]} sxLabel={() => 0} yFormat={valueFormat} /> : null}
+        {hover != null ? <rect x={pad.l + slot * hover} y={pad.t} width={slot} height={height - pad.t - pad.b} fill="var(--bg-hover)" /> : null}
+        {bars.map((b, i) => {
+          const x = pad.l + slot * i + slot / 2;
+          const y = sy(b.y1), hgt = Math.max(1.5, sy(b.y0) - y);
+          const runEnd = b.kind === "total" ? b.y1 : b.to;
+          return (
+            <g key={i} opacity={hover == null || hover === i ? 1 : 0.45} style={{ transition: "opacity var(--dur-fast) var(--ease-out)" }}>
+              <rect x={x - bw / 2} y={y} width={bw} height={hgt} rx="2" fill={fill[b.kind]} />
+              {i < bars.length - 1 ? <line x1={x + bw / 2} x2={pad.l + slot * (i + 1) + slot / 2 - bw / 2} y1={sy(runEnd)} y2={sy(runEnd)} stroke="var(--chart-guide)" strokeWidth="1" strokeDasharray="2 3" /> : null}
+              {showValues ? <text x={x} y={y - 5} textAnchor="middle" style={{ fontFamily: "var(--font-mono)", fontSize: 10, fill: b.kind === "neg" ? "var(--chart-neg)" : "var(--text-heading)" }}>{(b.kind === "pos" ? "+" : "") + valueFormat(b.value)}</text> : null}
+              <text x={x} y={height - pad.b + 15} textAnchor="middle" style={{ fontFamily: "var(--font-sans)", fontSize: 10, fill: "var(--chart-label)" }}>
+                {String(b.label).split("\n").map((ln, li) => <tspan key={li} x={x} dy={li ? 11 : 0}>{ln}</tspan>)}
+              </text>
+            </g>
+          );
+        })}
+      </svg>
+      {h && interactive ? (
+        <ChartTooltip x={pad.l + slot * hover + slot / 2} y={height / 2 - 10} flip={pad.l + slot * hover > width * 0.62}
+          title={String(h.label).replace("\n", " ")}
+          rows={h.kind === "total"
+            ? [{ label: "running total", value: valueFormat(h.value), color: fill.total }]
+            : [{ label: h.kind === "pos" ? "gain" : "loss", value: (h.kind === "pos" ? "+" : "") + valueFormat(h.value), color: fill[h.kind] },
+               { label: "running total", value: valueFormat(h.to) }]} />
+      ) : null}
+    </div>
+  );
+}

package/components/charts/WaterfallChart.vue

@@ -0,0 +1,46 @@
+<script setup>
+import { computed, ref } from 'vue'
+import { fmtNum, waterfall, niceTicks, scaleLin } from './chart-geometry.js'
+// Finance bridge: green gains, red losses, neutral totals, dashed running-sum connectors.
+const props = defineProps({ steps:{type:Array,default:()=>[]}, width:{type:Number,default:560}, height:{type:Number,default:260}, axes:{type:Boolean,default:true}, showValues:{type:Boolean,default:true}, valueFormat:{type:Function,default:fmtNum}, interactive:{type:Boolean,default:true}, style:Object })
+const hover = ref(null)
+function move(e){ if(!props.interactive) return; const r=e.currentTarget.getBoundingClientRect(); const slot=(props.width-g.value.pad.l-g.value.pad.r)/g.value.out.length; const i=Math.floor((e.clientX-r.left-g.value.pad.l)/slot); hover.value = i>=0 && i<g.value.out.length ? i : null }
+const FILL = { pos:'var(--chart-pos)', neg:'var(--chart-neg)', total:'var(--chart-total)' }
+const g = computed(() => {
+  const bars = waterfall(props.steps)
+  const pad = { l: props.axes?44:4, r:8, t: props.showValues?22:10, b:40 }
+  const { ticks, lo, hi } = niceTicks(Math.min(0,...bars.map(b=>b.y0)), Math.max(0,...bars.map(b=>b.y1)), 4)
+  const sy = scaleLin(lo, hi, props.height-pad.b, pad.t)
+  const slot = (props.width-pad.l-pad.r)/bars.length
+  const bw = Math.min(slot*0.58, 40)
+  return { pad, ticks, sy, out: bars.map((b,i)=>{
+    const x = pad.l + slot*i + slot/2
+    return { ...b, x, bw, y: sy(b.y1), h: Math.max(1.5, sy(b.y0)-sy(b.y1)), fill: FILL[b.kind],
+      run: sy(b.kind==='total'?b.y1:b.to), nextX: pad.l + slot*(i+1) + slot/2 - bw/2, last: i===bars.length-1,
+      lines: String(b.label).split('\\n') } }) }
+})
+</script>
+<template>
+  <div :style="{position:'relative',display:'inline-block',lineHeight:0,...style}">
+    <svg :width="width" :height="height" @mousemove="move" @mouseleave="hover=null" role="img">
+      <template v-if="axes">
+        <g v-for="t in g.ticks" :key="t">
+          <line :x1="g.pad.l" :x2="width-g.pad.r" :y1="g.sy(t)" :y2="g.sy(t)" :stroke="t===0?'var(--chart-axis)':'var(--chart-grid)'" stroke-width="1"/>
+          <text :x="g.pad.l-8" :y="g.sy(t)+3" text-anchor="end" style="font-family:var(--font-mono);font-size:10px;fill:var(--chart-label)">{{ valueFormat(t) }}</text>
+        </g>
+      </template>
+      <g v-for="(b,i) in g.out" :key="i" :opacity="hover==null||hover===i?1:0.45" style="transition:opacity var(--dur-fast) var(--ease-out)">
+        <rect :x="b.x-b.bw/2" :y="b.y" :width="b.bw" :height="b.h" rx="2" :fill="b.fill"/>
+        <line v-if="!b.last" :x1="b.x+b.bw/2" :x2="b.nextX" :y1="b.run" :y2="b.run" stroke="var(--chart-guide)" stroke-width="1" stroke-dasharray="2 3"/>
+        <text v-if="showValues" :x="b.x" :y="b.y-5" text-anchor="middle" :style="{fontFamily:'var(--font-mono)',fontSize:'10px',fill:b.kind==='neg'?'var(--chart-neg)':'var(--text-heading)'}">{{ (b.kind==='pos'?'+':'')+valueFormat(b.value) }}</text>
+        <text :x="b.x" :y="height-g.pad.b+15" text-anchor="middle" style="font-family:var(--font-sans);font-size:10px;fill:var(--chart-label)">
+          <tspan v-for="(ln,li) in b.lines" :key="li" :x="b.x" :dy="li?11:0">{{ ln }}</tspan>
+        </text>
+      </g>
+    </svg>
+    <div v-if="hover!=null && interactive" :style="{position:'absolute',left:g.out[hover].x+'px',top:(height/2-10)+'px',transform:g.out[hover].x>width*0.62?'translate(calc(-100% - 10px),-50%)':'translate(10px,-50%)',pointerEvents:'none',zIndex:5,background:'var(--bg-surface)',border:'1px solid var(--border-card)',borderRadius:'var(--radius-md)',boxShadow:'var(--shadow-menu)',padding:'7px 10px',lineHeight:'normal',whiteSpace:'nowrap'}">
+      <div style="font-family:var(--font-sans);font-size:var(--text-2xs);color:var(--text-muted);padding-bottom:3px">{{ String(g.out[hover].label).replace('\n',' ') }}</div>
+      <div style="font-family:var(--font-mono);font-size:var(--text-xs);color:var(--text-heading)">{{ g.out[hover].kind==='total' ? valueFormat(g.out[hover].value) : ((g.out[hover].kind==='pos'?'+':'')+valueFormat(g.out[hover].value)+' → '+valueFormat(g.out[hover].to)) }}</div>
+    </div>
+  </div>
+</template>

package/components/charts/WorldMap.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+/**
+ * World choropleth on real Natural Earth geometry (world-atlas 110m) projected with d3-geo.
+ * The host page MUST load the pinned d3 + topojson-client tags; the component reads them
+ * from window and fetches the pinned topology itself.
+ */
+export interface WorldMapProps {
+  /** Country name → value, e.g. { "United States": 6400, Germany: 5200 } */
+  values?: Record<string, number>;
+  width?: number; height?: number;
+  projection?: "naturalEarth" | "mercator" | "equalEarth";
+  /** "blue" sequential ramp, or "diverging" for signed values */
+  scale?: "blue" | "diverging";
+  valueFormat?: (v: number) => string;
+  legend?: boolean;
+  /** Unit shown in the legend and tooltip row label */ unit?: string;
+  interactive?: boolean;
+  onSelect?: (country: string, value: number | undefined) => void;
+  style?: React.CSSProperties;
+}
+export declare function WorldMap(props: WorldMapProps): JSX.Element;

package/components/charts/WorldMap.jsx

@@ -0,0 +1,107 @@
+import React from "react";
+import { fmtNum, quantize } from "./chart-geometry.js";
+import { ChartTooltip, wrapStyle } from "./ChartKit.jsx";
+
+const HEAT = ["var(--chart-heat-1)", "var(--chart-heat-2)", "var(--chart-heat-3)", "var(--chart-heat-4)", "var(--chart-heat-5)"];
+const TOPO = "https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-110m.json";
+/* Natural Earth spells several countries formally; accept the everyday name too so
+   callers can write { "United States": 1 } instead of "United States of America". */
+const ALIAS = {
+  "united states": "United States of America", usa: "United States of America", us: "United States of America",
+  uk: "United Kingdom", "great britain": "United Kingdom", britain: "United Kingdom",
+  "south korea": "South Korea", korea: "South Korea", "czech republic": "Czechia",
+  uae: "United Arab Emirates", drc: "Dem. Rep. Congo", "democratic republic of the congo": "Dem. Rep. Congo",
+  "bosnia and herzegovina": "Bosnia and Herz.", "dominican republic": "Dominican Rep.",
+  "central african republic": "Central African Rep.", "south sudan": "S. Sudan", "ivory coast": "Côte d'Ivoire",
+};
+
+/**
+ * World choropleth. Real Natural Earth geometry (world-atlas 110m) projected with d3-geo —
+ * never hand-drawn outlines. `values` maps country name → number ("United States",
+ * "Germany"…); unmatched countries render as empty land. Hover highlights a country and
+ * pins its value; click reports it.
+ *
+ * The host page must load the pinned d3 + topojson-client tags (see the card source);
+ * the component reads them off `window` and fetches the pinned topology itself.
+ */
+export function WorldMap({ values = {}, width = 660, height = 340, projection = "naturalEarth", scale = "blue", valueFormat = fmtNum, legend = true, unit, interactive = true, onSelect, style }) {
+  const [geo, setGeo] = React.useState(null);
+  const [err, setErr] = React.useState(null);
+  const [hover, setHover] = React.useState(null);
+
+  React.useEffect(() => {
+    let dead = false;
+    const d3 = window.d3, topojson = window.topojson;
+    if (!d3 || !topojson) { setErr("d3 + topojson-client are required on the page"); return; }
+    fetch(TOPO).then((r) => r.json()).then((topo) => {
+      if (dead) return;
+      const fc = topojson.feature(topo, topo.objects.countries);
+      setGeo(fc);
+    }).catch(() => !dead && setErr("could not load country geometry"));
+    return () => { dead = true; };
+  }, []);
+
+  const paths = React.useMemo(() => {
+    if (!geo || !window.d3) return null;
+    const d3 = window.d3;
+    const proj = (projection === "mercator" ? d3.geoMercator() : projection === "equalEarth" && d3.geoEqualEarth ? d3.geoEqualEarth() : d3.geoNaturalEarth1())
+      .fitSize([width, height - (legend ? 22 : 0)], geo);
+    const gp = d3.geoPath(proj);
+    return geo.features.map((f) => ({ name: f.properties.name, d: gp(f), c: gp.centroid(f) }));
+  }, [geo, width, height, projection, legend]);
+
+  /* Resolve caller keys to Natural Earth feature names once, so both the scale and every
+     lookup agree on the same key set. */
+  const resolved = React.useMemo(() => {
+    const out = {};
+    Object.keys(values).forEach((k) => {
+      const canon = ALIAS[k.toLowerCase()] || k;
+      out[canon] = values[k];
+    });
+    return out;
+  }, [values]);
+  const nums = Object.values(resolved).filter((v) => typeof v === "number");
+  const bucket = quantize(nums, 5);
+  const lo = Math.min(...nums), hi = Math.max(...nums);
+  const fillOf = (name) => {
+    const v = resolved[name];
+    if (v == null) return "var(--chart-track)";
+    if (scale === "diverging") {
+      const amax = Math.max(Math.abs(lo), Math.abs(hi)) || 1;
+      const a = Math.round((0.18 + Math.min(1, Math.abs(v) / amax) * 0.82) * 100);
+      return "color-mix(in srgb, var(--chart-" + (v >= 0 ? "pos" : "neg") + ") " + a + "%, var(--bg-surface))";
+    }
+    return HEAT[Math.max(0, bucket(v))];
+  };
+
+  if (err) return <div style={{ width, height, display: "flex", alignItems: "center", justifyContent: "center", fontFamily: "var(--font-mono)", fontSize: "var(--text-xs)", color: "var(--text-muted)", background: "var(--bg-inset)", borderRadius: "var(--radius-lg)", ...style }}>{err}</div>;
+  if (!paths) return <div style={{ width, height, display: "flex", alignItems: "center", justifyContent: "center", fontFamily: "var(--font-mono)", fontSize: "var(--text-xs)", color: "var(--text-muted)", ...style }}>loading map…</div>;
+
+  const h = hover != null ? paths[hover] : null;
+  return (
+    <div style={{ ...wrapStyle, ...style }}>
+      <svg width={width} height={height - (legend ? 22 : 0)} role="img">
+        {paths.map((p, i) => (
+          <path key={p.name + i} d={p.d} fill={fillOf(p.name)} stroke="var(--bg-surface)" strokeWidth="0.5"
+            onMouseEnter={interactive ? () => setHover(i) : undefined} onMouseLeave={interactive ? () => setHover(null) : undefined}
+            onClick={onSelect ? () => onSelect(p.name, resolved[p.name]) : undefined}
+            style={{ cursor: onSelect ? "pointer" : "default", outline: "none", opacity: hover == null || hover === i ? 1 : 0.75, transition: "opacity var(--dur-fast) var(--ease-out)" }} />
+        ))}
+        {h ? <path d={h.d} fill="none" stroke="var(--action-primary)" strokeWidth="1.4" pointerEvents="none" /> : null}
+      </svg>
+      {legend ? (
+        <div style={{ display: "flex", alignItems: "center", gap: 6, paddingTop: 6, lineHeight: "normal" }}>
+          <span style={{ fontFamily: "var(--font-mono)", fontSize: 10, color: "var(--chart-label)" }}>{valueFormat(lo)}</span>
+          {(scale === "diverging" ? ["var(--chart-neg)", "color-mix(in srgb, var(--chart-neg) 40%, var(--bg-surface))", "var(--chart-track)", "color-mix(in srgb, var(--chart-pos) 40%, var(--bg-surface))", "var(--chart-pos)"] : HEAT).map((c, i) => (
+            <span key={i} style={{ width: 22, height: 8, borderRadius: 2, background: c }} />
+          ))}
+          <span style={{ fontFamily: "var(--font-mono)", fontSize: 10, color: "var(--chart-label)" }}>{valueFormat(hi)}{unit ? " " + unit : ""}</span>
+        </div>
+      ) : null}
+      {h && interactive ? (
+        <ChartTooltip x={h.c[0]} y={h.c[1]} flip={h.c[0] > width * 0.62} title={h.name}
+          rows={[{ label: unit || "value", value: resolved[h.name] == null ? "no data" : valueFormat(resolved[h.name]), color: resolved[h.name] == null ? undefined : fillOf(h.name) }]} />
+      ) : null}
+    </div>
+  );
+}

package/components/charts/WorldMap.vue

@@ -0,0 +1,73 @@
+<script setup>
+import { ref, computed, onMounted } from 'vue'
+import { fmtNum, quantize } from './chart-geometry.js'
+/**
+ * World choropleth on real Natural Earth geometry (world-atlas 110m) projected with d3-geo.
+ * The host page MUST load the pinned d3 + topojson-client tags; this reads them off window.
+ */
+const HEAT = ['var(--chart-heat-1)','var(--chart-heat-2)','var(--chart-heat-3)','var(--chart-heat-4)','var(--chart-heat-5)']
+const TOPO = 'https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-110m.json'
+const ALIAS = { 'united states':'United States of America', usa:'United States of America', us:'United States of America',
+  uk:'United Kingdom', britain:'United Kingdom', 'great britain':'United Kingdom', 'czech republic':'Czechia',
+  uae:'United Arab Emirates', 'south sudan':'S. Sudan', 'dominican republic':'Dominican Rep.',
+  'bosnia and herzegovina':'Bosnia and Herz.', 'central african republic':'Central African Rep.', 'ivory coast':"Côte d'Ivoire" }
+const props = defineProps({ values:{type:Object,default:()=>({})}, width:{type:Number,default:660}, height:{type:Number,default:340}, projection:{type:String,default:'naturalEarth'}, scale:{type:String,default:'blue'}, valueFormat:{type:Function,default:fmtNum}, legend:{type:Boolean,default:true}, unit:String, interactive:{type:Boolean,default:true}, style:Object })
+const emit = defineEmits(['select'])
+const geo = ref(null); const err = ref(null); const hover = ref(null)
+onMounted(() => {
+  const d3 = window.d3, topojson = window.topojson
+  if (!d3 || !topojson) { err.value = 'd3 + topojson-client are required on the page'; return }
+  fetch(TOPO).then(r=>r.json()).then(topo=>{ geo.value = topojson.feature(topo, topo.objects.countries) })
+    .catch(()=>{ err.value = 'could not load country geometry' })
+})
+const resolved = computed(() => {
+  const out = {}
+  Object.keys(props.values).forEach(k=>{ out[ALIAS[k.toLowerCase()]||k] = props.values[k] })
+  return out
+})
+const plotH = computed(() => props.height - (props.legend ? 22 : 0))
+const paths = computed(() => {
+  if (!geo.value || !window.d3) return null
+  const d3 = window.d3
+  const proj = (props.projection==='mercator' ? d3.geoMercator() : (props.projection==='equalEarth' && d3.geoEqualEarth ? d3.geoEqualEarth() : d3.geoNaturalEarth1())).fitSize([props.width, plotH.value], geo.value)
+  const gp = d3.geoPath(proj)
+  return geo.value.features.map(f=>({ name:f.properties.name, d:gp(f), c:gp.centroid(f) }))
+})
+const nums = computed(() => Object.values(resolved.value).filter(v=>typeof v==='number'))
+const lo = computed(() => Math.min(...nums.value)); const hi = computed(() => Math.max(...nums.value))
+const bucket = computed(() => quantize(nums.value, 5))
+function fill(name){
+  const v = resolved.value[name]
+  if (v==null) return 'var(--chart-track)'
+  if (props.scale==='diverging') {
+    const amax = Math.max(Math.abs(lo.value), Math.abs(hi.value))||1
+    const a = Math.round((0.18+Math.min(1,Math.abs(v)/amax)*0.82)*100)
+    return 'color-mix(in srgb, var(--chart-'+(v>=0?'pos':'neg')+') '+a+'%, var(--bg-surface))'
+  }
+  return HEAT[Math.max(0, bucket.value(v))]
+}
+const swatches = computed(() => props.scale==='diverging'
+  ? ['var(--chart-neg)','color-mix(in srgb, var(--chart-neg) 40%, var(--bg-surface))','var(--chart-track)','color-mix(in srgb, var(--chart-pos) 40%, var(--bg-surface))','var(--chart-pos)']
+  : HEAT)
+</script>
+<template>
+  <div v-if="err" :style="{width:width+'px',height:height+'px',display:'flex',alignItems:'center',justifyContent:'center',fontFamily:'var(--font-mono)',fontSize:'var(--text-xs)',color:'var(--text-muted)',background:'var(--bg-inset)',borderRadius:'var(--radius-lg)',...style}">{{ err }}</div>
+  <div v-else-if="!paths" :style="{width:width+'px',height:height+'px',display:'flex',alignItems:'center',justifyContent:'center',fontFamily:'var(--font-mono)',fontSize:'var(--text-xs)',color:'var(--text-muted)',...style}">loading map…</div>
+  <div v-else :style="{position:'relative',display:'inline-block',lineHeight:0,...style}">
+    <svg :width="width" :height="plotH" role="img">
+      <path v-for="(p,i) in paths" :key="p.name+i" :d="p.d" :fill="fill(p.name)" stroke="var(--bg-surface)" stroke-width="0.5"
+        @mouseenter="interactive && (hover=i)" @mouseleave="interactive && (hover=null)" @click="emit('select', p.name, resolved[p.name])"
+        :style="{opacity:hover==null||hover===i?1:0.75,transition:'opacity var(--dur-fast) var(--ease-out)'}"/>
+      <path v-if="hover!=null" :d="paths[hover].d" fill="none" stroke="var(--action-primary)" stroke-width="1.4" pointer-events="none"/>
+    </svg>
+    <div v-if="legend" style="display:flex;align-items:center;gap:6px;padding-top:6px;line-height:normal">
+      <span style="font-family:var(--font-mono);font-size:10px;color:var(--chart-label)">{{ valueFormat(lo) }}</span>
+      <span v-for="(c,i) in swatches" :key="i" :style="{width:'22px',height:'8px',borderRadius:'2px',background:c}"/>
+      <span style="font-family:var(--font-mono);font-size:10px;color:var(--chart-label)">{{ valueFormat(hi) }}{{ unit ? ' '+unit : '' }}</span>
+    </div>
+    <div v-if="hover!=null && interactive" :style="{position:'absolute',left:paths[hover].c[0]+'px',top:paths[hover].c[1]+'px',transform:paths[hover].c[0]>width*0.62?'translate(calc(-100% - 10px),-50%)':'translate(10px,-50%)',pointerEvents:'none',zIndex:5,background:'var(--bg-surface)',border:'1px solid var(--border-card)',borderRadius:'var(--radius-md)',boxShadow:'var(--shadow-menu)',padding:'7px 10px',lineHeight:'normal',whiteSpace:'nowrap'}">
+      <div style="font-family:var(--font-sans);font-size:var(--text-2xs);color:var(--text-muted);padding-bottom:3px">{{ paths[hover].name }}</div>
+      <div style="font-family:var(--font-mono);font-size:var(--text-xs);color:var(--text-heading)">{{ resolved[paths[hover].name]==null ? 'no data' : valueFormat(resolved[paths[hover].name]) }}</div>
+    </div>
+  </div>
+</template>

package/components/charts/_dir.card.html

@@ -0,0 +1,7 @@
+<!-- @dsCard group="Directory Index" viewport="700x240" name="charts/" subtitle="22 chart types · 3 size tiers · chart-geometry core + ChartKit furniture" -->
+<!DOCTYPE html>
+<html><head><meta charset="utf-8"><script src="../_shared/frame-theme.js"></script><link rel="stylesheet" href="../../styles.css">
+<style>body{margin:0;background:var(--bg-surface);padding:18px;font-family:var(--font-sans)}.g{display:flex;flex-wrap:wrap;gap:8px}.p{border:1px solid var(--border-card);border-radius:var(--radius-md);padding:6px 10px;font-size:var(--text-xs);color:var(--text-body);font-family:var(--font-mono)}.h{font-size:var(--text-sm);line-height:19px;color:var(--text-secondary);padding-bottom:12px}</style></head>
+<body><div class="h">components/charts/ — the charting module. Every type has a live card under the <b>Charts</b> group; sizing tiers and color rules in <span style="font-family:var(--font-mono)">charts.prompt.md</span>. <b>WorldMap</b> additionally needs the pinned d3 + topojson tags on the page.</div>
+<div class="g"><span class="p">Sparkline</span><span class="p">LineChart</span><span class="p">BarChart</span><span class="p">BarList</span><span class="p">DonutChart</span><span class="p">ScatterChart</span><span class="p">HeatmapChart</span><span class="p">WaterfallChart</span><span class="p">BulletChart</span><span class="p">GaugeChart</span><span class="p">FunnelChart</span><span class="p">TreemapChart</span><span class="p">RadarChart</span><span class="p">Histogram</span><span class="p">BoxPlot</span><span class="p">ParetoChart</span><span class="p">CandlestickChart</span><span class="p">SankeyChart</span><span class="p">ChordChart</span><span class="p">SunburstChart</span><span class="p">WorldMap</span><span class="p">GanttChart</span><span class="p">ChartKit</span></div>
+</body></html>

package/components/charts/chart-3d.js

@@ -0,0 +1,84 @@
+// Shared 3D chart math: yaw/pitch rotation, orthographic projection, depth sorting,
+// face shading. Pure functions — no DOM, no tokens.
+
+/** Rotate (x,y,z) by yaw (around Y) then pitch (around X); degrees. */
+export function rotate3(x, y, z, yaw, pitch) {
+  const a = (yaw * Math.PI) / 180, b = (pitch * Math.PI) / 180;
+  const x1 = x * Math.cos(a) - z * Math.sin(a);
+  const z1 = x * Math.sin(a) + z * Math.cos(a);
+  const y1 = y * Math.cos(b) - z1 * Math.sin(b);
+  const z2 = y * Math.sin(b) + z1 * Math.cos(b);
+  return [x1, y1, z2];
+}
+
+/** Projector for a unit-ish box: world coords in, screen [x,y] + depth out. */
+export function makeProj(cx, cy, scale, yaw, pitch) {
+  return (x, y, z) => {
+    const [rx, ry, rz] = rotate3(x, -y, z, yaw, pitch);
+    return { x: cx + rx * scale, y: cy + ry * scale, depth: rz };
+  };
+}
+
+export const facePath = (pts) => "M" + pts.map((p) => p.x.toFixed(1) + " " + p.y.toFixed(1)).join(" L") + " Z";
+export const faceDepth = (pts) => pts.reduce((s, p) => s + p.depth, 0) / pts.length;
+
+/** Lambert-ish shade for a quad: mixes the base color toward white/black by orientation. */
+export function shade(color, amount) {
+  const pct = Math.round(Math.abs(amount) * 100);
+  return amount >= 0
+    ? `color-mix(in srgb, ${color} ${100 - pct}%, #fff)`
+    : `color-mix(in srgb, ${color} ${100 - pct}%, #000)`;
+}
+
+/** Normal-based light factor for a quad given 3 projected-space corners (screen z). */
+export function lightOf(p0, p1, p2) {
+  const ux = p1.x - p0.x, uy = p1.y - p0.y, uz = p1.depth - p0.depth;
+  const vx = p2.x - p0.x, vy = p2.y - p0.y, vz = p2.depth - p0.depth;
+  const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+  const len = Math.hypot(nx, ny, nz) || 1;
+  // Light from upper-left-front
+  return (nx * -0.35 + ny * -0.6 + nz * -0.72) / len;
+}
+
+/** The 6 faces of a cuboid spanning [x0,x1]×[y0,y1]×[z0,z1], projected + depth-sorted. */
+export function cuboidFaces(P, x0, x1, y0, y1, z0, z1) {
+  const c = [
+    P(x0, y0, z0), P(x1, y0, z0), P(x1, y1, z0), P(x0, y1, z0),
+    P(x0, y0, z1), P(x1, y0, z1), P(x1, y1, z1), P(x0, y1, z1),
+  ];
+  const F = [
+    { pts: [c[0], c[1], c[2], c[3]], kind: "front" },
+    { pts: [c[4], c[5], c[6], c[7]], kind: "back" },
+    { pts: [c[3], c[2], c[6], c[7]], kind: "top" },
+    { pts: [c[0], c[1], c[5], c[4]], kind: "bottom" },
+    { pts: [c[0], c[3], c[7], c[4]], kind: "left" },
+    { pts: [c[1], c[2], c[6], c[5]], kind: "right" },
+  ];
+  F.forEach((f) => { f.depth = faceDepth(f.pts); f.d = facePath(f.pts); });
+  return F.sort((a, b) => b.depth - a.depth);
+}
+
+/** Drag-to-rotate pointer handlers: returns props to spread on the svg.
+    Drag state lives on the DOM node — a closure variable would be reset by every
+    React re-render mid-drag, which silently kills the rotation after one frame. */
+export function dragRotate(get, set) {
+  return {
+    onPointerDown: (e) => { e.currentTarget.__kbDrag = { x: e.clientX, y: e.clientY, ...get() }; e.currentTarget.setPointerCapture && e.currentTarget.setPointerCapture(e.pointerId); },
+    onPointerMove: (e) => {
+      const s = e.currentTarget.__kbDrag;
+      if (!s) return;
+      set({
+        yaw: s.yaw + (e.clientX - s.x) * 0.45,
+        pitch: Math.max(8, Math.min(80, s.pitch + (e.clientY - s.y) * 0.35)),
+      });
+    },
+    onPointerUp: (e) => { e.currentTarget.__kbDrag = null; },
+    onPointerLeave: (e) => { e.currentTarget.__kbDrag = null; },
+  };
+}
+
+/** Sequential heat color for t∈[0,1] on the chart heat ramp (surface shading). */
+export function heatColor(t) {
+  const stops = ["var(--chart-heat-1)", "var(--chart-heat-2)", "var(--chart-heat-3)", "var(--chart-heat-4)", "var(--chart-heat-5)"];
+  return stops[Math.max(0, Math.min(4, Math.floor(t * 5 - 1e-9)))];
+}