feat(Chart): In projection mode, scaleExtent and translateExtent are now interpreted as relative values. scaleExtent: [0.5, 8] means 0.5x to 8x of the fitted projection scale. translateExtent is offset from the initial fitted position in pixels.

Author: techniq

.changeset/geo-relative-scale-translate-extent.md

@@ -0,0 +1,5 @@
+---
+'layerchart': minor
+---
+
+feat(Chart): In projection mode, `scaleExtent` and `translateExtent` are now interpreted as relative values (like d3-zoom). `scaleExtent: [0.5, 8]` means 0.5x to 8x of the fitted projection scale. `translateExtent` is offset from the initial fitted position in pixels.

docs/src/content/guides/transform.md

@@ -71,10 +71,10 @@ Updates the geo projection based on transform interactions. The projection is re
 
 Which projection properties are updated is controlled by the `apply` option and auto-detected from the projection type:
 
-| Projection type                                 | Default `apply`                                      | Behavior                |
-| ----------------------------------------------- | ---------------------------------------------------- | ----------------------- |
-| Flat maps (`geoMercator`, `geoAlbersUsa`, etc.) | `{ translate: true, scale: true, rotation: false }`  | Drag pans, scroll zooms |
-| Globe projections (`geoOrthographic`, etc.)     | `{ rotation: true, scale: false, translate: false }` | Drag rotates the globe  |
+| Projection type                                 | Default `apply`                                     | Behavior                   |
+| ----------------------------------------------- | --------------------------------------------------- | -------------------------- |
+| Flat maps (`geoMercator`, `geoAlbersUsa`, etc.) | `{ translate: true, scale: true, rotation: false }` | Drag pans, scroll zooms    |
+| Globe projections (`geoOrthographic`, etc.)     | `{ rotation: true, scale: true, translate: false }` | Drag rotates, scroll zooms |
 
 Auto-detection uses the projection's `clipAngle` — projections with a default clip angle (like orthographic) are treated as globes. Override with explicit `apply` values when needed.
 
@@ -100,12 +100,12 @@ When `fitGeojson` is provided and translate mode is active, the initial translat
 
 :example{ component="GeoPath" name="translucent-globe" }
 
-To enable zoom on a globe alongside rotation:
+Scroll zoom works on globes by default. To disable it, override with `apply`:
 
 ```svelte
 <Chart
 	geo={{ projection: geoOrthographic, fitGeojson: countries }}
-	transform={{ mode: 'projection', apply: { rotation: true, scale: true } }}
+	transform={{ mode: 'projection', apply: { rotation: true, scale: false } }}
 />
 ```
 
@@ -286,6 +286,8 @@ This works identically for geo canvas transforms:
 
 :example{ component="GeoPath" name="transform-canvas-scale-extent" }
 
+In `projection` mode, `scaleExtent` is interpreted as **relative to the initial fitted scale**. For example, `[0.5, 8]` means 0.5x to 8x of the projection's fitted scale — not absolute pixel values.
+
 ### `domainExtent` — constrain in data space
 
 For `mode: 'domain'` charts, `domainExtent` lets you express constraints in data units rather than pixel/transform space. This is useful when you want to say things like "don't pan before January 2020" or "always show at least 7 days."
@@ -387,12 +389,14 @@ Constrains panning to a bounding box in pixel coordinates `[[minX, minY], [maxX,
 
 For `domain` mode, prefer `domainExtent` which lets you express bounds in data units.
 
+In `projection` mode with flat maps, `translateExtent` defines pan bounds **relative to the initial fitted position**, and the allowed range scales with zoom level. For globe projections using rotation, values are passed through as degrees (yaw/pitch).
+
 ### How constraints compose
 
 When multiple constraint options are provided, they are applied in order:
 
-1. `scaleExtent` — clamps scale
-2. `translateExtent` — clamps translate
+1. `scaleExtent` — clamps scale (relative multipliers in projection mode)
+2. `translateExtent` — clamps translate (zoom-aware bounds in projection mode)
 3. `domainExtent` — clamps in domain space (converted to a `constrain` function internally)
 4. `constrain` — final custom adjustment
 
@@ -498,13 +502,13 @@ It supports placement (`'top-left'`, `'top-right'`, `'bottom-left'`, etc.), orie
 | Minimum visible range  | `domainExtent: { x: { minRange: 7 * 86400000 } }`         | [pan-zoom-domain-extent](/docs/components/LineChart/pan-zoom-domain-extent)             |
 | Pan/zoom a map (CSS)   | `transform={{ mode: 'canvas', scrollMode: 'scale' }}`     | [transform-canvas](/docs/components/GeoPath/transform-canvas)                           |
 | Pan/zoom a map (geo)   | `transform={{ mode: 'projection', scrollMode: 'scale' }}` | [transform-projection](/docs/components/GeoPath/transform-projection)                   |
-| World map (CSS)        | Canvas mode + world countries                              | [transform-world-canvas](/docs/components/GeoPath/transform-world-canvas)               |
-| World map (geo)        | Projection mode + world countries                          | [transform-world-projection](/docs/components/GeoPath/transform-world-projection)       |
+| World map (CSS)        | Canvas mode + world countries                             | [transform-world-canvas](/docs/components/GeoPath/transform-world-canvas)               |
+| World map (geo)        | Projection mode + world countries                         | [transform-world-projection](/docs/components/GeoPath/transform-world-projection)       |
 | Globe rotation         | `transform={{ mode: 'projection' }}` (auto-detected)      | [translucent-globe](/docs/components/GeoPath/translucent-globe)                         |
 | Geo map zoom limits    | `scaleExtent: [1, 8]`                                     | [transform-canvas-scale-extent](/docs/components/GeoPath/transform-canvas-scale-extent) |
 | Globe pitch clamping   | `constrain` with `Math.max(-90, ...)`                     | [transform-globe-constrain](/docs/components/GeoPath/transform-globe-constrain)         |
 | Brush-to-zoom          | `brush` + `transform={{ mode: 'domain' }}`                | [brush-pan-zoom](/docs/components/LineChart/brush-pan-zoom)                             |
-| Brush-to-zoom (band)   | `brush` + `transform` on band scale                       | [brush-pan-zoom-band](/docs/components/BarChart/brush-pan-zoom-band)                   |
+| Brush-to-zoom (band)   | `brush` + `transform` on band scale                       | [brush-pan-zoom-band](/docs/components/BarChart/brush-pan-zoom-band)                    |
 | Overview brush         | Separate chart with `brush.x` synced to `context.xDomain` | [pan-zoom-with-overview](/docs/components/LineChart/pan-zoom-with-overview)             |
 | Programmatic zoom only | `disablePointer: true` with `zoomTo()` calls              | [basic](/docs/components/Pack/basic)                                                    |
 | Animated transforms    | `motion: { type: 'tween', duration: 800 }`                | [basic](/docs/components/Pack/basic)                                                    |

docs/src/examples/components/TransformContext/pan-zoom-axes.svelte

@@ -25,10 +25,11 @@
 	transform={{
 		mode: 'domain',
 		scaleExtent: [1, 40],
-		domainExtent: {
-			x: { min: -100, max: domainSize + 100 },
-			y: { min: -100, max: domainSize + 100 }
-		},
+		// TODO: Disabled as domainExtent currently doesn't work well with inverted domains and zoom to cursor.
+		// domainExtent: {
+		// 	x: { min: -100, max: domainSize + 100 },
+		// 	y: { min: -100, max: domainSize + 100 }
+		// },
 		motion: { type: 'spring' }
 	}}
 	height={500}

docs/src/lib/components/controls/TransformContextControls.svelte

@@ -162,7 +162,9 @@
 				class="text-surface-content"
 			>
 				<svelte:fragment slot="selection" let:value>
-					<Icon data={value?.icon ?? LucideChevronDown} />
+					{#key value}
+						<Icon data={value?.icon ?? LucideChevronDown} />
+					{/key}
 				</svelte:fragment>
 			</MenuButton>
 		</Tooltip>

packages/layerchart/src/lib/components/Chart.svelte

@@ -936,13 +936,65 @@
     )
   );
 
-  // For band scale domain transforms, enforce scaleExtent minimum of 1 (can't zoom out past initial view)
+  // For projection mode, scaleExtent is relative to the initial fitted scale (like d3-zoom).
+  // e.g. [0.5, 8] means 0.5x to 8x of the fitted projection scale.
+  // For band scale domain transforms, enforce minimum of 1 (can't zoom out past initial view).
   const resolvedScaleExtent = $derived.by(() => {
+    if (transform?.mode === 'projection' && transform?.scaleExtent && initialTransform) {
+      const baseScale = initialTransform.scale;
+      return [
+        transform.scaleExtent[0] * baseScale,
+        transform.scaleExtent[1] * baseScale,
+      ] as [number, number];
+    }
     if (!isBandDomainTransform) return transform?.scaleExtent;
     const userExtent = transform?.scaleExtent;
     return [Math.max(1, userExtent?.[0] ?? 1), userExtent?.[1] ?? Infinity] as [number, number];
   });
 
+  // For projection mode with flat projections, translateExtent defines the pannable world bounds
+  // at the initial (1x) zoom level, similar to d3-zoom. The allowed translate range scales with
+  // the zoom ratio so you can pan more when zoomed in.
+  // For rotation mode (globes), translateExtent is passed through as degrees (yaw/pitch).
+  const resolvedTranslateExtent = $derived.by(() => {
+    if (transform?.mode === 'projection' && transform?.translateExtent) {
+      if (resolvedApply.rotation) {
+        // Rotation mode: values are degrees (yaw/pitch), pass through as-is
+        return transform.translateExtent;
+      }
+      // Flat projection translate mode: handled via projectionTranslateConstrain below
+      return undefined;
+    }
+    return transform?.translateExtent;
+  });
+
+  // For flat projection mode, implement d3-zoom-style translate constraining:
+  // The viewport (at current zoom) must overlap with the translateExtent world bounds.
+  // As zoom increases, the allowed translate range grows proportionally.
+  const projectionTranslateConstrain = $derived.by(() => {
+    if (transform?.mode !== 'projection' || !transform?.translateExtent || !initialTransform || resolvedApply.rotation) {
+      return undefined;
+    }
+
+    const baseScale = initialTransform.scale;
+    const baseTranslate = initialTransform.translate;
+    const [[x0, y0], [x1, y1]] = transform.translateExtent;
+
+    return (t: { scale: number; translate: { x: number; y: number } }) => {
+      let { scale, translate } = t;
+      // Zoom ratio relative to fitted scale
+      const k = scale / baseScale;
+
+      // Allowed translate range scales with zoom ratio
+      translate = {
+        x: Math.max(baseTranslate.x + x0 * k, Math.min(baseTranslate.x + x1 * k, translate.x)),
+        y: Math.max(baseTranslate.y + y0 * k, Math.min(baseTranslate.y + y1 * k, translate.y)),
+      };
+
+      return { scale, translate };
+    };
+  });
+
   // Default constrain for band scale domain transforms: prevent panning past data boundaries
   const bandScaleConstrain = $derived.by(() => {
     if (!isBandDomainTransform) return undefined;
@@ -969,7 +1021,7 @@
   // Compose user-provided constrain with domainExtent constrain and band scale constrain
   const composedConstrain = $derived.by(() => {
     const userConstrain = transform?.constrain;
-    const constrains = [bandScaleConstrain, domainExtentConstrain, userConstrain].filter(Boolean) as Array<(t: { scale: number; translate: { x: number; y: number } }) => { scale: number; translate: { x: number; y: number } }>;
+    const constrains = [bandScaleConstrain, domainExtentConstrain, projectionTranslateConstrain, userConstrain].filter(Boolean) as Array<(t: { scale: number; translate: { x: number; y: number } }) => { scale: number; translate: { x: number; y: number } }>;
     if (constrains.length === 0) return undefined;
     if (constrains.length === 1) return constrains[0];
     return (t: { scale: number; translate: { x: number; y: number } }) => {
@@ -1037,7 +1089,7 @@
   >
     {#key chartState.isMounted}
       <!-- svelte-ignore ownership_invalid_binding -->
-      {@const { domainExtent: _de, constrain: _uc, apply: _apply, scaleExtent: _se, ...transformProps } = transform ?? {}}
+      {@const { domainExtent: _de, constrain: _uc, apply: _apply, scaleExtent: _se, translateExtent: _te, ...transformProps } = transform ?? {}}
       <TransformContext
         bind:state={chartState.transformState}
         mode={transform?.mode ?? 'none'}
@@ -1046,6 +1098,7 @@
         {processTranslate}
         {...transformProps}
         scaleExtent={resolvedScaleExtent}
+        translateExtent={resolvedTranslateExtent}
         constrain={composedConstrain}
         disablePointer={(brush === true || (typeof brush === 'object' && !brush.disabled)) || transform?.disablePointer}
         {ondragstart}

packages/layerchart/src/lib/components/TransformContext.svelte.test.ts

@@ -14,7 +14,7 @@ describe('TransformContext', () => {
         height: 300,
         geo: {
           projection: geoMercator,
-          fitGeojson: { type: 'Sphere' } as GeoJSON.GeoJsonObject,
+          fitGeojson: { type: 'Sphere' } as unknown as GeoJSON.GeoJsonObject,
         },
         transform: {
           mode: 'projection' as const,
@@ -36,7 +36,7 @@ describe('TransformContext', () => {
       // Switch to orthographic (globe)
       chartProps.geo = {
         projection: geoOrthographic,
-        fitGeojson: { type: 'Sphere' } as GeoJSON.GeoJsonObject,
+        fitGeojson: { type: 'Sphere' } as unknown as GeoJSON.GeoJsonObject,
       };
       await tick();
 
@@ -53,7 +53,7 @@ describe('TransformContext', () => {
         height: 300,
         geo: {
           projection: geoOrthographic,
-          fitGeojson: { type: 'Sphere' } as GeoJSON.GeoJsonObject,
+          fitGeojson: { type: 'Sphere' } as unknown as GeoJSON.GeoJsonObject,
         },
         transform: {
           mode: 'projection' as const,
@@ -75,7 +75,7 @@ describe('TransformContext', () => {
       // Switch to Mercator (flat)
       chartProps.geo = {
         projection: geoMercator,
-        fitGeojson: { type: 'Sphere' } as GeoJSON.GeoJsonObject,
+        fitGeojson: { type: 'Sphere' } as unknown as GeoJSON.GeoJsonObject,
       };
       await tick();
 
@@ -93,7 +93,7 @@ describe('TransformContext', () => {
           height: 300,
           geo: {
             projection: geoOrthographic,
-            fitGeojson: { type: 'Sphere' } as GeoJSON.GeoJsonObject,
+            fitGeojson: { type: 'Sphere' } as unknown as GeoJSON.GeoJsonObject,
           },
           transform: {
             mode: 'projection' as const,
@@ -122,6 +122,50 @@ describe('TransformContext', () => {
       expect(chartContext.geo.projection?.scale()).toBeCloseTo(initialScale * 2, 0);
     });
 
+    it('should interpret scaleExtent as relative multipliers in projection mode', async () => {
+      let chartContext: any;
+
+      render(TransformTestHarness, {
+        chartProps: {
+          height: 300,
+          geo: {
+            projection: geoMercator,
+            fitGeojson: { type: 'Sphere' } as unknown as GeoJSON.GeoJsonObject,
+          },
+          transform: {
+            mode: 'projection' as const,
+            scrollMode: 'scale' as const,
+            scaleExtent: [0.5, 2] as [number, number],
+          },
+        },
+        oncontext: (ctx: any) => {
+          chartContext = ctx;
+        },
+      });
+
+      await vi.waitFor(() => expect(chartContext).toBeDefined());
+
+      const initialScale = chartContext.transform.scale;
+      expect(initialScale).toBeGreaterThan(10); // Mercator fitSize scale is typically large
+
+      // Try to zoom way beyond 2x — should be clamped to 2x initial
+      chartContext.transform.setScale(initialScale * 5, { instant: true });
+      await tick();
+
+      await vi.waitFor(() => {
+        // Should be clamped to ~2x the initial scale
+        expect(chartContext.transform.scale).toBeCloseTo(initialScale * 2, 0);
+      });
+
+      // Try to zoom below 0.5x — should be clamped to 0.5x initial
+      chartContext.transform.setScale(initialScale * 0.1, { instant: true });
+      await tick();
+
+      await vi.waitFor(() => {
+        expect(chartContext.transform.scale).toBeCloseTo(initialScale * 0.5, 0);
+      });
+    });
+
     it('should sync disablePointer reactively', async () => {
       let chartContext: any;
 

packages/layerchart/src/lib/states/transform.svelte.ts

@@ -190,7 +190,9 @@ export class TransformState {
   private _applyTranslate(x: number, y: number, deltaX: number, deltaY: number) {
     if (this.processTranslate) return this.processTranslate(x, y, deltaX, deltaY);
     if (this.mode === 'domain') {
-      // Negate deltaY because screen Y (top→bottom) is inverted vs data Y (bottom→top)
+      // Negate deltaY because screen Y (top→bottom) is inverted vs data Y (bottom→top).
+      // This works for both normal and reversed Y domains because _computeTransformDomain
+      // uses signed range, which naturally handles the reversal.
       if (this.axis === 'x') return { x: x + deltaX, y: 0 };
       if (this.axis === 'y') return { x: 0, y: y - deltaY };
       return { x: x + deltaX, y: y - deltaY };