fix(library): harden overlay controls API

Author: FelixTJDietrich

docs/library/api.md

@@ -43,8 +43,10 @@ import "@tumaet/apollon/style.css"
 Container, lifecycle, and two layers of editor options.
 
 **Container.** `className`, `style` (needs an explicit non-zero height), and
-`children` rendered alongside the canvas inside the editor's context
-provider.
+`children` rendered inside the editor's context provider. Omitting `children`
+renders the default palette, zoom, and minimap; passing children makes the chrome
+composition explicit, so include `<ApollonDefaultControls />` when custom children
+should keep the default controls.
 
 **Theming.** `theme` (a `--apollon-*` token object, typically from
 `createApollonTheme(...)`) and `dataTheme` (`"light" | "dark"`) are spread onto

docs/library/api/overlay-controls.md

@@ -9,8 +9,8 @@ description: Floating canvas chrome in named regions — React, imperative, and
 Apollon renders an editor's chrome — toolbars, palettes, rails, banners — as
 **floating controls anchored in named regions** of the canvas, not as separate
 bars stacked around it. Host chrome and the editor's own overlays share one
-collision-free layer, so they never overlap and the diagram knows how to make
-room for them.
+measured layout layer, so bands, rails, and corner controls deconflict through the
+same rules and the diagram knows how to make room for reserving chrome.
 
 A control is positioned by **region** (where it sits) and can optionally
 **reserve space** so the diagram "makes way" for it. Reservation is measured, not
@@ -61,11 +61,17 @@ overlay store — only real option changes (region, inset, order, …) push an
 update.
 
 ```tsx no-check
-import { Apollon, ApollonControl, UMLDiagramType } from "@tumaet/apollon"
+import {
+  Apollon,
+  ApollonControl,
+  ApollonDefaultControls,
+  UMLDiagramType,
+} from "@tumaet/apollon"
 
 function Editor() {
   return (
     <Apollon defaultType={UMLDiagramType.ClassDiagram}>
+      <ApollonDefaultControls />
       <ApollonControl id="my-app:export" region="top-right" groupLabel="Export">
         <button type="button" onClick={exportDiagram}>
           Export
@@ -79,7 +85,10 @@ function Editor() {
 `ApollonControlProps` is [`OverlayControlOptions`](#overlaycontroloptions) plus
 `children: ReactNode`. The component renders `null` in the host tree; the visible
 output is the portaled `children`. The `id` must be stable — changing it
-re-registers a fresh control.
+re-registers a fresh control. Supplying children to `<Apollon>` means you own the
+composition; include `<ApollonDefaultControls />` (or the individual
+`<Apollon.Palette />`, `<Apollon.Zoom />`, `<Apollon.MiniMap />`) when a custom
+child should keep the default chrome visible.
 
 ## The imperative way: `addControl`
 
@@ -127,8 +136,10 @@ reserved ids (`PALETTE_ID`, `ZOOM_ID`, `MINIMAP_ID`). You compose them the same
 two ways.
 
 **React — as `<Apollon>` children.** Presence renders, omission hides, typed
-props reconfigure. Passing _any_ children opts out of the defaults, so you list
-exactly the chrome you want (an empty composition is a bare canvas).
+props reconfigure. Passing _any_ children makes the composition explicit, so you
+list exactly the chrome you want. Use `<ApollonDefaultControls />` to keep the
+standard palette + zoom + minimap next to custom children; pass `null` or an empty
+fragment for a bare canvas.
 
 ```tsx no-check
 import { Apollon, UMLDiagramType } from "@tumaet/apollon"
@@ -343,12 +354,12 @@ control never drags the diagram.
   `region="bottom-right"` with `inset={{ bottom: "auto" }}` instead: the diagram
   still reserves bottom room for the island, but unrelated bottom-left chrome
   stays flush.
-- **Corners clear full-width bands, not empty rail columns.** Top/bottom corner
+- **Corners clear full-width bands and same-side rails.** Top/bottom corner
   controls sit below a header and above a footer structurally. Side rails share
-  the side track with the corner slots, so short rails leave bottom/top corners
-  flush instead of reserving an empty column. The built-in minimap uses the same
-  corner slots, so it stacks with host controls in its region instead of applying
-  its own side offsets.
+  the side track with the corner slots and are padded by the measured same-side
+  corner extent, so short rails leave corners flush while tall rails avoid covering
+  them. The built-in minimap uses the same corner slots, so it stacks with host
+  controls in its region instead of applying its own side offsets.
 - **Selection-anchored toolbars** — `<Apollon.SelectionToolbar>` (Figma/tldraw
   style): a screen-space, constant-size toolbar that follows the current selection.
   Distinct from `on-canvas`, which lives in diagram space and scales with zoom.

library/lib/apollon-editor.tsx

@@ -41,6 +41,7 @@ import {
 import { createOverlayStore, type OverlayStore } from "./overlay/overlayStore"
 import {
   assertBuiltInControlRegion,
+  preserveBuiltInControlKind,
   defaultControls,
 } from "./chrome/builtins/controls"
 import { mergeLabels } from "./i18n/labels"
@@ -415,11 +416,16 @@ export class ApollonEditor {
       throw new Error(
         `[ApollonEditor] updateControl: unknown region: ${patch.region}`
       )
-    if (patch.region !== undefined) {
-      assertBuiltInControlRegion(id, patch.region)
-    }
     // Pin id last so a stray `patch.id` can't fork the control under a new key.
-    this.overlayStore.getState().register({ ...existing, ...patch, id })
+    const next = { ...existing, ...patch, id }
+    // Built-in descriptors carry a private renderer-kind marker so their own
+    // runtime updates stay within the regions their renderers support. Replacing
+    // the renderer intentionally drops that marker: a host control at PALETTE_ID /
+    // MINIMAP_ID is a normal control and can move to any valid region.
+    if (patch.render === undefined) preserveBuiltInControlKind(existing, next)
+    if (patch.region !== undefined)
+      assertBuiltInControlRegion(next, patch.region)
+    this.overlayStore.getState().register(next)
   }
 
   /**

library/lib/chrome/builtins/controls.tsx

@@ -68,10 +68,45 @@ function assertBuiltInRegion(
   }
 }
 
-export function assertBuiltInControlRegion(id: string, region: string): void {
-  if (id === PALETTE_ID) {
+const BUILT_IN_CONTROL_KIND = Symbol("apollon-built-in-control")
+type BuiltInControlKind = "palette" | "minimap"
+type BuiltInControlInput = OverlayControlInput & {
+  [BUILT_IN_CONTROL_KIND]?: BuiltInControlKind
+}
+
+function markBuiltIn<T extends OverlayControlInput>(
+  control: T,
+  kind: BuiltInControlKind
+): T {
+  Object.defineProperty(control, BUILT_IN_CONTROL_KIND, {
+    value: kind,
+    enumerable: false,
+  })
+  return control
+}
+
+function builtInKind(
+  control: OverlayControlInput
+): BuiltInControlKind | undefined {
+  return (control as BuiltInControlInput)[BUILT_IN_CONTROL_KIND]
+}
+
+export function preserveBuiltInControlKind(
+  from: OverlayControlInput,
+  to: OverlayControlInput
+): OverlayControlInput {
+  const kind = builtInKind(from)
+  return kind ? markBuiltIn(to, kind) : to
+}
+
+export function assertBuiltInControlRegion(
+  control: OverlayControlInput,
+  region: string
+): void {
+  const kind = builtInKind(control)
+  if (kind === "palette") {
     assertBuiltInRegion("paletteControl", region, PALETTE_REGIONS)
-  } else if (id === MINIMAP_ID) {
+  } else if (kind === "minimap") {
     assertBuiltInRegion("miniMapControl", region, MINIMAP_REGIONS)
   }
 }
@@ -81,12 +116,15 @@ export function paletteControl(
 ): OverlayControlInput {
   const region = options.region ?? "left-rail"
   assertBuiltInRegion("paletteControl", region, PALETTE_REGIONS)
-  return {
-    ...options,
-    id: PALETTE_ID,
-    region,
-    render: () => <Sidebar />,
-  }
+  return markBuiltIn(
+    {
+      ...options,
+      id: PALETTE_ID,
+      region,
+      render: () => <Sidebar />,
+    },
+    "palette"
+  )
 }
 
 export function zoomControl({
@@ -134,12 +172,15 @@ export function miniMapControl({
   ...placement
 }: MiniMapControlOptions = {}): OverlayControlInput {
   assertBuiltInRegion("miniMapControl", region, MINIMAP_REGIONS)
-  return {
-    ...placement,
-    id: MINIMAP_ID,
-    region,
-    render: () => <BuiltInMiniMap pannable={pannable} zoomable={zoomable} />,
-  }
+  return markBuiltIn(
+    {
+      ...placement,
+      id: MINIMAP_ID,
+      region,
+      render: () => <BuiltInMiniMap pannable={pannable} zoomable={zoomable} />,
+    },
+    "minimap"
+  )
 }
 
 /** The editor's default chrome — palette, zoom/history cluster, minimap. */

library/lib/chrome/useRovingToolbar.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, type KeyboardEvent } from "react"
+import { useCallback, useLayoutEffect, useRef, type KeyboardEvent } from "react"
 
 /** Enabled, focusable buttons in DOM (left→right) order. */
 function focusableButtons(el: HTMLElement): HTMLButtonElement[] {
@@ -30,7 +30,7 @@ function syncTabStops(el: HTMLElement) {
 export function useRovingToolbar<T extends HTMLElement = HTMLDivElement>() {
   const ref = useRef<T>(null)
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     const el = ref.current
     if (!el) return
     syncTabStops(el)

library/lib/components/CustomMiniMap.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react"
+import { useMemo, useState, type CSSProperties } from "react"
 import {
   MiniMap,
   MiniMapNodeProps,
@@ -129,6 +129,17 @@ export const CustomMiniMap = ({
     canvasWidth > 0 && canvasWidth < MINIMAP_EXPAND_MIN_WIDTH
 
   const panelPositionClasses = position.replace("-", " ")
+  const managedCollapseStyle = useMemo<CSSProperties>(() => {
+    const [vertical, horizontal] = position.split("-") as [
+      "top" | "bottom",
+      "left" | "center" | "right",
+    ]
+    return {
+      position: "absolute",
+      [vertical]: 0,
+      ...(horizontal === "left" ? { left: 0 } : { right: 0 }),
+    }
+  }, [position])
 
   if (minimapCollapsed || tooNarrowToExpand) {
     const content = (
@@ -189,6 +200,7 @@ export const CustomMiniMap = ({
       {map}
       <div
         className={`react-flow__panel ${panelPositionClasses} apollon-mm-panel apollon-mm-collapse`}
+        style={managedCollapseStyle}
       >
         {collapse}
       </div>

library/lib/components/Sidebar.tsx

@@ -65,9 +65,9 @@ export const Sidebar = () => {
     [diagramType]
   )
 
-  // The palette is a rail overlay control. The rail itself stays height-stable
-  // when unrelated corner chrome moves; the palette only caps its own grid when
-  // same-side bottom chrome would otherwise overlap it in a short viewport.
+  // The palette is a rail overlay control. Generic rail/corner clearance lives in
+  // OverlayLayer; the palette only reads the rail's current content box to size
+  // its internal grid.
   const isRightRail = useOverlayStore(
     (state) => state.controls["apollon:palette"]?.region === "right-rail"
   )
@@ -81,24 +81,15 @@ export const Sidebar = () => {
     if (!aside || !band || !canvasEl) return
     const mobileQuery = window.matchMedia(MOBILE_VIEW_QUERY)
     const measure = () => {
-      // Start with the rail band's stable height, then cap it at the same-side
-      // bottom corner only when that corner is occupied. That preserves palette
-      // size-invariance for unrelated chrome (e.g. bottom-right controls do not
-      // resize a left palette) while still preventing a real same-side collision
-      // with the zoom/minimap cluster on short mobile viewports.
       const gap =
         parseFloat(
           getComputedStyle(aside).getPropertyValue("--apollon-chrome-gap")
         ) || 8
-      const bandRect = band.getBoundingClientRect()
-      const bottomRegion = isRightRail ? "bottom-right" : "bottom-left"
-      const bottomControl = canvasEl.querySelector<HTMLElement>(
-        `[data-apollon-region="${bottomRegion}"] [data-apollon-control]`
-      )
-      const bottomLimit = bottomControl
-        ? bottomControl.getBoundingClientRect().top - gap
-        : bandRect.bottom - gap
-      const h = Math.max(0, bottomLimit - bandRect.top - gap)
+      const bandStyle = getComputedStyle(band)
+      const verticalPadding =
+        (parseFloat(bandStyle.paddingTop) || 0) +
+        (parseFloat(bandStyle.paddingBottom) || 0)
+      const h = Math.max(0, band.clientHeight - verticalPadding - 2 * gap)
       const w = canvasEl.getBoundingClientRect().width
       const compact = mobileQuery.matches
       setCanvas((prev) =>
@@ -111,16 +102,12 @@ export const Sidebar = () => {
     const observer = new ResizeObserver(measure)
     observer.observe(band)
     observer.observe(canvasEl)
-    for (const region of ["bottom-left", "bottom-right"]) {
-      const corner = canvasEl.querySelector(`[data-apollon-region="${region}"]`)
-      if (corner) observer.observe(corner)
-    }
     mobileQuery.addEventListener("change", measure)
     return () => {
       observer.disconnect()
       mobileQuery.removeEventListener("change", measure)
     }
-  }, [isRightRail])
+  }, [])
 
   // The color-description element is the last grid cell.
   const cellCount = paletteItems.length + 1

library/lib/components/popovers/DefaultNodeEditPopover.tsx

@@ -3,11 +3,8 @@ import { useDiagramStore } from "@/store/context"
 import { useShallow } from "zustand/shallow"
 import { PopoverProps } from "./types"
 import { NodeStyleEditor } from "@/components/styleEditor"
-import {
-  nodeTypeLabel,
-  rendersNameLabel,
-  supportsMultilineName,
-} from "@/utils/nodeUtils"
+import { rendersNameLabel, supportsMultilineName } from "@/utils/nodeUtils"
+import { useLabels } from "@/i18n/useLabels"
 import { PopoverLayout } from "./PopoverLayout"
 
 export const DefaultNodeEditPopover: React.FC<PopoverProps> = ({
@@ -16,6 +13,7 @@ export const DefaultNodeEditPopover: React.FC<PopoverProps> = ({
   sideElements = [],
   placeholder,
 }) => {
+  const t = useLabels()
   const { nodes, setNodes } = useDiagramStore(
     useShallow((state) => ({
       nodes: state.nodes,
@@ -48,7 +46,7 @@ export const DefaultNodeEditPopover: React.FC<PopoverProps> = ({
   const nodeData = node.data as DefaultNodeProps
 
   return (
-    <PopoverLayout title={nodeTypeLabel(node.type)}>
+    <PopoverLayout title={t.nodeTypeLabel(node.type)}>
       <NodeStyleEditor
         nodeData={nodeData}
         handleDataFieldUpdate={handleDataFieldUpdate}

library/lib/components/popovers/DefaultNodeGiveFeedbackPopover.tsx

@@ -6,7 +6,6 @@ import { GiveFeedbackAssessmentBox } from "./GiveFeedbackAssessmentBox"
 import { Button } from "@tumaet/ui/components/button"
 import { useGoToNextAssessment } from "@/hooks"
 import { useLabels } from "@/i18n/useLabels"
-import { nodeTypeLabel } from "@/utils/nodeUtils"
 import { PopoverLayout } from "./PopoverLayout"
 
 export const DefaultNodeGiveFeedbackPopover = ({ elementId }: PopoverProps) => {
@@ -27,7 +26,7 @@ export const DefaultNodeGiveFeedbackPopover = ({ elementId }: PopoverProps) => {
         elementId={elementId}
         name={nodeData.name}
         elementType="node"
-        typeLabel={nodeTypeLabel(node.type)}
+        typeLabel={t.nodeTypeLabel(node.type)}
       />
       <Button variant="outline" onClick={handleGoToNextAssessment}>
         {t.nextAssessment}

library/lib/components/popovers/DefaultNodeSeeFeedbackPopover.tsx

@@ -5,7 +5,6 @@ import { PopoverProps } from "./types"
 import { SeeFeedbackAssessmentBox } from "./SeeFeedbackAssessmentBox"
 import { useGoToNextAssessment } from "@/hooks"
 import { useLabels } from "@/i18n/useLabels"
-import { nodeTypeLabel } from "@/utils/nodeUtils"
 import { Button } from "@tumaet/ui/components/button"
 import { PopoverLayout } from "./PopoverLayout"
 
@@ -25,7 +24,7 @@ export const DefaultNodeSeeFeedbackPopover = ({ elementId }: PopoverProps) => {
         elementId={elementId}
         name={nodeData.name}
         type={node.type || t.node}
-        typeLabel={nodeTypeLabel(node.type)}
+        typeLabel={t.nodeTypeLabel(node.type)}
       />
       <Button variant="outline" onClick={handleGoToNextAssessment}>
         {t.nextAssessment}