@defra/interactive-map 0.0.14-alpha → 0.0.16-alpha

package/src/utils/getSafeZoneInset.js

@@ -1,59 +1,156 @@
 /**
  * Calculates the safe zone inset — the unobscured region of the map viewport
- * not hidden behind overlay panels, action bars or the footer. Used as padding
- * for map operations like setCenter or fitBounds so the full extent is visible.
+ * not hidden behind overlay panels or structural UI (button columns, footer,
+ * action bar). Used as padding for map operations like fitBounds or setView
+ * so the target location or extent is fully visible.
  *
- * The algorithm measures the available space around the inset panel and decides
- * whether to push the safe area below or beside it, depending on whether the
- * layout is landscape or portrait oriented.
+ * Each edge inset is driven by:
+ *   - A structural baseline from the button columns, footer, and action bar.
+ *   - A panel contribution when panels on that edge cover more than 1/RATIO
+ *     of the available map dimension along that edge.
+ *   - A cap so no single inset exceeds 1/MAX_RATIO of the map dimension,
+ *     preventing fitBounds from zooming out to a corner when panels are large.
  *
- * @param {Object} refs - React refs for the key layout elements.
- * @param {React.RefObject} refs.mainRef - The main content area.
- * @param {React.RefObject} refs.insetRef - The inset panel (e.g. search results).
- * @param {React.RefObject} refs.leftRef - The left-hand button column.
- * @param {React.RefObject} refs.rightRef - The right-hand button column.
- * @param {React.RefObject} refs.actionsRef - The bottom action bar.
- * @param {React.RefObject} refs.footerRef - The footer (logo, copyright etc).
+ * Trigger logic per edge:
+ *   - left / right : combined HEIGHT of panels in that column vs available height
+ *   - top / bottom : WIDTH of panels in that row vs available width
+ *
+ * When a panel individually exceeds BOTH the height and width thresholds it
+ * would otherwise trigger both adjacent edges, pushing the safe zone into the
+ * opposite corner. To prevent this, such panels are classified as either
+ * "column-primary" (h/availableH ≥ w/availableW) or "row-primary" and only
+ * contribute to their dominant edge. Panels that exceed at most one threshold
+ * are never in conflict and contribute to both axes freely.
+ *
+ * @param {Object} refs - React refs from layoutRefs.
+ * @param {React.RefObject}  refs.mainRef          - Main map container.
+ * @param {React.RefObject}  refs.leftRef          - Left button column.
+ * @param {React.RefObject}  refs.rightRef         - Right button column.
+ * @param {React.RefObject}  refs.actionsRef       - Bottom action bar.
+ * @param {React.RefObject}  refs.footerRef        - Footer (logo, copyright, etc).
+ * @param {React.RefObject} [refs.leftTopRef]      - Top-left panel slot.
+ * @param {React.RefObject} [refs.leftBottomRef]   - Bottom-left panel slot.
+ * @param {React.RefObject} [refs.rightTopRef]     - Top-right panel slot.
+ * @param {React.RefObject} [refs.rightBottomRef]  - Bottom-right panel slot.
  * @returns {{ top: number, right: number, left: number, bottom: number } | undefined}
- *   Pixel insets from each edge of the main area, or undefined if any ref is missing.
+ *   Pixel insets from each edge of the main area, or undefined if any required ref is missing.
  */
+
+const RATIO = 2 // panels covering more than 1/RATIO of an edge trigger that edge's inset
+const MAX_RATIO = 3 // each inset is capped at 1/MAX_RATIO of its map dimension
+
+// Query the panel element directly within its slot container.
+// Only the first panel matters, and only when it is also the first element in the slot
+// (i.e. no buttons or other elements precede it — a panel pushed down by buttons is
+// already within the button-column structural inset and should not add extra padding).
+const getPanelDimensions = (slotRef) => {
+  if (!slotRef?.current) {
+    return { offsetWidth: 0, offsetHeight: 0 }
+  }
+  const first = slotRef.current.firstElementChild
+  if (!first?.classList.contains('im-c-panel') || first.offsetWidth === 0 || first.offsetHeight === 0) {
+    return { offsetWidth: 0, offsetHeight: 0 }
+  }
+  return { offsetWidth: first.offsetWidth, offsetHeight: first.offsetHeight }
+}
+
+// Panels are in normal flow inside slot containers, expanding left/right offsetWidth.
+// Query button groups directly to recover the button-only structural column width.
+const getButtonColWidth = (colRef) => {
+  const group = colRef?.current?.querySelector('.im-c-button-group')
+  return group ? group.offsetWidth : 0
+}
+
+// Returns the panel's contribution to column (left/right) and row (top/bottom) edges.
+//
+// A panel can only trigger BOTH adjacent edges simultaneously when it individually
+// exceeds both the height threshold (h > availableH/RATIO) and the width threshold
+// (w > availableW/RATIO). In that case, only the dominant direction is used, preventing
+// a corner panel from pushing the safe zone into the opposite corner.
+// When only one (or neither) threshold is individually exceeded, the panel contributes
+// its dimensions to both axes freely (combined thresholds still apply later).
+const panelContrib = (w, h, availableW, availableH) => {
+  const hFrac = h / availableH
+  const wFrac = w / availableW
+  if (hFrac >= 1 / RATIO && wFrac >= 1 / RATIO) {
+    return hFrac >= wFrac
+      ? { colH: h, colW: w, rowW: 0, rowH: 0 } // column-primary (left/right)
+      : { colH: 0, colW: 0, rowW: w, rowH: h } // row-primary (top/bottom)
+  }
+  return { colH: h, colW: w, rowW: w, rowH: h }
+}
+
+// Determines the column (left/right) inset and the row-axis contributions for both panels.
+//
+// Column coverage uses raw heights so that two panels whose combined height exceeds the
+// threshold always trigger the column inset, even if one is individually row-primary.
+// Exception: a single row-primary panel (no sibling, colH=0) is suppressed so it
+// contributes to top/bottom instead — giving a larger safe zone in the horizontal direction.
+// When triggered, row contributions for both panels are zeroed to prevent double-padding.
+const computeColumn = (panelA, panelB, availableW, availableH, hThreshold, columnLeft, gap) => {
+  const a = panelContrib(panelA.offsetWidth, panelA.offsetHeight, availableW, availableH)
+  const b = panelContrib(panelB.offsetWidth, panelB.offsetHeight, availableW, availableH)
+  const aSingleRowPrimary = panelB.offsetHeight === 0 && a.colH === 0
+  const bSingleRowPrimary = panelA.offsetHeight === 0 && b.colH === 0
+  const coverage = panelA.offsetHeight + panelB.offsetHeight + (panelA.offsetHeight > 0 && panelB.offsetHeight > 0 ? gap : 0)
+  const triggered = coverage > hThreshold && !aSingleRowPrimary && !bSingleRowPrimary
+  return {
+    panelInset: triggered ? columnLeft + Math.max(panelA.offsetWidth, panelB.offsetWidth) + gap : 0,
+    rowA: triggered ? { w: 0, h: 0 } : { w: a.rowW, h: a.rowH },
+    rowB: triggered ? { w: 0, h: 0 } : { w: b.rowW, h: b.rowH }
+  }
+}
+
+// Determines the row-axis (top/bottom) panel inset driven by combined panel width.
+// The combined width test subsumes the individual checks (dimensions are non-negative).
+const computeRow = (leftW, rightW, leftH, rightH, wThreshold, baseInset, gap) =>
+  leftW + rightW > wThreshold ? baseInset + Math.max(leftH, rightH) + gap : 0
+
 export const getSafeZoneInset = ({
-  mainRef,
-  insetRef,
-  leftRef,
-  rightRef,
-  actionsRef,
-  footerRef
+  mainRef, leftRef, rightRef, actionsRef, footerRef,
+  leftTopRef, leftBottomRef, rightTopRef, rightBottomRef
 }) => {
-  const refs = [mainRef, insetRef, leftRef, rightRef, actionsRef, footerRef]
-
-  if (refs.some(ref => !ref.current)) {
+  if ([mainRef, leftRef, rightRef, actionsRef, footerRef].some(ref => !ref?.current)) {
     return undefined
   }
 
-  const [main, inset, left, right, actions, footer] = refs.map(ref => ref.current)
+  const main = mainRef.current; const left = leftRef.current
+  const actions = actionsRef.current; const footer = footerRef.current
+
+  const gap = Number.parseInt(getComputedStyle(document.documentElement).getPropertyValue('--divider-gap'), 10)
+
+  const rawTL = getPanelDimensions(leftTopRef); const rawBL = getPanelDimensions(leftBottomRef)
+  const rawTR = getPanelDimensions(rightTopRef); const rawBR = getPanelDimensions(rightBottomRef)
 
-  const root = document.documentElement
-  const dividerGap = Number.parseInt(getComputedStyle(root).getPropertyValue('--divider-gap'), 10)
+  // Structural base insets — always present, never capped.
+  const colWidth = Math.max(getButtonColWidth(leftRef), getButtonColWidth(rightRef))
+  const baseLeft = main.offsetLeft + left.offsetLeft + colWidth + gap
+  const baseRight = left.offsetLeft + colWidth + gap
+  const baseTop = left.offsetTop
+  const footerInset = main.offsetHeight - footer.offsetTop + gap // mirrors --left/right-offset-bottom CSS var
+  const baseBottom = Math.max(main.offsetHeight - actions.offsetTop + gap, footerInset)
 
-  // === Safe area logic ===
-  const availableHeight = actions.offsetTop - inset.offsetTop - dividerGap
-  const leftOffset = left.offsetLeft + left.offsetWidth + dividerGap
-  const rightOffset = left.offsetLeft + right.offsetWidth + dividerGap
-  const availableWidth = main.offsetWidth - (leftOffset + rightOffset)
-  const insetOverlapWidth = inset.offsetWidth - leftOffset + left.offsetLeft
-  const isLandscape = availableWidth - insetOverlapWidth > availableHeight - inset.offsetHeight
-  const topOffset = left.offsetTop + (!isLandscape && inset.offsetHeight > 0 ? inset.offsetHeight + dividerGap : 0)
-  const combinedLeftOffset = isLandscape ? Math.max(inset.offsetWidth, left.offsetWidth) + left.offsetLeft + dividerGap : rightOffset
-  const actionsOffset = main.offsetHeight - actions.offsetTop
-  const footerOffset = main.offsetHeight - footer.offsetTop
+  const availableH = main.offsetHeight - baseTop - baseBottom
+  const availableW = main.offsetWidth - (baseLeft - main.offsetLeft) - baseRight
 
-  const RATIO = 2 // At what point is there enough room to leave the inset above
-  const hasRoom = insetOverlapWidth < availableWidth / RATIO && inset.offsetHeight < availableHeight / RATIO
+  const leftCol = computeColumn(rawTL, rawBL, availableW, availableH, availableH / RATIO, main.offsetLeft + left.offsetLeft, gap)
+  const rightCol = computeColumn(rawTR, rawBR, availableW, availableH, availableH / RATIO, left.offsetLeft, gap)
 
-  const top = hasRoom ? inset.offsetTop : topOffset
-  const combinedLeft = main.offsetLeft + (hasRoom ? rightOffset : combinedLeftOffset)
-  const bottom = Math.max(actionsOffset, footerOffset) + dividerGap
+  const leftPanelInset = leftCol.panelInset
+  const rightPanelInset = rightCol.panelInset
+  const topPanelInset = computeRow(leftCol.rowA.w, rightCol.rowA.w, leftCol.rowA.h, rightCol.rowA.h, availableW / RATIO, baseTop, gap)
+  const bottomPanelInset = computeRow(leftCol.rowB.w, rightCol.rowB.w, leftCol.rowB.h, rightCol.rowB.h, availableW / RATIO, footerInset, gap)
 
-  return { top, right: rightOffset, left: combinedLeft, bottom }
+  const usableW = main.offsetWidth - 2 * gap
+  const usableH = main.offsetHeight - 2 * gap
+  const maxL = main.offsetLeft + usableW * (MAX_RATIO - 1) / MAX_RATIO
+  const maxR = usableW * (MAX_RATIO - 1) / MAX_RATIO
+  const maxV = usableH * (MAX_RATIO - 1) / MAX_RATIO
+
+  return {
+    left: Math.max(baseLeft, Math.min(leftPanelInset, maxL)),
+    right: Math.max(baseRight, Math.min(rightPanelInset, maxR)),
+    top: Math.max(baseTop, Math.min(topPanelInset, maxV)),
+    bottom: Math.max(baseBottom, Math.min(bottomPanelInset, maxV))
+  }
 }

package/src/utils/getSafeZoneInset.test.js

@@ -1,133 +1,309 @@
 import { getSafeZoneInset } from './getSafeZoneInset'
 
-describe('getSafeZoneInset', () => {
-  let mainRef, insetRef, leftRef, rightRef, actionsRef, footerRef
-  let originalGetComputedStyle
+const MAIN_WIDTH = 900
+const MAIN_HEIGHT = 600
+const LEFT_LEFT = 10
+const LEFT_WIDTH = 40
+const LEFT_TOP = 60
+const RIGHT_WIDTH = 40
+const ACTIONS_TOP = 540
+const FOOTER_TOP = 560
+const EARLY_ACTIONS_TOP = 500
+const GAP = 8
 
-  beforeAll(() => { originalGetComputedStyle = window.getComputedStyle })
-  afterAll(() => { window.getComputedStyle = originalGetComputedStyle })
+// Base insets: main.offsetLeft=0 in tests
+const BASE_LEFT = LEFT_LEFT + LEFT_WIDTH + GAP // 58
+const BASE_RIGHT = LEFT_LEFT + RIGHT_WIDTH + GAP // 58
+const BASE_TOP = LEFT_TOP // 60
+const BASE_BOTTOM = (MAIN_HEIGHT - ACTIONS_TOP) + GAP // 68
 
-  beforeEach(() => {
-    mainRef = { current: { offsetWidth: 800, offsetHeight: 600, offsetLeft: 0 } }
-    insetRef = { current: { offsetWidth: 100, offsetHeight: 50, offsetTop: 50, offsetLeft: 20 } }
-    leftRef = { current: { offsetWidth: 50, offsetLeft: 20, offsetTop: 10 } }
-    rightRef = { current: { offsetWidth: 50, offsetLeft: 730 } }
-    actionsRef = { current: { offsetTop: 520 } }
-    footerRef = { current: { offsetTop: 550 } }
+// Height threshold: availableHeight / RATIO = (600-60-68)/2 = 236
+const ABOVE_THRESHOLD = 240
+const BELOW_THRESHOLD = 230
+const COMBINED_ABOVE = 120 // two × 120 + gap = 248 > 236
+const COMBINED_BELOW = 100 // two × 100 + gap = 208 < 236
 
-    // CSS var mock
-    window.getComputedStyle = jest.fn().mockReturnValue({ getPropertyValue: () => '10' })
+// Width threshold: availableWidth / RATIO = (900-58-58)/2 = 392
+const ABOVE_W_THRESHOLD = 400
+const COMBINED_ABOVE_W = 200 // two × 200 = 400 > 392 → triggers combined
+const COMBINED_BELOW_W = 180 // two × 180 = 360 < 392 → does not trigger
+const PANEL_H_TALL = 150
+const PANEL_H_SHORT = 100
+
+const ABOVE_CAP_TOP = 330 // 60+330+8=398 > CAP_HEIGHT ≈ 389.3 → capped
+const FOOTER_INSET = MAIN_HEIGHT - FOOTER_TOP + GAP // 48
+const ABOVE_CAP_BOTTOM = 342 // 48+342+8=398 > CAP_HEIGHT → capped
+
+const PANEL_W_STANDARD = 200
+const PANEL_W_WIDE = 250
+const PANEL_W_NARROW = 100
+const PANEL_W_XLARGE = 600 // 10+600+8=618 > CAP_WIDTH ≈ 589.3 → capped
+
+const leftInset = w => LEFT_LEFT + w + GAP
+const rightInset = w => LEFT_LEFT + w + GAP
+const topInset = h => BASE_TOP + h + GAP
+
+const MAX_RATIO = 3
+const CAP_WIDTH = (MAIN_WIDTH - 2 * GAP) * (MAX_RATIO - 1) / MAX_RATIO
+const CAP_HEIGHT = (MAIN_HEIGHT - 2 * GAP) * (MAX_RATIO - 1) / MAX_RATIO
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+let mainRef, leftRef, rightRef, actionsRef, footerRef
+
+beforeAll(() => {
+  globalThis.getComputedStyle = jest.fn().mockReturnValue({ getPropertyValue: () => String(GAP) })
+})
+
+const colRef = (offsetWidth, offsetLeft, offsetTop) => {
+  const buttonGroup = { offsetWidth }
+  return {
+    current: {
+      offsetWidth,
+      offsetLeft,
+      offsetTop,
+      querySelector: (sel) => sel === '.im-c-button-group' ? buttonGroup : null
+    }
+  }
+}
+
+beforeEach(() => {
+  mainRef = { current: { offsetWidth: MAIN_WIDTH, offsetHeight: MAIN_HEIGHT, offsetLeft: 0 } }
+  leftRef = colRef(LEFT_WIDTH, LEFT_LEFT, LEFT_TOP)
+  rightRef = colRef(RIGHT_WIDTH)
+  actionsRef = { current: { offsetTop: ACTIONS_TOP } }
+  footerRef = { current: { offsetTop: FOOTER_TOP } }
+})
+
+const base = () => ({ mainRef, leftRef, rightRef, actionsRef, footerRef })
+
+// Slot container where an .im-c-panel is the first element child.
+const panel = (offsetWidth, offsetHeight) => {
+  const panelEl = { offsetWidth, offsetHeight, classList: { contains: (c) => c === 'im-c-panel' } }
+  return { current: { firstElementChild: panelEl } }
+}
+
+// Slot container where a button precedes the panel (panel should be ignored).
+const panelAfterButton = () => ({ current: { firstElementChild: { classList: { contains: () => false } } } })
+
+// ─── Missing refs ────────────────────────────────────────────────────────────
+
+describe('getSafeZoneInset — missing refs', () => {
+  it('returns undefined when mainRef.current is null', () => {
+    expect(getSafeZoneInset({ ...base(), mainRef: { current: null } })).toBeUndefined()
+  })
+  it('returns undefined when leftRef.current is null', () => {
+    expect(getSafeZoneInset({ ...base(), leftRef: { current: null } })).toBeUndefined()
+  })
+  it('returns undefined when actionsRef is undefined', () => {
+    expect(getSafeZoneInset({ mainRef, leftRef, rightRef, footerRef })).toBeUndefined()
   })
+})
+
+// ─── Base structural insets ──────────────────────────────────────────────────
+
+describe('getSafeZoneInset — base structural insets', () => {
+  it('returns base insets when no panel refs are provided', () => {
+    expect(getSafeZoneInset(base())).toEqual({
+      left: BASE_LEFT, right: BASE_RIGHT, top: BASE_TOP, bottom: BASE_BOTTOM
+    })
+  })
+  it('ignores a panel that is not the first element in its slot (buttons precede it)', () => {
+    expect(getSafeZoneInset({ ...base(), leftTopRef: panelAfterButton() }).left).toBe(BASE_LEFT)
+  })
+  it('ignores a slot container with no children', () => {
+    expect(getSafeZoneInset({ ...base(), leftTopRef: { current: { firstElementChild: null } } }).left).toBe(BASE_LEFT)
+  })
+  it('ignores a panel with zero width', () => {
+    expect(getSafeZoneInset({ ...base(), leftTopRef: panel(0, ABOVE_THRESHOLD) }).left).toBe(BASE_LEFT)
+  })
+  it('uses zero button width when column ref has no button group', () => {
+    const noGroupLeft = { current: { offsetWidth: 0, offsetLeft: LEFT_LEFT, offsetTop: LEFT_TOP, querySelector: () => null } }
+    const noGroupRight = { current: { offsetWidth: 0, offsetLeft: 0, offsetTop: 0, querySelector: () => null } }
+    expect(getSafeZoneInset({ mainRef, leftRef: noGroupLeft, rightRef: noGroupRight, actionsRef, footerRef })).toEqual({
+      left: LEFT_LEFT + GAP, right: LEFT_LEFT + GAP, top: LEFT_TOP, bottom: BASE_BOTTOM
+    })
+  })
+  it('returns base insets when all panel slots are empty (height 0)', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      leftTopRef: panel(PANEL_W_STANDARD, 0),
+      leftBottomRef: panel(PANEL_W_STANDARD, 0),
+      rightTopRef: panel(PANEL_W_STANDARD, 0),
+      rightBottomRef: panel(PANEL_W_STANDARD, 0)
+    })).toEqual({ left: BASE_LEFT, right: BASE_RIGHT, top: BASE_TOP, bottom: BASE_BOTTOM })
+  })
+  it('uses max of actions and footer for base bottom', () => {
+    actionsRef.current.offsetTop = EARLY_ACTIONS_TOP
+    expect(getSafeZoneInset(base()).bottom).toBe(MAIN_HEIGHT - EARLY_ACTIONS_TOP + GAP)
+  })
+})
+
+// ─── Left edge ───────────────────────────────────────────────────────────────
 
-  it('returns undefined if any ref.current is null', () => {
+describe('getSafeZoneInset — left edge', () => {
+  it('does not trigger when single panel height is below threshold', () => {
+    expect(getSafeZoneInset({ ...base(), leftTopRef: panel(PANEL_W_STANDARD, BELOW_THRESHOLD) }).left).toBe(BASE_LEFT)
+  })
+  it('triggers when single panel height exceeds threshold', () => {
+    expect(getSafeZoneInset({ ...base(), leftTopRef: panel(PANEL_W_STANDARD, ABOVE_THRESHOLD) }).left)
+      .toBe(leftInset(PANEL_W_STANDARD))
+  })
+  it('triggers when combined height of two panels exceeds threshold', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      leftTopRef: panel(PANEL_W_STANDARD, COMBINED_ABOVE),
+      leftBottomRef: panel(PANEL_W_NARROW, COMBINED_ABOVE)
+    }).left).toBe(leftInset(PANEL_W_STANDARD))
+  })
+  it('does not trigger when combined height is below threshold', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      leftTopRef: panel(PANEL_W_STANDARD, COMBINED_BELOW),
+      leftBottomRef: panel(PANEL_W_STANDARD, COMBINED_BELOW)
+    }).left).toBe(BASE_LEFT)
+  })
+  it('uses the wider panel for the inset amount', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      leftTopRef: panel(PANEL_W_WIDE, COMBINED_ABOVE),
+      leftBottomRef: panel(PANEL_W_NARROW, COMBINED_ABOVE)
+    }).left).toBe(leftInset(PANEL_W_WIDE))
+  })
+})
+
+// ─── Right edge ──────────────────────────────────────────────────────────────
+
+describe('getSafeZoneInset — right edge', () => {
+  it('triggers when combined height of right-column panels exceeds threshold', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      rightTopRef: panel(PANEL_W_STANDARD, COMBINED_ABOVE),
+      rightBottomRef: panel(PANEL_W_NARROW, COMBINED_ABOVE)
+    }).right).toBe(rightInset(PANEL_W_STANDARD))
+  })
+  it('does not trigger when combined height is below threshold', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      rightTopRef: panel(PANEL_W_STANDARD, COMBINED_BELOW),
+      rightBottomRef: panel(PANEL_W_STANDARD, COMBINED_BELOW)
+    }).right).toBe(BASE_RIGHT)
+  })
+})
+
+// ─── Top edge ────────────────────────────────────────────────────────────────
+// Trigger is WIDTH-based. A narrow panel must not add top padding even if tall.
+
+describe('getSafeZoneInset — top edge', () => {
+  it('does not trigger when top panel is narrow, even if tall', () => {
+    // PANEL_W_STANDARD (200) < width threshold (392)
+    expect(getSafeZoneInset({ ...base(), rightTopRef: panel(PANEL_W_STANDARD, ABOVE_THRESHOLD) }).top).toBe(BASE_TOP)
+  })
+  it('triggers when a top panel width exceeds threshold', () => {
+    expect(getSafeZoneInset({ ...base(), leftTopRef: panel(ABOVE_W_THRESHOLD, ABOVE_THRESHOLD) }).top)
+      .toBe(topInset(ABOVE_THRESHOLD))
+  })
+  it('column-primary wide-and-tall top panel triggers left inset, not top', () => {
+    // panel(400,330): h/availableH≈0.699 > w/availableW≈0.510 → column-primary
+    const result = getSafeZoneInset({ ...base(), leftTopRef: panel(ABOVE_W_THRESHOLD, ABOVE_CAP_TOP) })
+    expect(result.left).toBe(leftInset(ABOVE_W_THRESHOLD))
+    expect(result.top).toBe(BASE_TOP)
+  })
+  it('when top panels have mixed primaries, each contributes to its own edge', () => {
+    // tl(400,100): row-primary → top; tr(400,330): column-primary → right
+    const result = getSafeZoneInset({
+      ...base(),
+      leftTopRef: panel(ABOVE_W_THRESHOLD, COMBINED_BELOW),
+      rightTopRef: panel(ABOVE_W_THRESHOLD, ABOVE_CAP_TOP)
+    })
+    expect(result.top).toBe(topInset(COMBINED_BELOW))
+    expect(result.right).toBe(rightInset(ABOVE_W_THRESHOLD))
+  })
+  it('triggers when combined width of two top panels exceeds threshold; uses max height', () => {
+    // each COMBINED_ABOVE_W (200) < threshold (392), but 200+200=400 > 392
+    expect(getSafeZoneInset({
+      ...base(),
+      leftTopRef: panel(COMBINED_ABOVE_W, PANEL_H_TALL),
+      rightTopRef: panel(COMBINED_ABOVE_W, PANEL_H_SHORT)
+    }).top).toBe(topInset(PANEL_H_TALL))
+  })
+  it('does not trigger when both top panels are below combined width threshold', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      leftTopRef: panel(COMBINED_BELOW_W, ABOVE_THRESHOLD),
+      rightTopRef: panel(COMBINED_BELOW_W, ABOVE_THRESHOLD)
+    }).top).toBe(BASE_TOP)
+  })
+})
+
+// ─── Bottom edge ─────────────────────────────────────────────────────────────
+
+describe('getSafeZoneInset — bottom edge', () => {
+  it('does not trigger when bottom panel is narrow, even if tall', () => {
+    expect(getSafeZoneInset({ ...base(), rightBottomRef: panel(PANEL_W_STANDARD, ABOVE_THRESHOLD) }).bottom).toBe(BASE_BOTTOM)
+  })
+  it('triggers when a bottom panel width exceeds threshold', () => {
+    expect(getSafeZoneInset({ ...base(), leftBottomRef: panel(ABOVE_W_THRESHOLD, ABOVE_THRESHOLD) }).bottom)
+      .toBe(Math.min(FOOTER_INSET + ABOVE_THRESHOLD + GAP, CAP_HEIGHT))
+  })
+  it('column-primary wide-and-tall bottom panel triggers left inset, not bottom', () => {
+    // panel(400,342): h/availableH≈0.724 > w/availableW≈0.510 → column-primary
+    const result = getSafeZoneInset({ ...base(), leftBottomRef: panel(ABOVE_W_THRESHOLD, ABOVE_CAP_BOTTOM) })
+    expect(result.left).toBe(leftInset(ABOVE_W_THRESHOLD))
+    expect(result.bottom).toBe(BASE_BOTTOM)
+  })
+  it('triggers when combined width of two bottom panels exceeds threshold; uses max height', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      leftBottomRef: panel(COMBINED_ABOVE_W, PANEL_H_TALL),
+      rightBottomRef: panel(COMBINED_ABOVE_W, PANEL_H_SHORT)
+    }).bottom).toBe(Math.min(FOOTER_INSET + PANEL_H_TALL + GAP, CAP_HEIGHT))
+  })
+  it('does not trigger when both bottom panels are below combined width threshold', () => {
+    expect(getSafeZoneInset({
+      ...base(),
+      leftBottomRef: panel(COMBINED_BELOW_W, ABOVE_THRESHOLD),
+      rightBottomRef: panel(COMBINED_BELOW_W, ABOVE_THRESHOLD)
+    }).bottom).toBe(BASE_BOTTOM)
+  })
+})
+
+// ─── MAX_RATIO cap ────────────────────────────────────────────────────────────
+
+describe('getSafeZoneInset — MAX_RATIO cap', () => {
+  it('caps left inset at (MAX_RATIO-1)/MAX_RATIO of usable width', () => {
+    expect(getSafeZoneInset({ ...base(), leftTopRef: panel(PANEL_W_XLARGE, PANEL_W_XLARGE) }).left).toBe(CAP_WIDTH)
+  })
+  it('caps right inset at (MAX_RATIO-1)/MAX_RATIO of usable width', () => {
+    expect(getSafeZoneInset({ ...base(), rightTopRef: panel(PANEL_W_XLARGE, PANEL_W_XLARGE) }).right).toBe(CAP_WIDTH)
+  })
+})
+
+// ─── Corner panel independence ────────────────────────────────────────────────
+
+describe('getSafeZoneInset — corner panel independence', () => {
+  it('narrow-but-tall corner panel triggers side inset only (not top)', () => {
+    // PANEL_W_STANDARD (200): tall enough for right, too narrow for top (< 392)
+    const result = getSafeZoneInset({ ...base(), rightTopRef: panel(PANEL_W_STANDARD, ABOVE_THRESHOLD) })
+    expect(result.right).toBe(rightInset(PANEL_W_STANDARD))
+    expect(result.top).toBe(BASE_TOP)
+  })
+  it('wide-and-tall corner panel triggers only its primary (row) edge inset', () => {
+    // panel(400, 240): w/availableW≈0.510, h/availableH≈0.508 → row-primary → top only
+    const result = getSafeZoneInset({ ...base(), leftTopRef: panel(ABOVE_W_THRESHOLD, ABOVE_THRESHOLD) })
+    expect(result.left).toBe(BASE_LEFT)
+    expect(result.top).toBe(topInset(ABOVE_THRESHOLD))
+  })
+  it('two wide panels in the same column collectively trigger left but not top or bottom', () => {
+    // Each h=COMBINED_ABOVE (120) < hThreshold individually, combined 248 > 236
+    // Each w=ABOVE_W_THRESHOLD (400) > wThreshold → left column triggers, excluding from top/bottom
     const result = getSafeZoneInset({
-      mainRef: { current: null },
-      insetRef,
-      leftRef,
-      rightRef,
-      actionsRef,
-      footerRef
+      ...base(),
+      leftTopRef: panel(ABOVE_W_THRESHOLD, COMBINED_ABOVE),
+      leftBottomRef: panel(ABOVE_W_THRESHOLD, COMBINED_ABOVE)
     })
-    expect(result).toBeUndefined()
-  })
-
-  it('portrait mode shifts inset below itself when it does NOT have enough vertical room', () => {
-    // Mock layout
-    mainRef.current.offsetWidth = 200
-    mainRef.current.offsetHeight = 200
-    insetRef.current.offsetWidth = 100
-    insetRef.current.offsetHeight = 50
-    insetRef.current.offsetTop = 50
-    insetRef.current.offsetLeft = 20
-
-    leftRef.current.offsetWidth = 50
-    leftRef.current.offsetLeft = 10
-    leftRef.current.offsetTop = 10
-
-    rightRef.current.offsetWidth = 50
-    rightRef.current.offsetLeft = 140
-
-    actionsRef.current.offsetTop = 150
-    footerRef.current.offsetTop = 180
-
-    const dividerGap = 10
-
-    const result = getSafeZoneInset({ mainRef, insetRef, leftRef, rightRef, actionsRef, footerRef })
-
-    // Compute expected values exactly as function would
-    const availableHeight = actionsRef.current.offsetTop - insetRef.current.offsetTop - dividerGap // 150 - 50 - 10 = 90
-    const leftOffset = leftRef.current.offsetLeft + leftRef.current.offsetWidth + dividerGap // 10 + 50 + 10 = 70
-    const rightOffset = leftRef.current.offsetLeft + rightRef.current.offsetWidth + dividerGap // 10 + 50 + 10 = 70
-    const availableWidth = mainRef.current.offsetWidth - (leftOffset + rightOffset) // 200 - (70+70) = 60
-    const insetOverlapWidth = insetRef.current.offsetWidth - leftOffset + leftRef.current.offsetLeft // 100 - 70 + 10 = 40
-    const isLandscape = availableWidth - insetOverlapWidth > availableHeight - insetRef.current.offsetHeight // 60-40 > 90-50 => 20>40 false
-
-    const topOffset = leftRef.current.offsetTop + (!isLandscape && insetRef.current.offsetHeight > 0 ? insetRef.current.offsetHeight + dividerGap : 0) // 10 + 50 +10 = 70
-    const combinedLeftOffset = isLandscape ? Math.max(insetRef.current.offsetWidth, leftRef.current.offsetWidth) + leftRef.current.offsetLeft + dividerGap : rightOffset // isLandscape=false -> 70
-    const actionsOffset = mainRef.current.offsetHeight - actionsRef.current.offsetTop // 200-150=50
-    const footerOffset = mainRef.current.offsetHeight - footerRef.current.offsetTop // 200-180=20
-    const hasRoom = insetOverlapWidth < availableWidth / 2 && insetRef.current.offsetHeight < availableHeight / 2 // 40 < 60/2? 40<30 false
-
-    const expectedTop = hasRoom ? insetRef.current.offsetTop : topOffset // false -> topOffset = 70
-    const expectedLeft = mainRef.current.offsetLeft + (hasRoom ? rightOffset : combinedLeftOffset) // 0+70=70
-    const expectedRight = rightOffset // 70
-    const expectedBottom = Math.max(actionsOffset, footerOffset) + dividerGap // max(50,20)+10 = 60
-
-    expect(result.top).toBe(expectedTop)
-    expect(result.left).toBe(expectedLeft)
-    expect(result.right).toBe(expectedRight)
-    expect(result.bottom).toBe(expectedBottom)
-  })
-
-  it('landscape mode places inset beside panel when enough room', () => {
-    mainRef.current.offsetWidth = 1000
-    insetRef.current.offsetWidth = 200
-    insetRef.current.offsetHeight = 50
-
-    const result = getSafeZoneInset({ mainRef, insetRef, leftRef, rightRef, actionsRef, footerRef })
-
-    const dividerGap = 10
-    const leftOffset = leftRef.current.offsetLeft + leftRef.current.offsetWidth + dividerGap
-    const rightOffset = leftRef.current.offsetLeft + rightRef.current.offsetWidth + dividerGap
-    const availableWidth = mainRef.current.offsetWidth - (leftOffset + rightOffset)
-    const insetOverlapWidth = insetRef.current.offsetWidth - leftOffset + leftRef.current.offsetLeft
-    const availableHeight = actionsRef.current.offsetTop - insetRef.current.offsetTop - dividerGap
-    const isLandscape = availableWidth - insetOverlapWidth > availableHeight - insetRef.current.offsetHeight
-
-    const topOffset = leftRef.current.offsetTop + (!isLandscape && insetRef.current.offsetHeight > 0 ? insetRef.current.offsetHeight + dividerGap : 0)
-    const combinedLeftOffset = isLandscape ? Math.max(insetRef.current.offsetWidth, leftRef.current.offsetWidth) + leftRef.current.offsetLeft + dividerGap : rightOffset
-    const actionsOffset = mainRef.current.offsetHeight - actionsRef.current.offsetTop
-    const footerOffset = mainRef.current.offsetHeight - footerRef.current.offsetTop
-    const hasRoom = insetOverlapWidth < availableWidth / 2 && insetRef.current.offsetHeight < availableHeight / 2
-    const top = hasRoom ? insetRef.current.offsetTop : topOffset
-    const combinedLeft = mainRef.current.offsetLeft + (hasRoom ? rightOffset : combinedLeftOffset)
-    const bottom = Math.max(actionsOffset, footerOffset) + dividerGap
-
-    expect(result.top).toBe(top)
-    expect(result.left).toBe(combinedLeft)
-    expect(result.right).toBe(rightOffset)
-    expect(result.bottom).toBe(bottom)
-  })
-
-  it('portrait mode with zero inset height leaves top unchanged', () => {
-    insetRef.current.offsetHeight = 0
-    mainRef.current.offsetWidth = 500
-    insetRef.current.offsetWidth = 100
-
-    const result = getSafeZoneInset({ mainRef, insetRef, leftRef, rightRef, actionsRef, footerRef })
-    expect(result.top).toBe(insetRef.current.offsetTop)
-  })
-
-  it('calculates correct bottom using max of actions and footer offsets', () => {
-    mainRef.current.offsetHeight = 600
-    actionsRef.current.offsetTop = 500
-    footerRef.current.offsetTop = 550
-
-    const result = getSafeZoneInset({ mainRef, insetRef, leftRef, rightRef, actionsRef, footerRef })
-
-    const dividerGap = 10
-    const expectedBottom = Math.max(mainRef.current.offsetHeight - actionsRef.current.offsetTop,
-      mainRef.current.offsetHeight - footerRef.current.offsetTop) + dividerGap
-    expect(result.bottom).toBe(expectedBottom)
+    expect(result.left).toBe(leftInset(ABOVE_W_THRESHOLD))
+    expect(result.top).toBe(BASE_TOP)
+    expect(result.bottom).toBe(BASE_BOTTOM)
   })
 })

package/src/utils/logger.js

@@ -0,0 +1,6 @@
+const PREFIX = '[interactive-map]'
+
+export const logger = {
+  warn: (...args) => console.warn(PREFIX, ...args),
+  error: (...args) => console.error(PREFIX, ...args)
+}