@genome-spy/core 0.78.0 → 0.79.1

package/dist/src/view/gridView/gridView.js

@@ -2,6 +2,8 @@ import { primaryPositionalChannels } from "../../encoder/encoder.js";
 import {
     FlexDimensions,
     getLargestSize,
+    getSizeDefMaxPx,
+    getSizeDefMinPx,
     mapToPixelCoords,
     parseSizeDef,
     ZERO_SIZEDEF,
@@ -9,7 +11,11 @@ import {
 import Grid from "../layout/grid.js";
 import Padding from "../layout/padding.js";
 import Rectangle from "../layout/rectangle.js";
-import AxisView, { CHANNEL_ORIENTS, ORIENT_CHANNELS } from "../axisView.js";
+import AxisView, {
+    CHANNEL_ORIENTS,
+    ORIENT_CHANNELS,
+    getExternalAxisOverhang,
+} from "../axisView.js";
 import ContainerView from "../containerView.js";
 import {
     propagateInteraction,
@@ -20,9 +26,26 @@ import UnitView from "../unitView.js";
 import { interactionToZoom } from "../zoom.js";
 import GridChild from "./gridChild.js";
 import KeyboardZoomController from "./keyboardZoomController.js";
+import { renderLocalLegends } from "./legendLayout.js";
+import {
+    addLegendView,
+    createGridChildLegend,
+    disposeLegendViews,
+    getLegendOverhang,
+    getOrderedLegendEntries,
+    iterateLegendViews,
+    isActiveLegendRegion,
+} from "./gridChildLegends.js";
 import SeparatorView, { resolveSeparatorProps } from "./separatorView.js";
 import { getZoomableResolutions } from "./zoomNavigationUtils.js";
+import { moveArrayItem } from "../../utils/arrayUtils.js";
 import { isHConcatSpec, isVConcatSpec } from "../viewSpecGuards.js";
+import {
+    clipCoords,
+    combineClipOptions,
+    createClipOptions,
+    normalizeClipOptions,
+} from "../renderingContext/clipOptions.js";
 
 // Secondary ordering within a z-index bucket for GridView-owned decorations.
 // These are not z-indices themselves: actual layering is decided first by the
@@ -34,6 +57,7 @@ const DECORATION_ORDER = Object.freeze({
     grid: 20,
     backgroundStroke: 30,
     axis: 40,
+    legend: 50,
     selectionRect: 80,
     scrollbar: 90,
     title: 100,
@@ -44,6 +68,80 @@ const DECORATION_ORDER = Object.freeze({
 // letting an explicit user zindex override the default.
 const CLIPPED_DECORATION_ZINDEX = 10;
 
+/**
+ * Legends are rendered as guide regions, not grid children. Their thickness is
+ * handled as overhang, but their parallel min/max constraints still affect the
+ * grid dimension that the parent concat sees.
+ *
+ * @param {import("./gridChildLegends.js").GridChildLegends} legends
+ * @returns {FlexDimensions}
+ */
+function getLegendParallelSizeConstraints(legends) {
+    /** @type {import("../layout/flexLayout.js").SizeDef[]} */
+    const widths = [];
+    /** @type {import("../layout/flexLayout.js").SizeDef[]} */
+    const heights = [];
+
+    for (const [orient, region] of Object.entries(legends)) {
+        if (!isActiveLegendRegion(region)) {
+            continue;
+        }
+
+        const size = region.legendView.getSize();
+        if (orient == "top" || orient == "bottom") {
+            widths.push(size.width);
+        } else {
+            // Side gradients can fill the available viewport height, but that
+            // available height must be determined by the real grid children and
+            // top/bottom chrome. Otherwise a shared right/left legend can make
+            // the grid grow to the browser height and then fill that height.
+            heights.push({ px: getSizeDefMinPx(size.height), grow: 0 });
+        }
+    }
+
+    return new FlexDimensions(getLargestSize(widths), getLargestSize(heights));
+}
+
+/**
+ * Treat an explicit concat/grid size as preferred available space while still
+ * letting fixed children and guide chrome establish a larger minimum. This
+ * mirrors flexbox behavior more closely than treating the explicit size as a
+ * hard clipping bound.
+ *
+ * @param {import("../layout/flexLayout.js").SizeDef} preferred
+ * @param {import("../layout/flexLayout.js").SizeDef} content
+ * @returns {import("../layout/flexLayout.js").SizeDef}
+ */
+function combinePreferredAndContentSize(preferred, content) {
+    const preferredGrow = preferred.grow ?? 0;
+    const preferredPx = preferred.px ?? 0;
+    const minPx = Math.max(
+        getSizeDefMinPx(preferred),
+        getSizeDefMinPx(content)
+    );
+
+    if (!preferredGrow) {
+        return { px: Math.max(preferredPx, minPx), grow: 0 };
+    }
+
+    /** @type {import("../layout/flexLayout.js").SizeDef} */
+    const size = {
+        px: Math.max(preferredPx, content.px ?? 0),
+        grow: preferredGrow,
+    };
+
+    if (minPx > (size.px ?? 0)) {
+        size.minPx = minPx;
+    }
+
+    const preferredMaxPx = getSizeDefMaxPx(preferred);
+    if (preferredMaxPx !== undefined && preferredMaxPx >= minPx) {
+        size.maxPx = preferredMaxPx;
+    }
+
+    return size;
+}
+
 /**
  * Modeled after: https://vega.github.io/vega/docs/layout/
  *
@@ -97,6 +195,9 @@ export default class GridView extends ContainerView {
      */
     #sharedAxes = {};
 
+    /** @type {import("./gridChildLegends.js").GridChildLegends} */
+    #sharedLegends = {};
+
     #childSerial = 0;
 
     /** @type {Partial<Record<"horizontal" | "vertical", SeparatorView>>} */
@@ -223,6 +324,17 @@ export default class GridView extends ContainerView {
         this.invalidateSizeCache();
     }
 
+    /**
+     * Moves a child within the grid without disposing it.
+     *
+     * @param {number} fromIndex
+     * @param {number} index Destination index after temporarily removing the child.
+     */
+    moveChildAt(fromIndex, index) {
+        moveArrayItem(this.#children, fromIndex, index);
+        this.invalidateSizeCache();
+    }
+
     get #visibleChildren() {
         return this.#children.filter((gridChild) =>
             gridChild.view.isConfiguredVisible()
@@ -275,10 +387,25 @@ export default class GridView extends ContainerView {
      * @protected
      */
     async createAxes() {
+        await this.syncGuideViews();
+    }
+
+    /**
+     * Recreates guide and chrome views that depend on the child hierarchy.
+     * Shared guides always depend on the whole container. Grid-child guides can
+     * be limited to newly inserted children during mutations.
+     *
+     * @param {{ gridChildren?: GridChild[] }} [options]
+     */
+    async syncGuideViews(options = {}) {
+        const gridChildren = options.gridChildren ?? this.#children;
+
         await this.syncSharedAxes();
+        await this.syncSharedLegends();
         await Promise.all(
-            this.#children.map((gridChild) => gridChild.createAxes())
+            gridChildren.map((gridChild) => gridChild.createAxes())
         );
+        this.invalidateSizeCache();
     }
 
     /**
@@ -325,6 +452,25 @@ export default class GridView extends ContainerView {
         await Promise.all(promises);
     }
 
+    /**
+     * Recreates shared legends based on current legend resolutions.
+     *
+     * Shared legends are GridView-owned for the same reason as shared axes:
+     * their placement is relative to the whole child grid, not any individual
+     * GridChild.
+     */
+    async syncSharedLegends() {
+        disposeLegendViews(this.#sharedLegends);
+        this.#sharedLegends = {};
+
+        for (const { definition, resolution } of getOrderedLegendEntries([
+            this,
+        ])) {
+            const legend = await createGridChildLegend(definition, this);
+            await addLegendView(this.#sharedLegends, legend, resolution);
+        }
+    }
+
     /**
      * @returns {IterableIterator<View>}
      */
@@ -340,6 +486,8 @@ export default class GridView extends ContainerView {
         for (const axisView of Object.values(this.#sharedAxes)) {
             yield axisView;
         }
+
+        yield* iterateLegendViews(this.#sharedLegends);
     }
 
     /**
@@ -367,17 +515,48 @@ export default class GridView extends ContainerView {
                 })
                 .reduce((a, b) => Math.max(a, b), 0);
 
+        /**
+         * @param {GridChild} child
+         * @returns {import("../layout/flexLayout.js").SizeDef}
+         */
+        const getPlotSize = (child) => {
+            // External overhang is represented by axis/padding slots. The
+            // growable view slot should contain only the child's plot area.
+            const size = child.view.getViewportSize()[dim];
+            const overhang = child.view.getOverhang();
+            const overhangSize =
+                direction == "column" ? overhang.width : overhang.height;
+
+            const plotSize = {
+                px: Math.max((size.px ?? 0) - overhangSize, 0),
+                grow: size.grow,
+                minPx:
+                    size.minPx === undefined
+                        ? undefined
+                        : Math.max(size.minPx - overhangSize, 0),
+                maxPx:
+                    size.maxPx === undefined
+                        ? undefined
+                        : Math.max(size.maxPx - overhangSize, 0),
+            };
+
+            const legendSize = getLegendParallelSizeConstraints(child.legends);
+            // Side legends constrain row height, while top/bottom legends
+            // constrain column width. Their perpendicular size is overhang.
+            return getLargestSize([
+                plotSize,
+                direction == "column" ? legendSize.width : legendSize.height,
+            ]);
+        };
+
         return this._cache(`size/directionSizes/${direction}`, () =>
             this.#grid[direction == "column" ? "colIndices" : "rowIndices"].map(
                 (col) => ({
                     axisBefore: getMaxAxisSize(col, 0),
                     axisAfter: getMaxAxisSize(col, 1),
                     view: getLargestSize(
-                        col.map(
-                            (rowIndex) =>
-                                this.#visibleChildren[
-                                    rowIndex
-                                ].view.getViewportSize()[dim]
+                        col.map((rowIndex) =>
+                            getPlotSize(this.#visibleChildren[rowIndex])
                         )
                     ),
                 })
@@ -448,12 +627,21 @@ export default class GridView extends ContainerView {
     #getFlexSize(direction) {
         let grow = 0;
         let px = 0;
+        let minPx = 0;
+        let maxPx = 0;
+        let hasMaxPx = true;
 
         const explicitSize =
             direction == "row" ? this.spec.height : this.spec.width;
-        if (explicitSize || explicitSize === 0) {
-            return parseSizeDef(explicitSize);
-        }
+        const preferredSize =
+            explicitSize || explicitSize === 0
+                ? parseSizeDef(explicitSize)
+                : undefined;
+        const usePreferredAsViewSlot =
+            preferredSize &&
+            (direction == "column"
+                ? this.#grid.colIndices.length == 1
+                : this.#grid.rowIndices.length == 1);
 
         const sizes = this.#getSizes(direction);
 
@@ -461,6 +649,8 @@ export default class GridView extends ContainerView {
             if (i > 0) {
                 // Spacing
                 px += this.#spacing;
+                minPx += this.#spacing;
+                maxPx += this.#spacing;
             }
 
             if (i == 0 || this.wrappingFacet) {
@@ -470,13 +660,28 @@ export default class GridView extends ContainerView {
 
             // Axis/padding
             px += size.axisBefore;
+            minPx += size.axisBefore;
+            maxPx += size.axisBefore;
 
             // View
-            px += size.view.px ?? 0;
-            grow += size.view.grow ?? 0;
+            const viewSize = usePreferredAsViewSlot
+                ? combinePreferredAndContentSize(preferredSize, size.view)
+                : size.view;
+            px += viewSize.px ?? 0;
+            grow += viewSize.grow ?? 0;
+            minPx += getSizeDefMinPx(viewSize);
+
+            const viewMaxPx = getSizeDefMaxPx(viewSize);
+            if (viewMaxPx === undefined) {
+                hasMaxPx = false;
+            } else {
+                maxPx += viewMaxPx;
+            }
 
             // Axis/padding
             px += size.axisAfter;
+            minPx += size.axisAfter;
+            maxPx += size.axisAfter;
 
             if (i == sizes.length - 1 || this.wrappingFacet) {
                 //Footer
@@ -484,7 +689,16 @@ export default class GridView extends ContainerView {
             }
         }
 
-        return { px, grow };
+        const measuredSize = {
+            px,
+            grow,
+            minPx: minPx || undefined,
+            maxPx: sizes.length && hasMaxPx ? maxPx : undefined,
+        };
+
+        return preferredSize && !usePreferredAsViewSlot
+            ? combinePreferredAndContentSize(preferredSize, measuredSize)
+            : measuredSize;
     }
 
     /**
@@ -505,7 +719,7 @@ export default class GridView extends ContainerView {
      * @return {Padding}
      */
     getOverhang() {
-        return this.#getGridOverhang().union(this.#getSharedAxisOverhang());
+        return this.#getGridOverhang().add(this.#getSharedGuideOverhang());
     }
 
     #getGridOverhang() {
@@ -535,11 +749,7 @@ export default class GridView extends ContainerView {
                 return 0;
             }
 
-            return Math.max(
-                axisView.getPerpendicularSize() +
-                    (axisView.axisProps.offset ?? 0),
-                0
-            );
+            return getExternalAxisOverhang(axisView);
         };
 
         return new Padding(
@@ -550,16 +760,58 @@ export default class GridView extends ContainerView {
         );
     }
 
+    #getSharedLegendOverhang() {
+        const getSharedLegendSize = (
+            /** @type {import("../../spec/legend.js").LegendOrient} */ orient
+        ) => getLegendOverhang(this.#sharedLegends, orient);
+
+        return new Padding(
+            getSharedLegendSize("top"),
+            getSharedLegendSize("right"),
+            getSharedLegendSize("bottom"),
+            getSharedLegendSize("left")
+        );
+    }
+
+    #getSharedGuideOverhang() {
+        return this.#getSharedAxisOverhang().add(
+            this.#getSharedLegendOverhang()
+        );
+    }
+
+    #getSharedAxesByOrient() {
+        /** @type {Partial<Record<import("../../spec/axis.js").AxisOrient, AxisView>>} */
+        const axes = {};
+        for (const axisView of Object.values(this.#sharedAxes)) {
+            axes[axisView.axisProps.orient] = axisView;
+        }
+
+        return axes;
+    }
+
     /**
      * @returns {FlexDimensions}
      */
     getSize() {
-        return this._cache("size", () =>
-            new FlexDimensions(
-                this.#getFlexSize("column"),
-                this.#getFlexSize("row")
-            ).addPadding(this.#getSharedAxisOverhang())
-        );
+        return this._cache("size", () => {
+            const parallelLegendSize = getLegendParallelSizeConstraints(
+                this.#sharedLegends
+            );
+
+            // Shared legends are placed around the whole grid, so combine their
+            // parallel constraints with the child-grid size before adding
+            // guide overhang.
+            return new FlexDimensions(
+                getLargestSize([
+                    this.#getFlexSize("column"),
+                    parallelLegendSize.width,
+                ]),
+                getLargestSize([
+                    this.#getFlexSize("row"),
+                    parallelLegendSize.height,
+                ])
+            ).addPadding(this.#getSharedGuideOverhang());
+        });
     }
 
     /**
@@ -578,7 +830,8 @@ export default class GridView extends ContainerView {
             // Usually padding is applied by the parent GridView, but if this is the root view, we need to apply it here
             coords = coords.shrink(this.getPadding());
         }
-        coords = coords.shrink(this.#getSharedAxisOverhang());
+        const sharedGuideOverhang = this.#getSharedGuideOverhang();
+        coords = coords.shrink(sharedGuideOverhang);
 
         context.pushView(this, coords);
 
@@ -587,7 +840,7 @@ export default class GridView extends ContainerView {
         const flexOpts = {
             devicePixelRatio,
         };
-        const columnFlexCoords = mapToPixelCoords(
+        let columnFlexCoords = mapToPixelCoords(
             this.#makeFlexItems("column"),
             coords.width,
             flexOpts
@@ -604,6 +857,33 @@ export default class GridView extends ContainerView {
             this.#columns ?? Infinity
         );
 
+        let columnLayoutDirty = false;
+        for (const [i, gridChild] of this.#visibleChildren.entries()) {
+            const [col, row] = grid.getCellCoords(i);
+            const colLocSize =
+                columnFlexCoords[this.#getViewSlot("column", col)];
+            const rowLocSize = rowFlexCoords[this.#getViewSlot("row", row)];
+
+            // Some child views have side overhang that depends on the final
+            // row height, such as SampleView's repeated y-axis threshold. Row
+            // slots are known here, but final columns may need one more pass if
+            // a child reports that its height-dependent overhang changed.
+            const layoutChanged =
+                /** @type {{ prepareLayoutSize?: (width: number, height: number) => boolean }} */ (
+                    gridChild.view
+                ).prepareLayoutSize?.(colLocSize.size, rowLocSize.size);
+            columnLayoutDirty ||= layoutChanged === true;
+        }
+
+        if (columnLayoutDirty) {
+            this._invalidateCacheByPrefix("size/directionSizes/column");
+            columnFlexCoords = mapToPixelCoords(
+                this.#makeFlexItems("column"),
+                coords.width,
+                flexOpts
+            );
+        }
+
         /** @param {number} x */
         const round = (x) =>
             Math.round(x * devicePixelRatio) / devicePixelRatio;
@@ -641,16 +921,36 @@ export default class GridView extends ContainerView {
             /**
              * @param {FlexDimensions} size
              * @param {"width" | "height"} dimension
+             * @param {boolean} explicitViewport
              */
-            const getLen = (size, dimension) =>
-                (size[dimension].grow
-                    ? (dimension == "width" ? colLocSize : rowLocSize).size
-                    : size[dimension].px) + overhang[dimension];
-
-            const viewportWidth = getLen(viewportSize, "width");
-            const viewportHeight = getLen(viewportSize, "height");
-            const viewWidth = getLen(viewSize, "width");
-            const viewHeight = getLen(viewSize, "height");
+            const getLen = (size, dimension, explicitViewport = false) =>
+                explicitViewport
+                    ? size[dimension].grow
+                        ? (dimension == "width" ? colLocSize : rowLocSize).size
+                        : size[dimension].px
+                    : (dimension == "width" ? colLocSize : rowLocSize).size +
+                      overhang[dimension];
+
+            const viewportWidth = getLen(
+                viewportSize,
+                "width",
+                view.spec.viewportWidth != null
+            );
+            const viewportHeight = getLen(
+                viewportSize,
+                "height",
+                view.spec.viewportHeight != null
+            );
+            const viewWidth = getLen(
+                viewSize,
+                "width",
+                view.spec.viewportWidth != null
+            );
+            const viewHeight = getLen(
+                viewSize,
+                "height",
+                view.spec.viewportHeight != null
+            );
 
             const hScrollbar = gridChild.scrollbars.horizontal;
             const vScrollbar = gridChild.scrollbars.vertical;
@@ -684,9 +984,8 @@ export default class GridView extends ContainerView {
 
             gridChild.coords = viewportCoords;
 
-            const clippedChildCoords = options.clipRect
-                ? viewportCoords.intersect(options.clipRect)
-                : viewportCoords;
+            const parentClip = normalizeClipOptions(options);
+            const visibleChildCoords = clipCoords(viewportCoords, parentClip);
 
             renderItems.push({
                 col,
@@ -700,7 +999,8 @@ export default class GridView extends ContainerView {
                 selectionRect,
                 viewportCoords,
                 viewCoords,
-                clippedChildCoords,
+                parentClip,
+                visibleChildCoords,
                 viewWidth,
                 viewHeight,
                 scrollable,
@@ -755,7 +1055,7 @@ export default class GridView extends ContainerView {
                     () =>
                         item.background?.render(
                             context,
-                            item.clippedChildCoords,
+                            item.visibleChildCoords,
                             {
                                 ...options,
                                 clipRect: undefined,
@@ -809,7 +1109,8 @@ export default class GridView extends ContainerView {
                 selectionRect,
                 viewportCoords,
                 viewCoords,
-                clippedChildCoords,
+                parentClip,
+                visibleChildCoords,
                 viewWidth,
                 viewHeight,
                 scrollable,
@@ -818,7 +1119,9 @@ export default class GridView extends ContainerView {
                 row,
             } = item;
 
-            const clipped = isClippedChildren(view) || scrollable;
+            const clippedChildren = isClippedChildren(view);
+            const clipped = clippedChildren || scrollable;
+            const clippedDecorations = hasClippedChildren(view) || scrollable;
 
             for (const gridLineView of Object.values(gridLines)) {
                 queueDecoration(
@@ -828,6 +1131,19 @@ export default class GridView extends ContainerView {
                 );
             }
 
+            const childClip = clipped
+                ? combineClipOptions(
+                      parentClip,
+                      createClipOptions(
+                          visibleChildCoords,
+                          clippedChildren ||
+                              Boolean(gridChild.scrollbars.horizontal),
+                          clippedChildren ||
+                              Boolean(gridChild.scrollbars.vertical)
+                      )
+                  )
+                : options.clip;
+
             const renderContent = () =>
                 view.render(
                     context,
@@ -835,7 +1151,8 @@ export default class GridView extends ContainerView {
                     clipped
                         ? {
                               ...options,
-                              clipRect: clippedChildCoords,
+                              clipRect: childClip?.rect,
+                              clip: childClip,
                           }
                         : options
                 );
@@ -846,11 +1163,11 @@ export default class GridView extends ContainerView {
                 queueDecoration(
                     defaultBackgroundStrokeZindex(
                         gridChild.backgroundStrokeZindex,
-                        clipped
+                        clippedDecorations
                     ),
                     DECORATION_ORDER.backgroundStroke,
                     () =>
-                        backgroundStroke?.render(context, clippedChildCoords, {
+                        backgroundStroke?.render(context, visibleChildCoords, {
                             ...options,
                             clipRect: undefined,
                         })
@@ -888,39 +1205,51 @@ export default class GridView extends ContainerView {
                     axisView
                 );
 
-                let clipRect = options.clipRect;
+                let clip = normalizeClipOptions(options);
+                let clipRect = clip?.rect;
 
                 // Scrollable axes must be clipped along the scroll direction.
                 if (scrollable) {
-                    clipRect = translatedCoords.intersect(clipRect).intersect(
-                        scrollable
-                            ? viewportCoords.modify(
-                                  // Ugly hack. Need to implement intersectX and intersectY.
-                                  direction == "vertical"
-                                      ? {
-                                            x: -100000,
-                                            width: 200000,
-                                        }
-                                      : {
-                                            y: -100000,
-                                            height: 200000,
-                                        }
-                              )
-                            : undefined
+                    const axisClip = createClipOptions(
+                        viewportCoords,
+                        direction == "horizontal",
+                        direction == "vertical"
+                    );
+                    clip = combineClipOptions(clip, axisClip);
+                    clipRect = clip?.rect;
+                }
+
+                if (clip && axisView.labelClipPolicy === "anchor") {
+                    clip = createClipOptions(
+                        clip.rect,
+                        ORIENT_CHANNELS[orient] === "x",
+                        ORIENT_CHANNELS[orient] === "y"
                     );
+                    clipRect = clip?.rect;
                 }
 
                 queueDecoration(
-                    defaultAxisZindex(axisView.axisProps.zindex, clipped),
+                    defaultAxisZindex(axisView.axisProps, clippedDecorations),
                     DECORATION_ORDER.axis,
                     () =>
                         axisView.render(context, translatedCoords, {
                             ...options,
                             clipRect,
+                            clip,
                         })
                 );
             }
 
+            renderLocalLegends(
+                gridChild.legends,
+                this.#getLegendOffsetAxes(axes, col, row, grid),
+                viewportCoords,
+                context,
+                options,
+                queueDecoration,
+                DECORATION_ORDER.legend
+            );
+
             // Axes shared between children
             // TODO: What if some have scrollable viewports?
             // Should throw an error because cannot have shared axes in such cases.
@@ -934,7 +1263,10 @@ export default class GridView extends ContainerView {
                     (orient == "bottom" && row == grid.nRows - 1)
                 ) {
                     queueDecoration(
-                        defaultAxisZindex(axisView.axisProps.zindex, clipped),
+                        defaultAxisZindex(
+                            axisView.axisProps,
+                            clippedDecorations
+                        ),
                         DECORATION_ORDER.axis,
                         () =>
                             axisView.render(
@@ -969,13 +1301,24 @@ export default class GridView extends ContainerView {
 
             if (title) {
                 queueDecoration(
-                    gridChild.titleZindex,
+                    gridChild.getTitleZindex(),
                     DECORATION_ORDER.title,
-                    () => title?.render(context, viewportCoords, options)
+                    () =>
+                        gridChild.renderTitle(context, viewportCoords, options)
                 );
             }
         }
 
+        renderLocalLegends(
+            this.#sharedLegends,
+            this.#getSharedAxesByOrient(),
+            coords,
+            context,
+            options,
+            queueDecoration,
+            DECORATION_ORDER.legend
+        );
+
         renderDecorations(underlays);
 
         for (const renderContent of contents) {
@@ -987,6 +1330,38 @@ export default class GridView extends ContainerView {
         context.popView(this);
     }
 
+    /**
+     * Local legends are GridChild-owned, but shared axes are GridView-owned.
+     * When they share an orient, the axis should remain next to the plot and
+     * the legend should move outside it. Give legend placement the applicable
+     * shared edge axes so `renderLocalLegends()` can apply the same offset it
+     * already uses for local axes.
+     *
+     * @param {Partial<Record<import("../../spec/axis.js").AxisOrient, AxisView>>} axes
+     * @param {number} col
+     * @param {number} row
+     * @param {Grid} grid
+     */
+    #getLegendOffsetAxes(axes, col, row, grid) {
+        /** @type {Partial<Record<import("../../spec/axis.js").AxisOrient, AxisView>>} */
+        const offsetAxes = { ...axes };
+
+        for (const axisView of Object.values(this.#sharedAxes)) {
+            const orient = axisView.axisProps.orient;
+            const isEdge =
+                (orient == "left" && col == 0) ||
+                (orient == "right" && col == grid.nCols - 1) ||
+                (orient == "top" && row == 0) ||
+                (orient == "bottom" && row == grid.nRows - 1);
+
+            if (isEdge && !offsetAxes[orient]) {
+                offsetAxes[orient] = axisView;
+            }
+        }
+
+        return offsetAxes;
+    }
+
     /**
      * @param {import("../../utils/interaction.js").default} event
      */
@@ -1302,6 +1677,22 @@ export function isClippedChildren(view) {
     return clipped;
 }
 
+/**
+ * @param {View} view
+ */
+function hasClippedChildren(view) {
+    let clipped = false;
+
+    view.visit((v) => {
+        if (v instanceof UnitView) {
+            const clip = v.mark.properties.clip;
+            clipped ||= clip === true || clip === "x" || clip === "y";
+        }
+    });
+
+    return clipped;
+}
+
 /**
  * @param {View} view
  * @returns {boolean}
@@ -1337,15 +1728,24 @@ function getSeparatorDirections(spec) {
 }
 
 /**
- * Default z-index for axes. Clipped or scrollable content gets a higher
+ * Default z-index for axes. Inside axes default to overlays because they share
+ * plot space with marks. Clipped or scrollable outside axes get a higher
  * default to keep guides above visible edge artifacts.
  *
- * @param {number | undefined} zindex
+ * @param {import("../../spec/axis.js").Axis} axisProps
  * @param {boolean} clipped
  * @returns {number}
  */
-function defaultAxisZindex(zindex, clipped) {
-    return zindex ?? (clipped ? CLIPPED_DECORATION_ZINDEX : 0);
+function defaultAxisZindex(axisProps, clipped) {
+    if (axisProps.zindex !== undefined) {
+        return axisProps.zindex;
+    } else if (axisProps.placement === "inside") {
+        return 1;
+    } else if (clipped) {
+        return CLIPPED_DECORATION_ZINDEX;
+    } else {
+        return 0;
+    }
 }
 
 /**
@@ -1369,18 +1769,30 @@ function defaultBackgroundStrokeZindex(zindex, clipped) {
 export function translateAxisCoords(coords, orient, axisView) {
     const props = axisView.axisProps;
     const ps = axisView.getPerpendicularSize();
+    const inside = props.placement === "inside";
+    const offset = props.offset ?? 0;
 
     if (orient == "bottom") {
-        return coords
-            .translate(0, coords.height + props.offset)
-            .modify({ height: ps });
+        return inside
+            ? coords.translate(0, coords.height - ps - offset).modify({
+                  height: ps,
+              })
+            : coords.translate(0, coords.height + offset).modify({
+                  height: ps,
+              });
     } else if (orient == "top") {
-        return coords.translate(0, -ps - props.offset).modify({ height: ps });
+        return inside
+            ? coords.translate(0, offset).modify({ height: ps })
+            : coords.translate(0, -ps - offset).modify({ height: ps });
     } else if (orient == "left") {
-        return coords.translate(-ps - props.offset, 0).modify({ width: ps });
+        return inside
+            ? coords.translate(offset, 0).modify({ width: ps })
+            : coords.translate(-ps - offset, 0).modify({ width: ps });
     } else if (orient == "right") {
-        return coords
-            .translate(coords.width + props.offset, 0)
-            .modify({ width: ps });
+        return inside
+            ? coords.translate(coords.width - ps - offset, 0).modify({
+                  width: ps,
+              })
+            : coords.translate(coords.width + offset, 0).modify({ width: ps });
     }
 }