@fundar/data-chart-telling 0.0.36 → 0.0.38

package/dist/plots/line/Plot.svelte

@@ -49,9 +49,8 @@
     tooltip = undefined,
   }: Props = $props();
 
-  // Fills leading/internal/trailing missing-data holes with an
-  // interpolated, distinctly-styled bridge, resolved per series like
-  // `segments` — see `GapsAwarePlotStylesConfig` (`types/layout/styles.ts`).
+  // Fills missing-data gaps with an interpolated, distinctly-styled bridge,
+  // resolved per series.
   const gaps = $derived(styles.gaps ?? {});
 
   const resolvedSeries = $derived(series ?? buildSeries(data!, x!, y!, z));
@@ -67,10 +66,8 @@
   const showVals = $derived(styles.values?.show ?? false);
   const hoverIsolate = $derived(styles.values?.hoverIsolate ?? false);
 
-  // A value label hovered while `styles.values.hoverIsolate` is on dims
-  // every other series exactly like a legend toggle would — local to this
-  // one `<Plot>` instance (not the shared HoverStore) so the gesture can't
-  // leak into unrelated tooltip/crosshair behavior.
+  // Dims every other series like a legend toggle when a value label is
+  // hovered, local to this `<Plot>` instance.
   let hoverIsolatedSeries = $state<string | null>(null);
 
   function effectiveDisabledFor(name: string): LegendDisabledStyle | undefined {
@@ -85,10 +82,7 @@
   const xAcc = $derived(resolveAccessor(resolvedSeries[0]?.x ?? ((d: TData) => d)));
   const yAcc = $derived(resolveAccessor(resolvedSeries[0]?.y ?? ((d: TData) => d)));
   const flat = $derived(resolvedSeries.flatMap((s) => s.data));
-  // A legend-disabled series is dimmed on the mark itself, but never surfaces
-  // in hover/tooltip — its points are simply absent from the candidate list.
-  // A gap row (see `gaps`) is excluded the same way — it carries no real
-  // value to hover.
+  // Legend-disabled series and gap rows are excluded from hover candidates.
   const hoverPoints = $derived(
     resolvedSeries.flatMap((s, idx) => {
       if (legendInteraction?.disabledSeries.has(s.name)) return [];
@@ -156,13 +150,7 @@
       .filter((p): p is { series: Series<TData>; lastRow: TData; color: string } => p !== undefined),
   );
 
-  // End-of-line labels can grow past the plot's own content box, into its
-  // margin — reserving real space there (rather than padding the domain,
-  // which would falsely imply data exists past the last real point) is
-  // what ValueLabels's own overflow measurement feeds into here, via a
-  // tracker local to this one `<Plot>` instance — see ValueLabels.svelte's
-  // own doc comment for why that locality (vs. svelteplot's shared margin
-  // context) matters.
+  // Grows the plot's margin to fit value labels that overflow the content box.
   const labelMargin = createLabelMarginTracker(() => margins);
 </script>
 

package/dist/plots/line/ValueLabels.svelte

@@ -13,12 +13,8 @@
   import type { MarginOverflow } from '../utils/labelOverflow.svelte';
 
   /**
-   * End-point value labels for `LinePlot` — one label per series at its last
-   * data point, with automatic collision resolution whenever several series
-   * end up with close last values. Rendered as a proper descendant of
-   * svelteplot's `<Plot>` (not just of `LinePlot` itself) so `usePlot()`
-   * below resolves the real, live y-scale needed to measure pixel-space
-   * overlap.
+   * End-of-line value labels for `LinePlot`, with automatic collision
+   * resolution and shared horizontal alignment across labels.
    */
   let {
     lastPoints,
@@ -33,7 +29,7 @@
   }: {
     lastPoints: { series: Series<TData>; lastRow: TData; color: string }[];
     values: ValuesStyle | undefined;
-    /** The plot's own pixel size — together with `numericMargins`, the ground truth for its content box (see `bounds()` below for why `usePlot()`'s own scale range can't be trusted for this). */
+    /** Plot pixel size, used with `numericMargins` to compute the content box. */
     width: number;
     height: number;
     /** `BasePlotLayout`'s resolved margins, already numeric on every side. */
@@ -49,17 +45,10 @@
 
   const cfg = $derived(getConfiguration());
 
-  // Elbow-routed leader line geometry (pixels), configurable project-wide
-  // via `setConfiguration({ line: { valueLabels: {...} } })` — each lane a
-  // run's members get spread across (see `laneAssignment`'s doc comment for
-  // how lanes are picked without crossing) is `laneStep` further out than
-  // the last; `elbowGap` is the shortest lane (rank 0, right off the data
-  // point); `labelGap` is the small clearance between the outermost lane and
-  // the label text it feeds into. `connectorColor`/`connectorWidth` are the
-  // leader line's own default look — deliberately *not* each series' own
-  // colour or stroke weight (matching the data line reads as more data, not
-  // as a leader, right where several lines are already converging) — both
-  // still overridable per-plot via `values.strokeStyle`.
+  // Elbow-routed leader line geometry (pixels), configurable via
+  // `setConfiguration({ line: { valueLabels: {...} } })`. `connectorColor`/
+  // `connectorWidth` default to a neutral look rather than each series' own
+  // colour, overridable per-plot via `values.strokeStyle`.
   const elbowGap = $derived(cfg.line.valueLabels.elbowGap);
   const laneStep = $derived(cfg.line.valueLabels.laneStep);
   const labelGap = $derived(cfg.line.valueLabels.labelGap);
@@ -70,12 +59,12 @@
   const connector = $derived(values?.strokeStyle);
   const formatValue = $derived(values?.format ?? ((v: number, name: string) => `${name} - ${v}`));
   const valAnchor = $derived<ValueAnchor>(values?.anchor ?? 'start');
-  // 'outside' is a per-point escape hatch resolved by HoverMarker; line's own
-  // value labels already have their own `anchor: 'outside'` concept above,
-  // so treat it as unset here.
+  // 'outside' is handled separately by HoverMarker, so it's treated as unset here.
   const resolvedTextAnchor = $derived(font?.textAnchor === 'outside' ? undefined : font?.textAnchor);
 
   const defaultDx = $derived(valAnchor === 'start' ? 6 : valAnchor === 'end' ? -6 : 0);
+  const baseDx = $derived(font?.dx ?? defaultDx);
+  const dir = $derived(Math.sign(baseDx) || 1);
   const defaultDy = $derived(valAnchor === 'outside' ? -8 : 0);
   const defaultTA = $derived(
     valAnchor === 'start' ? ('start' as const) : valAnchor === 'end' ? ('end' as const) : ('middle' as const),
@@ -85,38 +74,21 @@
 
   const plot = usePlot();
 
-  // ── Overflow measurement ─────────────────────────────────────────────────
-  // Measures how far the rendered labels extend past the plot's own content
-  // box and reports it to the caller (`Plot.svelte`), which grows its own
-  // local margin state to fit — see `labelOverflow.svelte.ts` for the actual
-  // `getBBox()` measurement. Reporting through a plain callback instead of
-  // registering directly into svelteplot's *shared* margin-auto-sizing
-  // context keeps this entirely local to one `<Plot>` instance: nothing here
-  // is shared across instances, which is what made that old approach spike
-  // CPU/memory into unresponsiveness when many instances mounted/unmounted
-  // together (e.g. a multi-story docs page → single story).
+  // Measures how far the rendered labels extend past the plot's content box
+  // and reports it to the caller (`Plot.svelte`), which grows its own local
+  // margin state to fit. Reported via a plain callback rather than
+  // svelteplot's shared margin context, to keep it local per `<Plot>`
+  // instance.
   let groupEl: SVGGElement | undefined = $state();
 
   watchLabelOverflow({
     el: () => groupEl,
-    // Deliberately built from our own `width`/`height`/`numericMargins`
-    // (all already correctly sized off the `width`/`height` this `<Plot>`
-    // was actually mounted with — see `BasePlotLayout`'s own `numericMargins`
-    // doc comment), not from `usePlot().scales.x/y.fn.range()`: svelteplot's
-    // `<Plot>` accepts an explicit `width`/`height` (our `fixedWidth`) for
-    // its own real layout, but the scale object it exposes through context
-    // is computed off its *internal* auto-detected size instead — normally
-    // the same number, but never reconciled with `fixedWidth` when one is
-    // given. That left `.range()` reporting a stale/placeholder boundary
-    // (svelteplot's own internal default, unrelated to this plot's actual
-    // pixel size) wherever a caller fixes `width`/`height` explicitly — which
-    // every plot kind here does — so this watcher never saw genuine
-    // right/bottom overflow past the *real* edge and never grew the margin
-    // to fit it, leaving end-point labels to render past the plot's true
-    // right edge with no space reserved for them.
+    // Built from `width`/`height`/`numericMargins` rather than the live
+    // scale's own `.range()`, which doesn't reconcile with an explicitly
+    // sized `<Plot>`.
     bounds: () => {
-      // getBBox() inside isn't itself tracked — depend on whatever actually
-      // changes the rendered label layout so this re-measures.
+      // getBBox() isn't tracked reactively — depend on whatever changes the
+      // label layout so this re-measures.
       void lastPoints;
       void values;
       return {
@@ -130,50 +102,88 @@
   });
 
   /**
-   * Pixel-space collision fix-up for end-point labels: resolves each label's
-   * true pixel Y through the plot's own live y-scale, then runs the shared
-   * two-pass declutter over those pixels to find how far each one needs to
-   * move to clear its neighbours. The result is a pure pixel *offset*
-   * (`extraDy`), applied the same way `<Text dy>` already is everywhere else
-   * in this file — it never becomes a data-space Y fed back into a mark,
-   * which would extend the y-scale's own domain and provoke an infinite
-   * autoscale ↔ declutter feedback loop.
+   * Pixel-space collision fix-up for end-point labels: resolves each
+   * label's pixel Y through the live y-scale, then declutters those pixels
+   * to find how far each needs to move to clear its neighbours and stay
+   * within the plot's own top/bottom edge (`extraDy` — applies even to a
+   * lone label with no neighbours, if its own value sits close enough to
+   * the edge). `rank`/`lanesUsed`/`runSize` come from `laneAssignment`,
+   * which turns the decluttered runs into lane assignments.
    *
-   * `inGroup`/`rank`/`lanesUsed` come from `laneAssignment`, fed by
-   * `declutter1D`'s own `connected` record rather than re-inferred from
-   * positions — see both functions' doc comments for why that's the only
-   * reliable source: position-based heuristics either miss a series that
-   * only had to move because a neighbour got pushed into it, or wrongly
-   * bridge two unrelated clusters that each happened to need decluttering
-   * on their own. The elbow connector below turns `rank` into a lane index.
-   * A series with nothing nearby is absent from the map, and its label
-   * renders with no extra offset.
+   * Horizontal placement (`aligned`/`reach`/`laneReach`/`dir`) is separate:
+   * every label reaches out to the same shared lane column, not just the
+   * ones in its own cluster, so the whole set of end-of-line labels lines
+   * up on one horizontal line. A label gets a connector whenever either of
+   * these moved it off its natural position — see the markup below.
+   *
+   * That shared column's direction can itself flip from `dir` to the right,
+   * but only ever away from the left: a leftward fan (`dir === -1`) runs
+   * into the Y axis's own tick labels once every point sits pinned against
+   * that same edge (e.g. a scroll/scrub caller's first visible point), with
+   * nowhere to reserve room without growing a margin purely to sit on top of
+   * them. The right has no such fixed content by default, so flipping there
+   * instead — for every aligned label at once — avoids the collision
+   * without needing any extra margin at all. The mirror case is deliberately
+   * left alone: a rightward fan's point is *always* pinned at the scale's
+   * own right edge by construction (`available` below would read ~0 for it
+   * too, same as the left), so the same check would flip the common case
+   * right back into the plot over its own lines — margin growth (see
+   * `Plot.svelte`'s `labelMargin`) is what actually handles that side.
    */
   const declutteredOffsets = $derived.by(() => {
-    const map = new SvelteMap<string, { extraDy: number; inGroup: boolean; rank: number; lanesUsed: number }>();
+    const map = new SvelteMap<
+      string,
+      { extraDy: number; aligned: boolean; rank: number; reach: number; laneReach: number; dir: number }
+    >();
     if (lastPoints.length < 2) return map;
     const yScale = plot.scales.y?.fn;
     if (!yScale) return map;
+    const xScale = plot.scales.x?.fn;
     const minGap = Math.max(16, fontSize * 1.4);
     const items = lastPoints.map(({ series: s, lastRow }) => ({
       name: s.name,
       pos: Number(yScale(Number(resolveAccessor(s.y)(lastRow)))),
+      px: xScale ? Number(xScale(resolveAccessor(s.x)(lastRow))) : undefined,
     }));
     const sorted = [...items].sort((a, b) => a.pos - b.pos);
-    // Same content-box source as `watchLabelOverflow`'s `bounds()` above,
-    // not `yScale.range()` — see that call's doc comment for why.
+    // Same content-box source as `watchLabelOverflow`'s `bounds()` above.
     const bounds: [number, number] = [numericMargins.top, height - numericMargins.bottom];
     const { positions: spread, connected } = declutter1D(items, minGap, bounds);
     const spreadByName = new Map(spread.map((d) => [d.name, d.pos]));
     const originals = sorted.map((item) => item.pos);
     const finals = sorted.map((item) => spreadByName.get(item.name) ?? item.pos);
     const ranks = laneAssignment(originals, finals, connected);
+
+    const anyGrouped = ranks.some((r) => r.runSize > 1);
+    const globalLanes = anyGrouped ? Math.max(...ranks.map((r) => r.lanesUsed)) : 1;
+    const reach = elbowGap + (globalLanes - 1) * laneStep + labelGap;
+
+    let effectiveDir = dir;
+    if (anyGrouped && dir === -1) {
+      // -Infinity (not +Infinity) when the x-scale isn't resolved yet on an
+      // early render — defaults to flipped until proven safe not to be,
+      // rather than the other way around. Defaulting to "don't flip" here
+      // briefly rendered the full leftward fan with no available-space data
+      // at all, which `watchLabelOverflow` could catch and lock in via its
+      // own monotonic growth before a later render corrected it — flipping
+      // right is never wrong even when it turns out to be unnecessary (nothing
+      // fixed lives there to run into), so there's no equivalent risk on
+      // that side to defend against.
+      const roomsLeft = sorted
+        .filter((item): item is typeof item & { px: number } => item.px != null)
+        .map((item) => item.px - numericMargins.left);
+      const availableLeft = roomsLeft.length > 0 ? Math.min(...roomsLeft) : -Infinity;
+      if (availableLeft < reach) effectiveDir = 1;
+    }
+
     sorted.forEach((item, i) => {
       map.set(item.name, {
         extraDy: finals[i] - originals[i],
-        inGroup: ranks[i].runSize > 1,
+        aligned: anyGrouped,
         rank: ranks[i].rank,
-        lanesUsed: ranks[i].lanesUsed,
+        reach,
+        laneReach: elbowGap + ranks[i].rank * laneStep,
+        dir: effectiveDir,
       });
     });
     return map;
@@ -181,27 +191,38 @@
 </script>
 
 <g bind:this={groupEl}>
+<!-- Nothing renders before both scales resolve: `declutteredOffsets` itself
+     only needs the y-scale, so an early render with the x-scale still
+     missing would otherwise fall back to plain `baseDx`, un-flipped — for a
+     long 'end'-anchored label that's a real, if brief, overflow past the
+     edge, and `watchLabelOverflow` can catch and lock that in via its own
+     monotonic growth before a later, correctly-positioned render arrives. -->
+{#if plot.scales.x?.fn && plot.scales.y?.fn}
 {#each lastPoints as { series: s, lastRow, color: seriesColor } (s.name)}
   {@const xFn = resolveAccessor(s.x)}
   {@const yFn = resolveAccessor(s.y)}
   {@const offset = declutteredOffsets.get(s.name)}
-  {@const extraDy = offset?.inGroup ? offset.extraDy : 0}
-  {@const baseDx = font?.dx ?? defaultDx}
-  {@const dir = Math.sign(baseDx) || 1}
-  {@const numLanes = offset?.inGroup ? offset.lanesUsed : 0}
-  {@const labelDx = offset?.inGroup
-    ? dir * (elbowGap + (numLanes - 1) * laneStep + labelGap)
-    : baseDx}
+  {@const extraDy = offset?.extraDy ?? 0}
+  {@const effDir = offset?.aligned ? offset.dir : dir}
+  {@const flipped = offset?.aligned && effDir !== dir}
+  {@const labelDx = offset?.aligned ? effDir * offset.reach : baseDx}
   {@const text = formatValue(Number(yFn(lastRow)), s.name)}
   {@const preferredTA = resolvedTextAnchor ?? defaultTA}
+  {@const finalTA = flipped
+    ? preferredTA === 'start'
+      ? 'end'
+      : preferredTA === 'end'
+        ? 'start'
+        : preferredTA
+    : preferredTA}
   {@const preferredLA = font?.lineAnchor ?? defaultLA}
   {@const disabled = disabledFor?.(s.name)}
   {@const disabledStroke = disabledStrokeOverride(disabled)}
   {@const disabledFill = disabledFillOverride(disabled)}
-  {#if offset?.inGroup && plot.scales.x?.fn && plot.scales.y?.fn}
+  {#if offset?.aligned || extraDy !== 0}
     {@const px = Number(plot.scales.x.fn(xFn(lastRow)))}
     {@const py = Number(plot.scales.y.fn(Number(yFn(lastRow))))}
-    {@const laneX = px + dir * (elbowGap + offset.rank * laneStep)}
+    {@const laneX = offset?.aligned ? px + effDir * offset.laneReach : px + labelDx}
     {@const targetY = py + extraDy}
     <path
       d={`M ${px} ${py} H ${laneX} V ${targetY} H ${px + labelDx}`}
@@ -214,9 +235,7 @@
       stroke-linejoin={connector?.strokeLinejoin ?? 'miter'}
     />
   {/if}
-  <!-- svelteplot's Text mark never wires pointer handlers to its DOM node,
-       despite declaring them in its types — a wrapping <g> catches the
-       boundary crossing instead (pointerenter/leave fire on every ancestor). -->
+  <!-- Text marks don't wire pointer handlers; a wrapping <g> catches them instead. -->
   <g
     role="presentation"
     onpointerenter={onHoverSeries && (() => onHoverSeries(s.name))}
@@ -229,7 +248,7 @@
       text={() => text}
       dx={labelDx}
       dy={(font?.dy ?? defaultDy) + extraDy}
-      textAnchor={preferredTA}
+      textAnchor={finalTA}
       lineAnchor={preferredLA}
       lineHeight={font?.lineHeight}
       rotate={font?.rotate}
@@ -246,4 +265,5 @@
     />
   </g>
 {/each}
+{/if}
 </g>

package/dist/plots/line/ValueLabels.svelte.d.ts

@@ -10,7 +10,7 @@ declare function $$render<TData extends Record<string, unknown>>(): {
             color: string;
         }[];
         values: ValuesStyle | undefined;
-        /** The plot's own pixel size — together with `numericMargins`, the ground truth for its content box (see `bounds()` below for why `usePlot()`'s own scale range can't be trusted for this). */
+        /** Plot pixel size, used with `numericMargins` to compute the content box. */
         width: number;
         height: number;
         /** `BasePlotLayout`'s resolved margins, already numeric on every side. */

package/dist/plots/utils/declutter.js

@@ -103,10 +103,10 @@ function runBiasWeights(down, up, connected, [lo, hi]) {
  * it lands entirely inside `[lo, hi]`. A run's own relative spacing is
  * preserved as-is (just translated) whenever it already fits in `hi - lo`;
  * only a run wider than the available space gets uniformly scaled down
- * around its centre first. Lone, unconnected positions pass through
- * untouched — they were never pushed by `declutter1D` in the first place,
- * so clamping one to the bounds would move a label away from the data point
- * it's honestly reporting, for no collision-avoidance reason at all.
+ * around its centre first. A lone, unconnected position is simply clamped
+ * to the nearer bound instead — its own value never needed decluttering,
+ * but it can still sit close enough to the scale's own edge to overflow on
+ * its own.
  */
 function fitRunsWithinBounds(positions, connected, [lo, hi]) {
     const out = [...positions];
@@ -130,6 +130,9 @@ function fitRunsWithinBounds(positions, connected, [lo, hi]) {
                 }
             }
         }
+        else {
+            out[i] = Math.min(Math.max(out[i], lo), hi);
+        }
         i = j + 1;
     }
     return out;

package/dist/plots/utils/labelOverflow.svelte.js

@@ -1,3 +1,4 @@
+import { AUTO_MARGIN_ESTIMATE } from '../../layout/plot/margins';
 const NO_OVERFLOW = { left: 0, right: 0, top: 0, bottom: 0 };
 /**
  * Watches an SVG group's rendered bounding box against the plot's own
@@ -94,19 +95,27 @@ export function createLabelMarginTracker(margins) {
             measured = next;
         }
     }
+    // `measured` is overflow *past* the current margin, not the total margin
+    // needed — grown on top of `AUTO_MARGIN_ESTIMATE` (the same fallback
+    // svelteplot's own 'auto' sizing is estimated by elsewhere), not the raw
+    // overflow alone, or growth would silently replace whatever room 'auto'
+    // would have reserved for the axis itself (tick labels, title) with a
+    // number that only accounts for the value label. `AUTO_MARGIN_ESTIMATE` is
+    // a fixed constant, not `numericMargins`' own already-grown value, so this
+    // can't compound into unbounded growth across repeated reports.
     const resolvedMargins = $derived.by(() => {
         const base = margins();
         if (measured.left <= 0 && measured.right <= 0 && measured.top <= 0 && measured.bottom <= 0)
             return base;
         const out = { ...base };
         if (measured.right > 0 && base?.right === undefined)
-            out.right = measured.right;
+            out.right = AUTO_MARGIN_ESTIMATE.right + measured.right;
         if (measured.left > 0 && base?.left === undefined)
-            out.left = measured.left;
+            out.left = AUTO_MARGIN_ESTIMATE.left + measured.left;
         if (measured.top > 0 && base?.top === undefined)
-            out.top = measured.top;
+            out.top = AUTO_MARGIN_ESTIMATE.top + measured.top;
         if (measured.bottom > 0 && base?.bottom === undefined)
-            out.bottom = measured.bottom;
+            out.bottom = AUTO_MARGIN_ESTIMATE.bottom + measured.bottom;
         return out;
     });
     // Bundles `resolvedMargins` with a remount key derived from `measured`,

package/dist/types/layout/coordinates.d.ts

@@ -1,4 +1,5 @@
 import type { GeoProjection } from 'd3-geo';
+import type { GeoCameraConfig } from '../plots/camera';
 /**
  * The projection names svelteplot's `<Plot projection>` accepts as a string
  * (svelteplot itself doesn't export this as a type — defined here so authors
@@ -53,6 +54,7 @@ export type GeoScalesConfig = {
         domain?: [number, number];
     };
 };
+/** Wheel/pinch scale gesture only — see `CoordinatesConfig.pan` for drag-to-translate, and `.rotate` for drag-to-spin-the-globe. */
 export type GeoZoomConfig = {
     min?: number;
     max?: number;
@@ -63,14 +65,18 @@ export type GeoZoomConfig = {
     };
 };
 /**
- * `coordinates` prop for GeoPlot — the only plot kind with a coordinate
- * system other than implicit cartesian. Bundles the projection (a `GoG`
- * Coordinates concern) and pan/zoom (navigating within that coordinate
- * system), resolved together by `CoordinatesLayout`.
+ * `coordinates` prop for GeoPlot — bundles the projection, interactive
+ * gestures, and the declarative `camera`, resolved by `CoordinatesLayout`.
  */
 export type CoordinatesConfig = {
     /** Which map projection to draw with. Defaults to `'equal-earth'`. */
     projection?: GeoProjectionConfig;
-    /** `true`/config enables drag-pan + scroll-zoom. Omitted/`false` = static map. */
+    /** `true`/config enables scroll/pinch-to-zoom. Independent of `pan`/`rotate`. */
     zoom?: boolean | GeoZoomConfig;
+    /** `true` enables drag-to-pan on a 2D (non-`orthographic`) projection. */
+    pan?: boolean;
+    /** `true` enables drag-to-rotate on `orthographic` (claims the drag gesture from `pan`). */
+    rotate?: boolean;
+    /** `GeoPlot`'s own declarative "current viewpoint" — frame/zoom/anchor on a target, animated on change. See `GeoCameraConfig`. */
+    camera?: GeoCameraConfig;
 };

package/dist/types/plots/camera.d.ts

@@ -0,0 +1,42 @@
+import type { EasingName, EasingFn } from '../charts/interpolate';
+import type { GeoInsetLocation } from '../markers/geo';
+/** What the camera frames. `features` shares its id space with `segments`/`featureId`. `center` has no extent of its own — see `GeoCameraConfig.zoom`. */
+export type GeoCameraTarget = {
+    features: string[];
+} | {
+    center: [number, number];
+} | {
+    bounds: GeoJSON.GeoJsonObject;
+};
+/**
+ * How the camera moves to a newly resolved target.
+ * - `progress` unset: auto-plays once over `duration` ms, eased by `easing`.
+ * - `progress` set (a live 0–1 value, e.g. from scroll): renders the move as
+ *   a pure function of it instead — stalls/reverses with the input.
+ */
+export type GeoCameraTransition = {
+    /** Auto-play duration in ms, ignored once `progress` is set. Defaults to 750. */
+    duration?: number;
+    /** Same `EasingName | EasingFn` vocabulary as `styles.gaps`/`TimelineConfig.interpolate`. */
+    easing?: EasingName | EasingFn;
+    /** A live 0–1 value the host drives itself instead of an auto-played duration. */
+    progress?: number;
+    /** Which way to interpolate rotation when ambiguous — only relevant for `orthographic`. `'shortest'` (default) or `'longest'`. No-op for 2D projections. */
+    direction?: 'shortest' | 'longest';
+};
+/**
+ * `coordinates.camera` — `GeoPlot`'s declarative "current viewpoint": frames,
+ * zooms and anchors on `target`, animated on change. Realized as a
+ * pixel-space pan/zoom transform for 2D projections, plus a `rotate`
+ * override for `orthographic`. Composes with interactive `coordinates.pan`/`zoom`/`rotate`.
+ */
+export type GeoCameraConfig = {
+    target: GeoCameraTarget;
+    /** Multiplier on the auto-fit scale for a `features`/`bounds` target (`1` = tight fit). For a `center` target, used directly as the pixel scale instead. */
+    zoom?: number;
+    /** Where the framed target lands within the plot frame — the same 9-point vocabulary `inset` markers use. Defaults to `'middle-middle'`. */
+    anchor?: GeoInsetLocation;
+    /** Pixel gap kept between the framed target and whichever edge(s) `anchor` pushes it toward. Defaults to 24. */
+    padding?: number;
+    transition?: GeoCameraTransition;
+};

package/dist/types/plots/camera.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "type": "module",
   "files": [
     "dist"