feat(layer): add zIndex to ChartSpec for controlling layer render order

Layers in a LayerSpec now respect an optional zIndex property that controls
paint order independent of axis assignment. Default behavior is unchanged
(layers render in array order, later layers paint on top). Axis assignment
(left/right y) is always determined by array position, not zIndex.

Author: rileyhilliard

packages/core/src/types/spec.ts

@@ -875,6 +875,13 @@ export interface ChartSpec {
    * - AnimationConfig: full control via enter/update/exit phases
    */
   animation?: AnimationSpec;
+  /**
+   * Render order within a LayerSpec. Higher values render on top.
+   * When omitted, layers render in array order (later layers paint on top).
+   * Axis assignment (left/right y) is always determined by array position,
+   * not zIndex.
+   */
+  zIndex?: number;
 }
 
 /**

packages/engine/src/compile.ts

@@ -500,7 +500,15 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
     seenLabels.add(entry.label);
   }
 
-  for (const leaf of leaves) {
+  // Sort leaves by zIndex for render order while preserving original indices
+  // for axis assignment. Default zIndex is the array position.
+  const indexedLeaves = leaves.map((leaf, i) => ({
+    leaf,
+    zIndex: (leaf as ChartSpec).zIndex ?? i,
+  }));
+  indexedLeaves.sort((a, b) => a.zIndex - b.zIndex);
+
+  for (const { leaf } of indexedLeaves) {
     const leafLayout = compileChart(leaf as unknown, options);
 
     allMarks.push(...leafLayout.marks);
@@ -821,14 +829,22 @@ function compileLayerIndependent(
     }
   }
 
+  // Determine mark render order. By default, layer 0 paints first (behind),
+  // layer 1 paints second (on top). zIndex on the original leaf specs can
+  // reverse this so e.g. a line in layer 0 renders on top of bars in layer 1.
+  const z0 = leaf0.zIndex ?? 0;
+  const z1 = leaf1.zIndex ?? 1;
+  const marks =
+    z0 <= z1 ? [...adjustedMarks0, ...taggedMarks1] : [...taggedMarks1, ...adjustedMarks0];
+
   return {
     ...layout0,
     axes: {
       x: layout0.axes.x,
       y: layout0.axes.y,
       y2: y2Axis,
     },
-    marks: [...adjustedMarks0, ...taggedMarks1],
+    marks,
     legend: {
       ...layout0.legend,
       entries: mergedLegendEntries,