@mui/x-charts-premium 9.7.0 → 9.9.0

package/internals/plugins/useGeoProjectionZoom/useGeoProjectionZoom.mjs

@@ -0,0 +1,166 @@
+'use client';
+
+import _extends from "@babel/runtime/helpers/esm/extends";
+import * as React from 'react';
+import { useEffectAfterFirstRender } from '@mui/x-internals/useEffectAfterFirstRender';
+import { useRegisterZoomGestures } from '@mui/x-charts-pro/internals';
+import { selectorChartRawProjection } from "../useGeoProjection/useGeoProjection.selectors.mjs";
+import { BUTTON_ZOOM_STEP, getDefaultMapInteraction } from "./mapZoom.utils.mjs";
+import { usePanOnDrag } from "./gestureHooks/usePanOnDrag.mjs";
+import { useZoomOnWheel } from "./gestureHooks/useZoomOnWheel.mjs";
+import { useZoomOnPinch } from "./gestureHooks/useZoomOnPinch.mjs";
+import { getDefaultTranslation } from "../useGeoProjection/projection.utils.mjs";
+export const useGeoProjectionZoom = ({
+  store,
+  instance,
+  params
+}) => {
+  const {
+    zoom,
+    onViewChange,
+    view
+  } = params;
+  const interactionDefaults = getDefaultMapInteraction(selectorChartRawProjection(store.state));
+  const {
+    minZoomLevel = 0.5,
+    maxZoomLevel = 8,
+    maxEmptySpace = 0,
+    rotationAllowed = interactionDefaults.rotationAllowed,
+    translationAllowed = interactionDefaults.translationAllowed
+  } = typeof zoom === 'object' ? zoom : {};
+
+  // `zoom` is either a boolean or a config object; an object always enables the interaction.
+  const enabled = zoom !== false;
+  const isControlled = view !== undefined;
+  const clampZoomLevel = React.useCallback(zoomLevel => Math.max(minZoomLevel, Math.min(maxZoomLevel, zoomLevel)), [minZoomLevel, maxZoomLevel]);
+
+  // The view is the source of truth, stored directly: no pixel <-> view conversion on write/read.
+  // Callers are responsible for clamping `zoomLevel`.
+  const applyView = React.useCallback(newView => {
+    if (!isControlled) {
+      store.set('geoProjectionZoom', _extends({}, store.state.geoProjectionZoom, {
+        zoomLevel: newView.zoomLevel,
+        center: newView.center,
+        translation: newView.translation,
+        roll: newView.roll
+      }));
+    }
+    onViewChange?.(newView);
+  }, [store, isControlled, onViewChange]);
+
+  // In controlled mode, keep the store in sync with the `view` prop. The initial view is seeded in
+  // `getInitialState`, so this only reacts to subsequent updates.
+  useEffectAfterFirstRender(() => {
+    if (!view) {
+      return;
+    }
+    store.set('geoProjectionZoom', _extends({}, store.state.geoProjectionZoom, {
+      zoomLevel: view.zoomLevel,
+      center: view.center,
+      translation: view.translation,
+      roll: view.roll
+    }));
+  }, [store, view]);
+  useRegisterZoomGestures({
+    instance
+  });
+
+  // --- gestures: reuse the generic primitives from x-charts-pro -------------
+  usePanOnDrag({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace
+  });
+  useZoomOnWheel({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace,
+    minZoomLevel,
+    maxZoomLevel
+  });
+  useZoomOnPinch({
+    store,
+    instance
+  }, applyView, {
+    enabled,
+    rotationAllowed,
+    translationAllowed,
+    maxEmptySpace,
+    minZoomLevel,
+    maxZoomLevel
+  });
+
+  // Shared by both buttons: clamp through `applyView` (which also handles controlled mode and
+  // `onViewChange`), keeping the current center/translation. Bail out when already at a bound so a
+  // click at the limit stays a no-op.
+  const zoomBy = React.useCallback(factor => {
+    const current = store.state.geoProjectionZoom;
+    const currentZoom = current.zoomLevel ?? 1;
+    const nextZoom = clampZoomLevel(currentZoom * factor);
+    if (nextZoom === currentZoom) {
+      return;
+    }
+    applyView({
+      zoomLevel: nextZoom,
+      center: current.center ?? [0, 0],
+      translation: current.translation ?? [0, 0],
+      roll: current.roll ?? 0
+    });
+  }, [store, clampZoomLevel, applyView]);
+  const zoomIn = React.useCallback(() => zoomBy(BUTTON_ZOOM_STEP), [zoomBy]);
+  const zoomOut = React.useCallback(() => zoomBy(1 / BUTTON_ZOOM_STEP), [zoomBy]);
+  const resetZoom = React.useCallback(() => {
+    applyView({
+      zoomLevel: store.state.geoProjectionZoom.initialZoomLevel,
+      center: store.state.geoProjectionZoom.initialCenter,
+      translation: store.state.geoProjectionZoom.initialTranslation,
+      roll: store.state.geoProjectionZoom.initialRoll
+    });
+  }, [applyView, store]);
+  const publicAPI = {
+    zoomIn,
+    zoomOut,
+    resetZoom
+  };
+  return {
+    publicAPI,
+    instance: publicAPI
+  };
+};
+useGeoProjectionZoom.params = {
+  zoom: true,
+  initialView: true,
+  view: true,
+  onViewChange: true
+};
+useGeoProjectionZoom.getDefaultizedParams = ({
+  params
+}) => _extends({}, params, {
+  zoom: params.zoom ?? false
+});
+useGeoProjectionZoom.getInitialState = params => {
+  const zoomLevel = params.view?.zoomLevel ?? params.initialView?.zoomLevel ?? 1;
+  const center = params.view?.center ?? params.initialView?.center ?? [0, 0];
+  const roll = params.view?.roll ?? params.initialView?.roll ?? 0;
+  const translation = params.view?.translation ?? params.initialView?.translation ?? getDefaultTranslation(params.projection, params.geoData, params.parallels, center) ?? [0, 0];
+  return {
+    geoProjectionZoom: {
+      zoomLevel,
+      center,
+      translation,
+      roll,
+      initialZoomLevel: zoomLevel,
+      initialCenter: center,
+      initialTranslation: translation,
+      initialRoll: roll
+    }
+  };
+};

package/internals/plugins/useGeoProjectionZoom/useGeoProjectionZoom.types.d.mts

@@ -0,0 +1,152 @@
+import type { ChartPluginSignature } from '@mui/x-charts/internals';
+import type { UseGeoProjectionSignature } from "../useGeoProjection/useGeoProjection.types.mjs";
+/**
+ * Which rotation axes a pan/zoom gesture may move:
+ * - `'both'`: rotate freely along longitude and latitude, keeping the roll fixed.
+ * - `'longitude'`: rotate along longitude only (lock the north–south tilt).
+ * - `'none'`: lock every axis.
+ * - `'both+roll'`: rotate freely along longitude and latitude, and allow rolling the map around the center.
+ */
+export type MapRotationAxis = 'both' | 'longitude' | 'none' | 'both+roll';
+export type MapTranslationAxis = 'both' | 'x' | 'y' | 'none';
+/**
+ * Public, resolution-independent representation of the map view.
+ *
+ * Unlike the raw projection `scale`/`translate` (both in SVG pixels, tied to the drawing-area
+ * size), a view survives a resize: `zoomLevel` is a ratio and `center` is a geographic coordinate.
+ */
+export interface MapZoomView {
+  /**
+   * The zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * `1` means the whole dataset fits the drawing area; `2` means twice as close.
+   */
+  zoomLevel: number;
+  /**
+   * The geographic coordinate `[longitude, latitude]` displayed at the center of the drawing area.
+   */
+  center: [number, number];
+  /**
+   * The map translation in percentage of the drawing area.
+   */
+  translation: [number, number];
+  /**
+   * The roll of the map, in degrees.
+   * This spins the map around the point displayed at the center of the drawing area, independently
+   * of the `center` (which controls longitude/latitude).
+   */
+  roll: number;
+}
+/**
+ * Fine-grained configuration for the map zoom/pan interaction, passed as the `zoom` parameter
+ * instead of a plain `true`.
+ */
+export interface MapZoomOptions {
+  /**
+   * Which axes the map can be rotated along while panning or zooming.
+   * For example, `'longitude'` lets the map rotate east–west but locks the north–south tilt.
+   */
+  rotationAllowed?: MapRotationAxis;
+  /**
+   * Which axes the map can be translated along while panning or zooming.
+   * For example, `'y'` lets the map translate vertically but locks the horizontal movement.
+   */
+  translationAllowed?: MapTranslationAxis;
+  /**
+   * The minimum zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * @default 1
+   */
+  minZoomLevel?: number;
+  /**
+   * The maximum zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * @default 8
+   */
+  maxZoomLevel?: number;
+  /**
+   * The maximal space left empty while panning, expressed as a ratio of the drawing area size.
+   * For example:
+   * - `0` keeps the map's bounding box flush with (or covering) the drawing area.
+   * - `0.5` lets the user pan until at most half of the drawing area is empty on a given side.
+   * @default 0
+   */
+  maxEmptySpace?: number;
+}
+interface UseGeoProjectionZoomParameters {
+  /**
+   * If `true`, the map can be panned (drag) and zoomed (wheel / pinch).
+   * Pass a {@link MapZoomOptions} object to fine-tune the interaction, e.g. restrict rotation axes.
+   * @default false
+   */
+  zoom?: boolean | MapZoomOptions;
+  /**
+   * The view to apply on mount, when the zoom is not controlled.
+   * Use this to seed the map at a specific zoom level and center without controlling it.
+   */
+  initialView?: Omit<MapZoomView, 'translation' | 'roll'> & Partial<Pick<MapZoomView, 'translation' | 'roll'>>;
+  /**
+   * The view to display, in controlled mode.
+   * When set, the component does not update the view on its own — drive it from `onViewChange`.
+   */
+  view?: MapZoomView;
+  /**
+   * Callback fired when the map zoom or pan changes (including programmatic reset).
+   * @param {MapZoomView} view The new zoom level and geographic center.
+   */
+  onViewChange?: (view: MapZoomView) => void;
+}
+interface UseGeoProjectionZoomDefaultizedParameters extends UseGeoProjectionZoomParameters {
+  zoom: boolean | MapZoomOptions;
+}
+/**
+ * Imperative methods shared by the plugin `instance` and the public `apiRef`.
+ */
+interface UseGeoProjectionZoomPublicApi {
+  /**
+   * Zoom the map in by a fixed step, centered on the drawing area.
+   */
+  zoomIn: () => void;
+  /**
+   * Zoom the map out by a fixed step, centered on the drawing area.
+   */
+  zoomOut: () => void;
+  /**
+   * Reset the map to the default scale and translation that fit the data in the drawing area.
+   */
+  resetZoom: () => void;
+}
+interface UseGeoProjectionZoomInstance extends UseGeoProjectionZoomPublicApi {}
+export interface UseGeoProjectionZoomState {
+  geoProjectionZoom: {
+    /**
+     * The zoom level, as a multiple of the scale that fits the data in the drawing area.
+     * `null` (the default) and `1` both mean fit-to-data. The absolute projection scale is
+     * derived as `fitScale * zoomLevel`, so this stays valid across resizes.
+     */
+    zoomLevel: number;
+    /**
+     * The geographic coordinate `[longitude, latitude]` displayed at the center of the drawing area.
+     * `null` keeps the data centered (the fit center).
+     */
+    center: [number, number];
+    /**
+     * The map translation in percentage of the drawing area.
+     */
+    translation: [number, number] | null;
+    /**
+     * The roll of the map, in degrees. `null` keeps the map upright (no roll).
+     */
+    roll: number;
+    initialTranslation: [number, number];
+    initialCenter: [number, number];
+    initialZoomLevel: number;
+    initialRoll: number;
+  };
+}
+export type UseGeoProjectionZoomSignature = ChartPluginSignature<{
+  params: UseGeoProjectionZoomParameters;
+  defaultizedParams: UseGeoProjectionZoomDefaultizedParameters;
+  publicAPI: UseGeoProjectionZoomPublicApi;
+  instance: UseGeoProjectionZoomInstance;
+  state: UseGeoProjectionZoomState;
+  dependencies: [UseGeoProjectionSignature];
+}>;
+export {};

package/internals/plugins/useGeoProjectionZoom/useGeoProjectionZoom.types.d.ts

@@ -0,0 +1,152 @@
+import type { ChartPluginSignature } from '@mui/x-charts/internals';
+import type { UseGeoProjectionSignature } from "../useGeoProjection/useGeoProjection.types.js";
+/**
+ * Which rotation axes a pan/zoom gesture may move:
+ * - `'both'`: rotate freely along longitude and latitude, keeping the roll fixed.
+ * - `'longitude'`: rotate along longitude only (lock the north–south tilt).
+ * - `'none'`: lock every axis.
+ * - `'both+roll'`: rotate freely along longitude and latitude, and allow rolling the map around the center.
+ */
+export type MapRotationAxis = 'both' | 'longitude' | 'none' | 'both+roll';
+export type MapTranslationAxis = 'both' | 'x' | 'y' | 'none';
+/**
+ * Public, resolution-independent representation of the map view.
+ *
+ * Unlike the raw projection `scale`/`translate` (both in SVG pixels, tied to the drawing-area
+ * size), a view survives a resize: `zoomLevel` is a ratio and `center` is a geographic coordinate.
+ */
+export interface MapZoomView {
+  /**
+   * The zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * `1` means the whole dataset fits the drawing area; `2` means twice as close.
+   */
+  zoomLevel: number;
+  /**
+   * The geographic coordinate `[longitude, latitude]` displayed at the center of the drawing area.
+   */
+  center: [number, number];
+  /**
+   * The map translation in percentage of the drawing area.
+   */
+  translation: [number, number];
+  /**
+   * The roll of the map, in degrees.
+   * This spins the map around the point displayed at the center of the drawing area, independently
+   * of the `center` (which controls longitude/latitude).
+   */
+  roll: number;
+}
+/**
+ * Fine-grained configuration for the map zoom/pan interaction, passed as the `zoom` parameter
+ * instead of a plain `true`.
+ */
+export interface MapZoomOptions {
+  /**
+   * Which axes the map can be rotated along while panning or zooming.
+   * For example, `'longitude'` lets the map rotate east–west but locks the north–south tilt.
+   */
+  rotationAllowed?: MapRotationAxis;
+  /**
+   * Which axes the map can be translated along while panning or zooming.
+   * For example, `'y'` lets the map translate vertically but locks the horizontal movement.
+   */
+  translationAllowed?: MapTranslationAxis;
+  /**
+   * The minimum zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * @default 1
+   */
+  minZoomLevel?: number;
+  /**
+   * The maximum zoom level, as a multiple of the scale that fits the data in the drawing area.
+   * @default 8
+   */
+  maxZoomLevel?: number;
+  /**
+   * The maximal space left empty while panning, expressed as a ratio of the drawing area size.
+   * For example:
+   * - `0` keeps the map's bounding box flush with (or covering) the drawing area.
+   * - `0.5` lets the user pan until at most half of the drawing area is empty on a given side.
+   * @default 0
+   */
+  maxEmptySpace?: number;
+}
+interface UseGeoProjectionZoomParameters {
+  /**
+   * If `true`, the map can be panned (drag) and zoomed (wheel / pinch).
+   * Pass a {@link MapZoomOptions} object to fine-tune the interaction, e.g. restrict rotation axes.
+   * @default false
+   */
+  zoom?: boolean | MapZoomOptions;
+  /**
+   * The view to apply on mount, when the zoom is not controlled.
+   * Use this to seed the map at a specific zoom level and center without controlling it.
+   */
+  initialView?: Omit<MapZoomView, 'translation' | 'roll'> & Partial<Pick<MapZoomView, 'translation' | 'roll'>>;
+  /**
+   * The view to display, in controlled mode.
+   * When set, the component does not update the view on its own — drive it from `onViewChange`.
+   */
+  view?: MapZoomView;
+  /**
+   * Callback fired when the map zoom or pan changes (including programmatic reset).
+   * @param {MapZoomView} view The new zoom level and geographic center.
+   */
+  onViewChange?: (view: MapZoomView) => void;
+}
+interface UseGeoProjectionZoomDefaultizedParameters extends UseGeoProjectionZoomParameters {
+  zoom: boolean | MapZoomOptions;
+}
+/**
+ * Imperative methods shared by the plugin `instance` and the public `apiRef`.
+ */
+interface UseGeoProjectionZoomPublicApi {
+  /**
+   * Zoom the map in by a fixed step, centered on the drawing area.
+   */
+  zoomIn: () => void;
+  /**
+   * Zoom the map out by a fixed step, centered on the drawing area.
+   */
+  zoomOut: () => void;
+  /**
+   * Reset the map to the default scale and translation that fit the data in the drawing area.
+   */
+  resetZoom: () => void;
+}
+interface UseGeoProjectionZoomInstance extends UseGeoProjectionZoomPublicApi {}
+export interface UseGeoProjectionZoomState {
+  geoProjectionZoom: {
+    /**
+     * The zoom level, as a multiple of the scale that fits the data in the drawing area.
+     * `null` (the default) and `1` both mean fit-to-data. The absolute projection scale is
+     * derived as `fitScale * zoomLevel`, so this stays valid across resizes.
+     */
+    zoomLevel: number;
+    /**
+     * The geographic coordinate `[longitude, latitude]` displayed at the center of the drawing area.
+     * `null` keeps the data centered (the fit center).
+     */
+    center: [number, number];
+    /**
+     * The map translation in percentage of the drawing area.
+     */
+    translation: [number, number] | null;
+    /**
+     * The roll of the map, in degrees. `null` keeps the map upright (no roll).
+     */
+    roll: number;
+    initialTranslation: [number, number];
+    initialCenter: [number, number];
+    initialZoomLevel: number;
+    initialRoll: number;
+  };
+}
+export type UseGeoProjectionZoomSignature = ChartPluginSignature<{
+  params: UseGeoProjectionZoomParameters;
+  defaultizedParams: UseGeoProjectionZoomDefaultizedParameters;
+  publicAPI: UseGeoProjectionZoomPublicApi;
+  instance: UseGeoProjectionZoomInstance;
+  state: UseGeoProjectionZoomState;
+  dependencies: [UseGeoProjectionSignature];
+}>;
+export {};

package/internals/plugins/useGeoProjectionZoom/useGeoProjectionZoom.types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/internals/plugins/useGeoProjectionZoom/useGeoProjectionZoom.types.mjs

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

package/models/seriesType/mapShape.d.mts

@@ -94,7 +94,7 @@ export interface MapShapeSeriesType extends Omit<CommonSeriesType<'mapShape'>, '
 export type MapShapeItemIdentifier = {
   type: 'mapShape';
   seriesId: SeriesId;
-  dataIndex: number;
+  name: string;
 };
 export type DefaultizedMapShapeValueType = MapShapeValueType & {
   hidden: boolean;
@@ -102,4 +102,5 @@ export type DefaultizedMapShapeValueType = MapShapeValueType & {
 export interface DefaultizedMapShapeSeriesType extends Omit<DefaultizedProps<MapShapeSeriesType, CommonDefaultizedProps | 'color'>, 'data'> {
   hidden: boolean;
   data: ReadonlyArray<DefaultizedMapShapeValueType>;
+  lookupByName: ReadonlyMap<string, number>;
 }

package/models/seriesType/mapShape.d.ts

@@ -94,7 +94,7 @@ export interface MapShapeSeriesType extends Omit<CommonSeriesType<'mapShape'>, '
 export type MapShapeItemIdentifier = {
   type: 'mapShape';
   seriesId: SeriesId;
-  dataIndex: number;
+  name: string;
 };
 export type DefaultizedMapShapeValueType = MapShapeValueType & {
   hidden: boolean;
@@ -102,4 +102,5 @@ export type DefaultizedMapShapeValueType = MapShapeValueType & {
 export interface DefaultizedMapShapeSeriesType extends Omit<DefaultizedProps<MapShapeSeriesType, CommonDefaultizedProps | 'color'>, 'data'> {
   hidden: boolean;
   data: ReadonlyArray<DefaultizedMapShapeValueType>;
+  lookupByName: ReadonlyMap<string, number>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/x-charts-premium",
-  "version": "9.7.0",
+  "version": "9.9.0",
   "author": "MUI Team",
   "description": "The Premium plan edition of the MUI X Charts components.",
   "license": "SEE LICENSE IN LICENSE",
@@ -28,14 +28,14 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.29.7",
-    "@mui/utils": "^9.1.1",
+    "@mui/utils": "^9.2.0",
     "clsx": "^2.1.1",
     "prop-types": "^15.8.1",
-    "@mui/x-charts": "^9.7.0",
-    "@mui/x-charts-pro": "^9.7.0",
+    "@mui/x-charts": "^9.9.0",
+    "@mui/x-license": "^9.9.0",
+    "@mui/x-charts-pro": "^9.9.0",
     "@mui/x-charts-vendor": "^9.4.0",
-    "@mui/x-license": "^9.7.0",
-    "@mui/x-internals": "^9.7.0"
+    "@mui/x-internals": "^9.9.0"
   },
   "peerDependencies": {
     "@emotion/react": "^11.9.0",

package/utils/webgl/glsl.d.mts

@@ -0,0 +1,15 @@
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+export declare const ROUNDED_BOX_SDF_GLSL = "\n    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {\n      float radius;\n      if (pos.x < 0.0) {\n        radius = pos.y < 0.0 ? r.x : r.w;\n      } else {\n        radius = pos.y < 0.0 ? r.y : r.z;\n      }\n\n      vec2 q = abs(pos) - halfSize + radius;\n      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;\n    }\n  ";

package/utils/webgl/glsl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+export declare const ROUNDED_BOX_SDF_GLSL = "\n    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {\n      float radius;\n      if (pos.x < 0.0) {\n        radius = pos.y < 0.0 ? r.x : r.w;\n      } else {\n        radius = pos.y < 0.0 ? r.y : r.z;\n      }\n\n      vec2 q = abs(pos) - halfSize + radius;\n      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;\n    }\n  ";

package/utils/webgl/glsl.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ROUNDED_BOX_SDF_GLSL = void 0;
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+// language=Glsl
+const ROUNDED_BOX_SDF_GLSL = exports.ROUNDED_BOX_SDF_GLSL = /* glsl */`
+    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {
+      float radius;
+      if (pos.x < 0.0) {
+        radius = pos.y < 0.0 ? r.x : r.w;
+      } else {
+        radius = pos.y < 0.0 ? r.y : r.z;
+      }
+
+      vec2 q = abs(pos) - halfSize + radius;
+      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;
+    }
+  `;

package/utils/webgl/glsl.mjs

@@ -0,0 +1,28 @@
+/**
+ * GLSL snippet: signed distance field for a rounded box with per-corner radii.
+ *
+ * Convention:
+ *   - `pos` and `halfSize` are in the same pixel-space coordinates.
+ *   - `r` carries corner radii in CSS order: top-left, top-right, bottom-right, bottom-left.
+ *   - For uniform-radius use cases pass `vec4(scalar)`.
+ *
+ * Screen-space conventions (after the y-flip in the vertex stage):
+ *   pos.y < 0 -> top,   pos.y > 0 -> bottom
+ *   pos.x < 0 -> left,  pos.x > 0 -> right
+ *
+ * Reference: Inigo Quilez, "Distance to a rounded box".
+ */
+// language=Glsl
+export const ROUNDED_BOX_SDF_GLSL = /* glsl */`
+    float roundedBoxSDF(vec2 pos, vec2 halfSize, vec4 r) {
+      float radius;
+      if (pos.x < 0.0) {
+        radius = pos.y < 0.0 ? r.x : r.w;
+      } else {
+        radius = pos.y < 0.0 ? r.y : r.z;
+      }
+
+      vec2 q = abs(pos) - halfSize + radius;
+      return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - radius;
+    }
+  `;

package/utils/webgl/instancedAttribute.d.mts

@@ -0,0 +1,28 @@
+import type { GrowableBuffer } from "./utils.mjs";
+export interface InstancedAttribute {
+  buffer: GrowableBuffer;
+  location: number;
+  size: number;
+  glType: GLenum;
+  normalized: boolean;
+}
+/**
+ * Creates a per-instance vertex attribute backed by a fresh grow-only GPU buffer.
+ *
+ * The caller MUST have the owning VAO bound when calling this — the
+ * vertexAttribPointer + vertexAttribDivisor calls register the binding into
+ * that VAO and the program then references it on each draw.
+ */
+export declare function createInstancedAttribute(gl: WebGL2RenderingContext, program: WebGLProgram, name: string, size: number, glType?: GLenum, normalized?: boolean): InstancedAttribute;
+/**
+ * Wires up a per-instance vertex attribute that reads from an existing GrowableBuffer.
+ * Use this when the same buffer must back the same-named attribute in multiple
+ * VAOs (e.g. two shader-program variants over the same data).
+ *
+ * The caller MUST have the owning VAO bound when calling this.
+ *
+ * If the attribute is missing from the program (typo, or optimized out by the
+ * compiler), `getAttribLocation` returns -1. We skip the GL setup in that case to
+ * avoid `INVALID_VALUE` errors from `enableVertexAttribArray(-1)` and warn in dev.
+ */
+export declare function bindInstancedAttribute(gl: WebGL2RenderingContext, program: WebGLProgram, name: string, buffer: GrowableBuffer, size: number, glType?: GLenum, normalized?: boolean): InstancedAttribute;