@columenlabs/lumen-ui 0.0.0-stage → 0.1.0

package/dist/lumen-finder.js

@@ -0,0 +1,275 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenFinder (any app): one box that finds a page, a setting or anything an app adds, opened with ⌘K (Ctrl K)
+// or the header's search button. A dialog on desktop, a bottom sheet on phone, around
+// LumenSelectorList. The shell lists what it knows itself (the nav's pages grouped by the app's
+// `pageTypes`, Settings, Recent, and Ask where an assistant is docked); an app adds its own rows from
+// anywhere below the shell with `useLumenFinderRows`, reading what was typed with `useLumenFinder`
+// (one app's symbols, another's accounts). Its chips are the app's
+// (`LumenFinderConfig`, LumenShell's `finder` prop).
+import { useRouter } from '@tanstack/react-router';
+import { ClockIcon, FileTextIcon, LayersIcon, SearchIcon, SettingsIcon, SparklesIcon, XIcon, } from 'lucide-react';
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { useAssistant } from './assistant-context.js';
+import { useAssistantScreen } from './assistant-screen.js';
+import { useIsMobile } from './hooks/use-mobile.js';
+import { IconButton } from './icon-button.js';
+import { cn } from './lib/utils.js';
+import { LumenSelectorList, fuzzyScore, } from './lumen-selector.js';
+import { Button } from './ui/button.js';
+import { Dialog, DialogContent, DialogTitle } from './ui/dialog.js';
+import { Kbd } from './ui/kbd.js';
+import { Sheet, SheetContent, SheetTitle } from './ui/sheet.js';
+/** A row shown under every chip (the assistant's Ask row). */
+const EVERY_SCOPE = '*';
+const DEFAULT_SCOPES = ['Pages', 'Settings'];
+const PAGE = { group: 'Pages', scope: 'Pages', icon: FileTextIcon };
+const WORKSPACE = { group: 'Workspaces', scope: 'Pages', icon: LayersIcon };
+const StateCtx = createContext(null);
+const ApiCtx = createContext(null);
+/** Whether Find is open and what is typed in it; null outside the shell. */
+export const useLumenFinder = () => useContext(StateCtx);
+/** Opens Find; null outside the shell. */
+export const useOpenLumenFinder = () => useContext(ApiCtx)?.setOpen ?? null;
+/** Adds rows to Find while the caller is mounted. Pass a memoized list (or null for none). */
+export function useLumenFinderRows(rows) {
+    const register = useContext(ApiCtx)?.register;
+    const key = useId();
+    useEffect(() => {
+        if (!register)
+            return;
+        register(key, rows);
+        return () => register(key, null);
+    }, [register, key, rows]);
+}
+const NO_TYPES = {};
+/** The groups with nothing typed: Recent, Pages, Workspaces, the page types' groups, then the rest. */
+function groupOrder(pageTypes) {
+    return [
+        ...new Set(['Recent', 'Pages', 'Workspaces', ...Object.values(pageTypes).map((t) => t.group)]),
+    ];
+}
+const recentKey = (app) => `lumen-finder-recent:${app}`;
+function readRecent(app) {
+    try {
+        const v = JSON.parse(localStorage.getItem(recentKey(app)) ?? '[]');
+        return Array.isArray(v) ? v : [];
+    }
+    catch {
+        return [];
+    }
+}
+function remember(app, r) {
+    if (!r.href)
+        return;
+    const next = [
+        { label: r.label, detail: r.detail, scope: r.scope, href: r.href },
+        ...readRecent(app).filter((x) => x.href !== r.href),
+    ].slice(0, 5);
+    try {
+        localStorage.setItem(recentKey(app), JSON.stringify(next));
+    }
+    catch {
+        // A private window refuses storage; Recent stays empty.
+    }
+}
+const scoreOf = (r, q) => [r.label, r.detail ?? '', ...(r.keywords ?? [])].reduce((best, s) => {
+    const v = fuzzyScore(q, s);
+    return v === null ? best : best === null ? v : Math.max(best, v);
+}, null);
+/** What shows: rows in the scope, matched and ranked against the query, Settings then Ask last. */
+function arrange(rows, q, scope, order, lastGroup) {
+    const query = q.trim().toLowerCase();
+    const groups = new Map();
+    for (const r of rows) {
+        if (scope !== 'All' && r.scope !== scope && r.scope !== EVERY_SCOPE)
+            continue;
+        if (query && r.group === 'Recent')
+            continue;
+        const v = r.pinned ? 2000 : query ? scoreOf(r, query) : 0;
+        if (v === null)
+            continue;
+        const g = groups.get(r.group) ?? { rows: [], best: Number.NEGATIVE_INFINITY };
+        g.rows.push({ r, v });
+        g.best = Math.max(g.best, v);
+        groups.set(r.group, g);
+    }
+    const last = (label) => label === lastGroup ? 2 : label === 'Settings' && !query ? 1 : 0;
+    const rank = (label) => {
+        const i = order.indexOf(label);
+        return i < 0 ? order.length : i;
+    };
+    return [...groups]
+        .sort(([a, ga], [b, gb]) => last(a) - last(b) || (query ? gb.best - ga.best : rank(a) - rank(b)))
+        .map(([label, g]) => ({
+        label,
+        options: (query ? g.rows.sort((x, y) => y.v - x.v) : g.rows).map((x) => x.r),
+    }));
+}
+/** The shell's own rows: Recent, the nav's pages, Settings sections and Ask the assistant. */
+function useShellRows(open, query, settings, openSettings, app, pageTypes, settingsScope) {
+    const screen = useAssistantScreen();
+    const assistant = useAssistant();
+    // The nav registers its pages with the screen map; Find reads it, and Recent, each time it opens.
+    const pages = useMemo(() => (open ? (screen?.map().pages ?? []) : []), [open, screen]);
+    const recent = useMemo(() => (open ? readRecent(app) : []), [open, app]);
+    const base = useMemo(() => {
+        const rows = recent.map((r) => ({
+            ...r,
+            value: `recent:${r.href}`,
+            group: 'Recent',
+            icon: ClockIcon,
+        }));
+        for (const p of pages) {
+            // A workspace page is its own kind, whatever the nav calls it.
+            const type = p.path.startsWith('/workspaces/') ? 'workspace' : p.type;
+            const t = (type && pageTypes[type]) || (type === 'workspace' ? WORKSPACE : PAGE);
+            const where = p.parent ?? p.section;
+            rows.push({
+                value: `page:${p.path}`,
+                label: p.title,
+                group: t.group,
+                scope: t.scope,
+                icon: t.icon,
+                detail: where === t.group ? undefined : where,
+                href: p.path,
+            });
+        }
+        for (const s of settings)
+            rows.push({
+                value: `setting:${s.id}`,
+                label: `Settings ▸ ${s.title}`,
+                group: 'Settings',
+                scope: settingsScope,
+                icon: SettingsIcon,
+                keywords: [s.title],
+                run: () => openSettings(s.id),
+            });
+        return rows;
+    }, [pages, recent, settings, openSettings, pageTypes, settingsScope]);
+    const q = query.trim();
+    return useMemo(() => assistant?.ready && q
+        ? [
+            ...base,
+            {
+                value: 'assistant',
+                label: `Ask ${assistant.name} “${q}”`,
+                group: assistant.name,
+                scope: EVERY_SCOPE,
+                icon: SparklesIcon,
+                pinned: true,
+                run: () => assistant.draft(q, []),
+            },
+        ]
+        : base, [base, assistant, q]);
+}
+/** Find for the shell: ⌘K, the rows apps add and the dialog. LumenShell mounts it. */
+export function LumenFinder({ app, settings, openSettings, config, children, }) {
+    const pageTypes = config?.pageTypes ?? NO_TYPES;
+    const settingsScope = config?.settingsScope ?? 'Settings';
+    const scopes = config?.scopes ?? DEFAULT_SCOPES;
+    const order = useMemo(() => groupOrder(pageTypes), [pageTypes]);
+    const lastGroup = useAssistant()?.name ?? null;
+    const [open, setOpenState] = useState(false);
+    const [query, setQuery] = useState('');
+    const [scope, setScope] = useState('All');
+    const [sources, setSources] = useState(new Map());
+    const setOpen = useCallback((o) => {
+        if (o) {
+            setQuery('');
+            setScope('All');
+        }
+        setOpenState(o);
+    }, []);
+    const register = useCallback((key, rows) => {
+        setSources((m) => {
+            if (m.get(key) === rows || (!rows && !m.has(key)))
+                return m;
+            const next = new Map(m);
+            if (rows)
+                next.set(key, rows);
+            else
+                next.delete(key);
+            return next;
+        });
+    }, []);
+    useEffect(() => {
+        const onKey = (e) => {
+            if ((e.metaKey || e.ctrlKey) && !e.altKey && e.key.toLowerCase() === 'k') {
+                e.preventDefault();
+                setOpenState((o) => {
+                    if (!o) {
+                        setQuery('');
+                        setScope('All');
+                    }
+                    return !o;
+                });
+            }
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, []);
+    const api = useMemo(() => ({ setOpen, register }), [setOpen, register]);
+    const state = useMemo(() => ({ open, query }), [open, query]);
+    const own = useShellRows(open, query, settings, openSettings, app, pageTypes, settingsScope);
+    const groups = useMemo(() => open
+        ? arrange([...own, ...[...sources.values()].flat()], query, scope, order, lastGroup)
+        : [], [open, own, sources, query, scope, order, lastGroup]);
+    return (_jsx(ApiCtx.Provider, { value: api, children: _jsxs(StateCtx.Provider, { value: state, children: [children, _jsx(FinderDialog, { app: app, open: open, onOpenChange: setOpen, query: query, onQuery: setQuery, scope: scope, onScope: setScope, scopes: scopes, placeholder: config?.placeholder ?? 'Find a page or setting', groups: groups })] }) }));
+}
+function FinderDialog({ app, open, onOpenChange, query, onQuery, scope, onScope, scopes, placeholder, groups, }) {
+    const mobile = useIsMobile();
+    const router = useRouter();
+    const list = useRef(null);
+    const input = useRef(null);
+    // Focus without scrolling: on a phone iOS pans the page to a focused field as the keyboard opens,
+    // which carried Find's input off the top of the screen.
+    useEffect(() => {
+        if (open)
+            input.current?.focus({ preventScroll: true });
+    }, [open]);
+    // ⌘↵ (Ctrl ↵) or a ⌘-click opens the pick in a new tab.
+    const newTab = useRef(false);
+    const pick = (o) => {
+        const r = o;
+        const tab = newTab.current;
+        newTab.current = false;
+        remember(app, r);
+        onOpenChange(false);
+        if (r.run)
+            return r.run();
+        if (!r.href)
+            return;
+        const outside = /^https?:/.test(r.href);
+        if (tab)
+            window.open(outside ? r.href : router.history.createHref(r.href), '_blank');
+        else if (outside)
+            window.location.assign(r.href);
+        else
+            void router.navigate({ href: r.href });
+    };
+    const body = (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", onMouseDownCapture: (e) => {
+            newTab.current = e.metaKey || e.ctrlKey;
+        }, 
+        // A swipe through the list on a phone drops the keyboard, so the rows it hid show.
+        onTouchMove: (e) => {
+            const typing = document.activeElement;
+            if (typing instanceof HTMLInputElement && !typing.contains(e.target))
+                typing.blur();
+        }, children: [_jsxs("div", { className: "flex items-center gap-2 border-b px-3 max-md:px-4", children: [_jsx(SearchIcon, { className: "size-4 shrink-0 text-muted-foreground" }), _jsx("input", { ref: input, value: query, onChange: (e) => onQuery(e.target.value), onKeyDown: (e) => {
+                            if (e.key === 'Escape')
+                                return;
+                            newTab.current = e.key === 'Enter' && (e.metaKey || e.ctrlKey);
+                            list.current?.key(e);
+                        }, "aria-label": "Find", placeholder: placeholder, className: "h-11 min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground max-md:text-base" }), mobile ? (_jsx(IconButton, { icon: XIcon, label: "Close", onClick: () => onOpenChange(false) })) : (_jsx(Kbd, { children: "esc" }))] }), _jsx("div", { className: "flex gap-1 overflow-x-auto border-b px-2 py-1.5 max-md:px-3", children: ['All', ...scopes].map((s) => (_jsx(Button, { size: "xs", variant: "ghost", "aria-pressed": s === scope, className: cn('text-muted-foreground', s === scope && 'bg-muted text-foreground'), onClick: () => onScope(s), children: s }, s))) }), _jsx(LumenSelectorList, { groups: groups, query: "", onPick: pick, handle: list, label: "Find", empty: query.trim() ? 'Nothing here by that name' : 'Nothing to find yet', className: "max-h-none min-h-0 flex-1 rounded-none bg-transparent shadow-none ring-0" }), !mobile && (_jsxs("div", { className: "flex items-center gap-3 border-t px-3 py-1.5 text-xs text-muted-foreground", children: [_jsxs("span", { className: "flex items-center gap-1", children: [_jsx(Kbd, { children: "\u2191" }), _jsx(Kbd, { children: "\u2193" }), " move"] }), _jsxs("span", { className: "flex items-center gap-1", children: [_jsx(Kbd, { children: "\u21B5" }), " open"] }), _jsxs("span", { className: "flex items-center gap-1", children: [_jsx(Kbd, { children: "\u2318\u21B5" }), " new tab"] })] }))] }));
+    if (mobile)
+        return (_jsx(Sheet, { open: open, onOpenChange: onOpenChange, children: _jsxs(SheetContent, { side: "top", showCloseButton: false, className: "flex h-dvh flex-col gap-0 p-0 pt-[env(safe-area-inset-top)]", children: [_jsx(SheetTitle, { className: "sr-only", children: "Find" }), open && body] }) }));
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { showCloseButton: false, className: "top-[12vh] flex h-[76vh] max-h-140 translate-y-0 flex-col gap-0 overflow-hidden p-0 sm:max-w-2xl", children: [_jsx(DialogTitle, { className: "sr-only", children: "Find" }), open && body] }) }));
+}
+const SHORTCUT = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform) ? '⌘K' : 'Ctrl K';
+/** The header's Find button. */
+export function LumenFinderButton() {
+    const open = useOpenLumenFinder();
+    if (!open)
+        return null;
+    return _jsx(IconButton, { icon: SearchIcon, label: `Find (${SHORTCUT})`, onClick: () => open(true) });
+}

package/dist/lumen-form.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from 'react';
+import { type LumenOption } from './lumen-selector.js';
+/** A text field's value is a string; a `multi` field's is a list. */
+export type LumenFormValue = string | string[];
+export type LumenFormValues = Record<string, LumenFormValue>;
+export interface LumenFormField {
+    id: string;
+    label: string;
+    /** `text` by default. `secret` hides what is typed; `select` and `multi` are LumenSelector. */
+    kind?: 'text' | 'secret' | 'number' | 'date' | 'textarea' | 'select' | 'multi';
+    required?: boolean;
+    /** A line under the field. */
+    hint?: ReactNode;
+    placeholder?: string;
+    /** `select` and `multi`. */
+    options?: readonly LumenOption[];
+    /** A message when the value is wrong, else nothing: `v => v.startsWith('https://') || 'Must start with https://'`. */
+    check?: (value: LumenFormValue, values: LumenFormValues) => string | true | undefined | null;
+    /** `secret`: the saved value, masked (`••••3f9a`). An empty box keeps it. */
+    saved?: string;
+}
+/** What stands in the way of a save, one message per field. */
+export declare function lumenFormIssues(fields: readonly LumenFormField[], values: LumenFormValues): Record<string, string>;
+export declare function LumenForm({ fields, initial, onSave, onCancel, saveLabel, busy, footer, }: {
+    fields: readonly LumenFormField[];
+    initial?: LumenFormValues;
+    /** Runs only when every check passes. A secret left empty is left out. */
+    onSave: (values: LumenFormValues) => void;
+    onCancel?: () => void;
+    saveLabel?: string;
+    busy?: boolean;
+    /** Beside Save, on the left (a Test button, a note). */
+    footer?: ReactNode;
+}): import("react").JSX.Element;

package/dist/lumen-form.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenForm:
+// a list of fields in, a laid-out form out. Label, input, hint and error sit the same way in every
+// app; each field's own check runs as the person types, and Save is LumenShell's SaveButton, which
+// lists what stands in the way and takes the person to it. A secret already saved shows masked and
+// is kept while its box stays empty. LumenForm only puts the kit's parts together.
+import { useId, useState } from 'react';
+import { SaveButton } from './form-issues.js';
+import { LumenSelector } from './lumen-selector.js';
+import { Button } from './ui/button.js';
+import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from './ui/field.js';
+import { Input } from './ui/input.js';
+import { Textarea } from './ui/textarea.js';
+const isEmpty = (v) => v === undefined || (Array.isArray(v) ? v.length === 0 : v.trim() === '');
+/** What stands in the way of a save, one message per field. */
+export function lumenFormIssues(fields, values) {
+    const out = {};
+    for (const f of fields) {
+        const v = values[f.id] ?? (f.kind === 'multi' ? [] : '');
+        if (isEmpty(v)) {
+            if (f.required && !(f.kind === 'secret' && f.saved))
+                out[f.id] = `${f.label} is needed`;
+            continue;
+        }
+        const r = f.check?.(v, values);
+        if (typeof r === 'string')
+            out[f.id] = r;
+    }
+    return out;
+}
+export function LumenForm({ fields, initial, onSave, onCancel, saveLabel = 'Save', busy = false, footer, }) {
+    const base = useId();
+    const [values, setValues] = useState(initial ?? {});
+    // A field shows its error once the person has left it, or tried to save.
+    const [touched, setTouched] = useState(new Set());
+    const errors = lumenFormIssues(fields, values);
+    const domId = (id) => `${base}-${id}`;
+    const issues = fields
+        .filter((f) => errors[f.id])
+        .map((f) => ({ where: f.label, message: errors[f.id] ?? '', target: domId(f.id) }));
+    const set = (id, v) => setValues((s) => ({ ...s, [id]: v }));
+    const touchAll = () => setTouched(new Set(fields.map((f) => f.id)));
+    const touch = (id) => setTouched((s) => (s.has(id) ? s : new Set(s).add(id)));
+    const save = () => onSave(Object.fromEntries(Object.entries(values).filter(([k, v]) => !(fields.find((f) => f.id === k)?.kind === 'secret' && isEmpty(v)))));
+    const input = (f) => {
+        const id = domId(f.id);
+        const invalid = touched.has(f.id) && !!errors[f.id];
+        const text = values[f.id] ?? '';
+        switch (f.kind) {
+            case 'select':
+                return (_jsx(LumenSelector, { id: id, label: f.label, options: f.options ?? [], placeholder: f.placeholder, value: text, onChange: (v) => {
+                        set(f.id, v);
+                        touch(f.id);
+                    } }));
+            case 'multi':
+                return (_jsx(LumenSelector, { id: id, label: f.label, multiple: true, options: f.options ?? [], placeholder: f.placeholder, value: values[f.id] ?? [], onChange: (v) => {
+                        set(f.id, v);
+                        touch(f.id);
+                    } }));
+            case 'textarea':
+                return (_jsx(Textarea, { id: id, value: text, placeholder: f.placeholder, "aria-invalid": invalid || undefined, onChange: (e) => set(f.id, e.target.value), onBlur: () => touch(f.id) }));
+            default:
+                return (_jsx(Input, { id: id, type: f.kind === 'secret'
+                        ? 'password'
+                        : f.kind === 'number'
+                            ? 'number'
+                            : f.kind === 'date'
+                                ? 'date'
+                                : 'text', value: text, placeholder: f.kind === 'secret' && f.saved ? f.saved : f.placeholder, autoComplete: f.kind === 'secret' ? 'off' : undefined, className: f.kind === 'date' ? 'w-44' : undefined, "aria-invalid": invalid || undefined, onChange: (e) => set(f.id, e.target.value), onBlur: () => touch(f.id) }));
+        }
+    };
+    return (_jsxs("form", { className: "flex flex-col gap-4", onSubmit: (e) => {
+            e.preventDefault();
+            touchAll();
+            if (!issues.length)
+                save();
+        }, children: [_jsx(FieldGroup, { children: fields.map((f) => {
+                    const invalid = touched.has(f.id) && !!errors[f.id];
+                    return (_jsxs(Field, { "data-invalid": invalid || undefined, children: [_jsxs(FieldLabel, { htmlFor: domId(f.id), children: [f.label, f.required && _jsx("span", { className: "font-normal text-muted-foreground", children: "required" })] }), input(f), f.hint && !invalid && _jsx(FieldDescription, { children: f.hint }), invalid && _jsx(FieldError, { children: errors[f.id] })] }, f.id));
+                }) }), _jsxs("div", { className: "flex items-center justify-end gap-2 border-t pt-3", children: [footer, _jsx("div", { className: "flex-1" }), onCancel && (_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: onCancel, children: "Cancel" })), _jsx("span", { className: "contents", onClickCapture: touchAll, children: _jsx(SaveButton, { issues: issues, busy: busy, label: saveLabel, onSave: save }) })] })] }));
+}

package/dist/lumen-geo-map.d.ts

@@ -0,0 +1,9 @@
+export declare function LumenGeoMap({ values, label, unit, height, }: {
+    /** The number for each country, by ISO alpha-2 code; countries left out draw empty. */
+    values: Record<string, number>;
+    /** What the map shows, for screen readers. */
+    label: string;
+    /** What the number counts ("visits"), shown in the tooltip after it. */
+    unit?: string;
+    height?: number;
+}): import("react").JSX.Element;

package/dist/lumen-geo-map.js

@@ -0,0 +1,121 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// LumenGeoMap: a world map shaded by a number per country (visits, people, revenue), drawn by
+// ECharts' map chart over Natural Earth's 110m countries (world-atlas). Countries are keyed by
+// ISO 3166-1 alpha-2 code ("US", "GB"), the code most sources report. The map and its outlines
+// load in their own chunk the first time a page draws one.
+import { useEffect, useMemo, useState } from 'react';
+import { LumenEChart, baseOption, useChartTokens } from './lumen-echart.js';
+const ANTARCTICA = '010';
+/** Russia and Fiji, by numeric code. */
+const ACROSS_180 = new Set(['643', '242']);
+/** Points this far west belong to the shape's eastern end. */
+const FAR_WEST = -150;
+const FULL_TURN = 360;
+/** The map's height when the caller gives none, as LumenEChart's. */
+const HEIGHT = 260;
+/** Country borders, thin enough to read small countries at 110m. */
+const BORDER = 0.5;
+/** Moves every far-west longitude in nested GeoJSON coordinates one turn east, in place. */
+function unwrap(c) {
+    if (!Array.isArray(c))
+        return;
+    if (typeof c[0] === 'number') {
+        if (c[0] < FAR_WEST)
+            c[0] += FULL_TURN;
+        return;
+    }
+    for (const inner of c)
+        unwrap(inner);
+}
+/** Registers the map chart and the world outlines with ECharts once. */
+let loading = null;
+function loadWorld() {
+    loading ??= Promise.all([
+        import('echarts/core'),
+        import('echarts/charts'),
+        import('topojson-client'),
+        import('world-atlas/countries-110m.json'),
+        import('i18n-iso-countries'),
+    ]).then(([core, charts, topo, atlas, iso]) => {
+        core.use([charts.MapChart]);
+        const world = atlas.default;
+        const fc = topo.feature(world, world.objects.countries);
+        // Antarctica takes a third of the height and holds no one; Russia and Fiji cross the date
+        // line, so their far-east points move past 180° to keep each shape in one piece.
+        fc.features = fc.features.filter((f) => f.id !== ANTARCTICA);
+        for (const f of fc.features)
+            if (f.id && ACROSS_180.has(f.id))
+                unwrap(f.geometry.coordinates);
+        // ECharts matches data to a feature by a property, and world-atlas keeps the numeric code
+        // in the feature's own id, so copy it into the properties.
+        const names = new Map();
+        for (const f of fc.features) {
+            f.properties.key = f.id ?? f.properties.name;
+            names.set(f.properties.key, f.properties.name);
+        }
+        core.registerMap('world', fc);
+        return {
+            key: (alpha2) => iso.default.alpha2ToNumeric(alpha2),
+            name: (key) => names.get(key) ?? key,
+        };
+    });
+    return loading;
+}
+export function LumenGeoMap({ values, label, unit, height = HEIGHT, }) {
+    const t = useChartTokens();
+    const [world, setWorld] = useState(null);
+    useEffect(() => {
+        let alive = true;
+        loadWorld().then((w) => alive && setWorld(w));
+        return () => {
+            alive = false;
+        };
+    }, []);
+    const option = useMemo(() => {
+        if (!world)
+            return null;
+        const data = Object.entries(values).flatMap(([code, value]) => {
+            const id = world.key(code.toUpperCase());
+            return id ? [{ name: id, value }] : [];
+        });
+        const max = Math.max(1, ...data.map((d) => d.value));
+        const base = baseOption(t);
+        return {
+            ...base,
+            tooltip: {
+                ...base.tooltip,
+                trigger: 'item',
+                formatter: (p) => {
+                    const value = Number.isFinite(p.value) ? p.value : 0;
+                    return `${world.name(p.name)}: ${value.toLocaleString('en-US')}${unit ? ` ${unit}` : ''}`;
+                },
+            },
+            visualMap: {
+                show: false,
+                min: 0,
+                max,
+                inRange: { color: [t.border, t.primary] },
+            },
+            series: [
+                {
+                    type: 'map',
+                    map: 'world',
+                    nameProperty: 'key',
+                    roam: false,
+                    left: 0,
+                    right: 0,
+                    top: 0,
+                    bottom: 0,
+                    data,
+                    itemStyle: { areaColor: t.border, borderColor: t.card, borderWidth: BORDER },
+                    emphasis: { label: { show: false }, itemStyle: { areaColor: t.series[5] ?? t.primary } },
+                    select: { disabled: true },
+                },
+            ],
+        };
+    }, [world, values, unit, t]);
+    if (!option) {
+        return (_jsx("div", { role: "img", "aria-label": label, className: "w-full animate-pulse rounded-md bg-muted/40", style: { height } }));
+    }
+    return _jsx(LumenEChart, { label: label, option: option, height: height });
+}

package/dist/lumen-grid.d.ts

@@ -0,0 +1,49 @@
+import { type ViewCardPlace } from '@columenlabs/lumen-ui-types/views';
+import { type ReactNode } from 'react';
+import { type LayoutItem } from 'react-grid-layout';
+/** The gap between cards, the shell's section gap. */
+export declare const GRID_GAP = 12;
+/** One card on the grid. */
+export interface GridCard {
+    id: string;
+    /** Columns of 6 it spans on a desktop. */
+    w: number;
+    /** Rows of 8px; left out, as tall as it draws. */
+    h?: number;
+    x?: number;
+    y?: number;
+    /** Its own place on a phone. */
+    phone?: ViewCardPlace;
+    /** A full-width table: outside Edit layout it sits between the grid's runs, scrolling sideways. */
+    wide?: boolean;
+    /** A card the page builds in code: it is laid out but not moved or sized. */
+    locked?: boolean;
+    node: ReactNode;
+}
+/** Where a card was put while editing: its columns, row, width and, once resized, its height. */
+export interface GridPlace {
+    id: string;
+    x: number;
+    y: number;
+    w: number;
+    h?: number;
+}
+export declare const useGridCell: () => {
+    fixed: boolean;
+} | null;
+/**
+ * The grid's layout: the page's lead cards, then the saved ones where they were placed, then the
+ * page's other cards, compacted upward; cards of measured height starting on the same row take the
+ * tallest's height.
+ */
+export declare function gridLayout(groups: GridCard[][], heights: Record<string, number>, phone: boolean): LayoutItem[];
+/** The page's cards on the grid; `onPlace` makes them movable and sizable (Edit layout). */
+export declare function LumenGrid({ lead, cards, tail, editing, onPlace, }: {
+    /** The page's own cards before the saved ones, and after them. */
+    lead?: GridCard[];
+    cards: GridCard[];
+    tail?: GridCard[];
+    editing: boolean;
+    /** Told every card's place after a move or resize, and whether it was on the phone's grid. */
+    onPlace?: (places: GridPlace[], phone: boolean) => void;
+}): import("react").JSX.Element;