@defra/interactive-map 0.0.40-alpha → 0.0.42-alpha

package/src/App/renderer/mapButtons.test.js

@@ -1,5 +1,5 @@
 import React from 'react'
-import { mapButtons, getMatchingButtons, applySlotExclusivity, renderButton, resolveGroupName, resolveGroupLabel, resolveGroupOrder } from './mapButtons.js'
+import { mapButtons, getMatchingButtons, applySlotExclusivity, SlotButton } from './mapButtons.js'
 import { logger } from '../../services/logger.js'
 import { getPanelConfig } from '../registry/panelRegistry.js'
 
@@ -47,52 +47,6 @@ describe('mapButtons module', () => {
     getPanelConfig.mockReturnValue({})
   })
 
-  // -------------------------
-  // resolveGroup* helper tests
-  // -------------------------
-  describe('resolveGroupName', () => {
-    it('returns null when group is null or undefined', () => {
-      expect(resolveGroupName(null)).toBeNull()
-      expect(resolveGroupName(undefined)).toBeNull()
-    })
-    it('returns the string when group is a string', () => {
-      expect(resolveGroupName('g1')).toBe('g1')
-    })
-    it('returns group.name when group is an object', () => {
-      expect(resolveGroupName({ name: 'g1' })).toBe('g1')
-      expect(resolveGroupName({ name: undefined })).toBeNull()
-    })
-  })
-
-  describe('resolveGroupLabel', () => {
-    it('returns empty string when group is falsy', () => {
-      expect(resolveGroupLabel(null)).toBe('')
-      expect(resolveGroupLabel(undefined)).toBe('')
-    })
-    it('returns the string itself when group is a string', () => {
-      expect(resolveGroupLabel('My Group')).toBe('My Group')
-    })
-    it('returns group.label when provided, else group.name, else empty string', () => {
-      expect(resolveGroupLabel({ name: 'g1', label: 'Group One' })).toBe('Group One')
-      expect(resolveGroupLabel({ name: 'g1' })).toBe('g1')
-      expect(resolveGroupLabel({ order: 5 })).toBe('')
-    })
-  })
-
-  describe('resolveGroupOrder', () => {
-    it('returns 0 when group is falsy', () => {
-      expect(resolveGroupOrder(null)).toBe(0)
-      expect(resolveGroupOrder(undefined)).toBe(0)
-    })
-    it('returns 0 when group is a string', () => {
-      expect(resolveGroupOrder('g1')).toBe(0)
-    })
-    it('returns group.order when provided, else 0', () => {
-      expect(resolveGroupOrder({ name: 'g1', order: 5 })).toBe(5)
-      expect(resolveGroupOrder({ name: 'g1' })).toBe(0)
-    })
-  })
-
   // -------------------------
   // getMatchingButtons tests
   // -------------------------
@@ -156,11 +110,11 @@ describe('mapButtons module', () => {
   })
 
   // -------------------------
-  // renderButton tests
+  // SlotButton tests
   // -------------------------
-  describe('renderButton', () => {
+  describe('SlotButton', () => {
     const render = (config, state = appState) =>
-      renderButton({ btn: ['id', config], appState: state, appConfig, evaluateProp })
+      SlotButton({ buttonId: 'id', config, appState: state, appConfig, evaluateProp })
 
     it('renders a MapButton with correct basic props', () => {
       const result = render(baseBtn)
@@ -283,68 +237,85 @@ describe('mapButtons module', () => {
       expect(result[0]).toMatchObject({ id: 'b1', type: 'button', order: 1 })
     })
 
-    it('renders grouped buttons as a single group item with role=group', () => {
+    it('renders grouped buttons as a single group item with role=group, keyed by kebab-cased label', () => {
       appState.buttonConfig = ({
-        b1: { ...baseBtn, group: { name: 'g1', label: 'Group 1', order: 2 } },
-        b2: { ...baseBtn, desktop: { slot: 'header', order: 2 }, group: { name: 'g1', label: 'Group 1', order: 2 } }
+        b1: { ...baseBtn, group: { label: 'Group 1', slotOrder: 2 } },
+        b2: { ...baseBtn, desktop: { slot: 'header', order: 2 }, group: { label: 'Group 1', slotOrder: 2 } }
       })
       const result = map()
       expect(result).toHaveLength(1)
-      expect(result[0]).toMatchObject({ id: 'group-g1', type: 'group', order: 2 })
+      // stringToKebab only hyphenates camelCase boundaries, not spaces — this id is an internal
+      // React key/identifier only, never rendered as a literal DOM id, so that's harmless here.
+      expect(result[0]).toMatchObject({ id: 'group-group 1', type: 'group', order: 2 })
       expect(result[0].element.props.role).toBe('group')
       expect(result[0].element.props['aria-label']).toBe('Group 1')
     })
 
-    it('uses group name as aria-label when no explicit label is provided', () => {
+    it('merges group labels that differ only by case/whitespace into one group', () => {
       appState.buttonConfig = ({
-        b1: { ...baseBtn, group: { name: 'g1', order: 0 } },
-        b2: { ...baseBtn, group: { name: 'g1', order: 0 } }
+        b1: { ...baseBtn, group: { label: 'Zoom Controls' } },
+        b2: { ...baseBtn, group: { label: 'zoom controls' } }
       })
       const result = map()
-      expect(result[0].element.props['aria-label']).toBe('g1')
+      expect(result).toHaveLength(1)
+      // First-encountered member's raw label wins, same convention as panel tabs (groupIntoTabs.js)
+      expect(result[0].element.props['aria-label']).toBe('Zoom Controls')
     })
 
-    it('sorts group members by intra-group order', () => {
+    it('orders group members via orderItems — unordered members keep natural sequence, an ordered one splices in by position', () => {
       appState.buttonConfig = ({
-        b1: { ...baseBtn, group: { name: 'g1', order: 0 }, desktop: { slot: 'header', order: 3 } },
-        b2: { ...baseBtn, group: { name: 'g1', order: 0 }, desktop: { slot: 'header', order: 1 } },
-        b3: { ...baseBtn, group: { name: 'g1', order: 0 }, desktop: { slot: 'header', order: 2 } }
+        b1: { ...baseBtn, group: { label: 'g1' }, desktop: { slot: 'header' } },
+        b2: { ...baseBtn, group: { label: 'g1' }, desktop: { slot: 'header', order: 1 } },
+        b3: { ...baseBtn, group: { label: 'g1' }, desktop: { slot: 'header' } }
       })
-      const result = map()
-      expect(result).toHaveLength(1)
-      const children = result[0].element.props.children
-      expect(children[0].props.buttonId).toBe('b2')
-      expect(children[1].props.buttonId).toBe('b3')
-      expect(children[2].props.buttonId).toBe('b1')
+      const children = map()[0].element.props.children
+      expect(children.map(c => c.props.buttonId)).toEqual(['b2', 'b1', 'b3'])
     })
 
-    it('renders singleton groups as regular buttons using group slot order', () => {
-      appState.buttonConfig = ({ b1: { ...baseBtn, group: { name: 'g1', label: 'Group 1', order: 3 } } })
+    it('renders singleton groups as regular buttons using the group\'s slot order', () => {
+      appState.buttonConfig = ({ b1: { ...baseBtn, group: { label: 'Group 1', slotOrder: 3 } } })
       const result = map()
       expect(result).toHaveLength(1)
       expect(result[0]).toMatchObject({ id: 'b1', type: 'button', order: 3 })
     })
 
-    it('falls back to breakpoint order for singleton group when group order is 0', () => {
-      appState.buttonConfig = ({ b1: { ...baseBtn, desktop: { slot: 'header', order: 4 }, group: { name: 'g1', order: 0 } } })
-      expect(map()[0].order).toBe(4)
+    it('does not fall back to the button\'s own breakpoint order when group slotOrder is explicitly 0', () => {
+      appState.buttonConfig = ({ b1: { ...baseBtn, desktop: { slot: 'header', order: 4 }, group: { label: 'g1', slotOrder: 0 } } })
+      expect(map()[0].order).toBe(0)
     })
 
-    it('falls back to 0 for singleton group when both group order and breakpoint order are absent', () => {
-      appState.buttonConfig = ({ b1: { ...baseBtn, desktop: { slot: 'header' }, group: { name: 'g1', order: 0 } } })
+    it('falls back to 0 for singleton group when group slotOrder is absent', () => {
+      appState.buttonConfig = ({ b1: { ...baseBtn, desktop: { slot: 'header' }, group: { label: 'g1' } } })
       expect(map()[0].order).toBe(0)
     })
 
-    it('sorts group members treating missing breakpoint order as 0', () => {
+    it('warns in dev mode when group members declare inconsistent slotOrder values, using the first one encountered', () => {
       appState.buttonConfig = ({
-        b1: { ...baseBtn, group: { name: 'g1', order: 0 }, desktop: { slot: 'header', order: 2 } },
-        b2: { ...baseBtn, group: { name: 'g1', order: 0 }, desktop: { slot: 'header' } },
-        b3: { ...baseBtn, group: { name: 'g1', order: 0 }, desktop: { slot: 'header', order: 1 } }
+        b1: { ...baseBtn, group: { label: 'g1', slotOrder: 2 } },
+        b2: { ...baseBtn, desktop: { slot: 'header', order: 1 }, group: { label: 'g1', slotOrder: 5 } }
       })
-      const children = map()[0].element.props.children
-      expect(children[0].props.buttonId).toBe('b2')
-      expect(children[1].props.buttonId).toBe('b3')
-      expect(children[2].props.buttonId).toBe('b1')
+      const result = map()
+      expect(result[0].order).toBe(2)
+      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('inconsistent slotOrder values'))
+    })
+
+    it('does not warn when group members agree on slotOrder', () => {
+      appState.buttonConfig = ({
+        b1: { ...baseBtn, group: { label: 'g1', slotOrder: 2 } },
+        b2: { ...baseBtn, desktop: { slot: 'header', order: 1 }, group: { label: 'g1', slotOrder: 2 } }
+      })
+      map()
+      expect(logger.warn).not.toHaveBeenCalled()
+    })
+
+    it('mixes grouped and ungrouped buttons in the same slot', () => {
+      appState.buttonConfig = ({
+        solo: { ...baseBtn, desktop: { slot: 'header', order: 1 } },
+        b1: { ...baseBtn, group: { label: 'g1' }, desktop: { slot: 'header' } },
+        b2: { ...baseBtn, group: { label: 'g1' }, desktop: { slot: 'header' } }
+      })
+      const result = map()
+      expect(result.map(r => r.id).sort()).toEqual(['group-g1', 'solo'])
     })
 
     it('falls back to order 0 when order is not specified in breakpoint config', () => {
@@ -404,5 +375,18 @@ describe('mapButtons module', () => {
       expect(result).toHaveLength(1)
       expect(result[0].id).toBe('parent')
     })
+
+    // Actions.jsx (the 'actions' slot wrapper) reads isHidden/variant directly off each slot
+    // item's top-level element props via React.Children.toArray — these two guard that contract.
+    it('carries isHidden as a top-level prop on the slot element, not just inside MapButton', () => {
+      appState.buttonConfig = ({ b1: baseBtn })
+      appState.hiddenButtons = new Set(['b1'])
+      expect(map()[0].element.props.isHidden).toBe(true)
+    })
+
+    it('carries variant as a top-level prop on the slot element, not just inside MapButton', () => {
+      appState.buttonConfig = ({ b1: { ...baseBtn, variant: 'touch' } })
+      expect(map()[0].element.props.variant).toBe('touch')
+    })
   })
 })

package/src/App/renderer/mapControls.js

@@ -28,7 +28,9 @@ export function mapControls ({ slot, appState, evaluateProp }) {
         return false
       }
 
-      const slotAllowed = allowedSlots.control.includes(bpConfig.slot)
+      // A control may also target a panel's body directly via the `<panelId>-panel`
+      // slot convention (mirrors the `<buttonId>-button` convention panels already use).
+      const slotAllowed = allowedSlots.control.includes(bpConfig.slot) || bpConfig.slot?.endsWith('-panel')
       const inModeWhitelist = control.includeModes?.includes(mode) ?? true
       const inExcludeModes = control.excludeModes?.includes(mode) ?? false
 
@@ -72,6 +74,7 @@ export function mapControls ({ slot, appState, evaluateProp }) {
         id: control.id,
         type: 'control',
         order: control[breakpoint]?.order ?? 0,
+        tab: control[breakpoint]?.tab,
         element
       }
     })

package/src/App/renderer/mapControls.test.js

@@ -164,4 +164,36 @@ describe('mapControls', () => {
     const result = mapControls({ slot: 'header', appState: defaultAppState, evaluateProp: (p) => p })
     expect(result.map(c => c.id)).toEqual(['ctrl1'])
   })
+
+  it('matches a control targeting a panel-body slot via the <panelId>-panel convention', () => {
+    defaultAppState.controlConfig = ({
+      ctrl1: { id: 'ctrl1', desktop: { slot: 'map-styles-panel', order: 1 }, includeModes: ['view'] }
+    })
+    const result = mapControls({ slot: 'map-styles-panel', appState: defaultAppState, evaluateProp: (p) => p })
+    expect(result.map(c => c.id)).toEqual(['ctrl1'])
+  })
+
+  it('does not match a panel-body-targeting control against an unrelated slot', () => {
+    defaultAppState.controlConfig = ({
+      ctrl1: { id: 'ctrl1', desktop: { slot: 'map-styles-panel', order: 1 }, includeModes: ['view'] }
+    })
+    const result = mapControls({ slot: 'header', appState: defaultAppState, evaluateProp: (p) => p })
+    expect(result).toEqual([])
+  })
+
+  it('passes through the tab field from the breakpoint config', () => {
+    defaultAppState.controlConfig = ({
+      ctrl1: { id: 'ctrl1', desktop: { slot: 'map-styles-panel', tab: 'Styles' }, includeModes: ['view'] }
+    })
+    const result = mapControls({ slot: 'map-styles-panel', appState: defaultAppState, evaluateProp: (p) => p })
+    expect(result[0].tab).toBe('Styles')
+  })
+
+  it('leaves tab undefined when not set on the breakpoint config', () => {
+    defaultAppState.controlConfig = ({
+      ctrl1: { id: 'ctrl1', desktop: { slot: 'header', order: 1 }, includeModes: ['view'] }
+    })
+    const result = mapControls({ slot: 'header', appState: defaultAppState, evaluateProp: (p) => p })
+    expect(result[0].tab).toBeUndefined()
+  })
 })

package/src/App/renderer/mapPanels.js

@@ -4,6 +4,11 @@ import { withPluginContexts } from './pluginWrapper.js'
 import { Panel } from '../components/Panel/Panel.jsx'
 import { allowedSlots } from './slots.js'
 import { resolveTargetSlot, isModeAllowed, isConsumerHtml } from './slotHelpers.js'
+import { mapControls } from './mapControls.js'
+import { orderItems } from './orderItems.js'
+import { groupIntoTabs } from './groupIntoTabs.js'
+import { stringToKebab } from '../../utils/stringToKebab.js'
+import { logger } from '../../services/logger.js'
 
 /**
  * Determines whether a panel should be rendered in the given slot.
@@ -44,7 +49,7 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
     const cfg = panelConfig[panelId]?.[breakpoint]
     return cfg?.modal
   })
-  const allowedModalPanelId = modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null
+  const allowedModalPanelId = modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null // NOSONAR, .at() is only Chrome 90+
 
   return openPanelEntries.map(([panelId, { props, focusOnOpen }]) => {
     const config = panelConfig[panelId]
@@ -73,13 +78,8 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
     const plugin = pluginRegistry.registeredPlugins.find(p => p.id === config.pluginId)
     const pluginId = plugin?.id
 
-    const WrappedChild = config.render
-      ? withPluginContexts(config.render, {
-        ...props,
-        pluginId,
-        pluginConfig: plugin?.config
-      })
-      : null
+    const html = pluginId ? evaluateProp(config.html, pluginId) : config.html
+    const label = evaluateProp(config.label, pluginId)
 
     return {
       id: panelId,
@@ -92,12 +92,54 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
           panelConfig={config}
           props={props}
           focusOnOpen={focusOnOpen}
-          WrappedChild={WrappedChild}
-          label={evaluateProp(config.label, pluginId)}
-          html={pluginId ? evaluateProp(config.html, pluginId) : config.html}
+          {...buildPanelBody({ panelId, config, bpConfig, props, plugin, pluginId, html, label, appState, evaluateProp })}
+          label={label}
+          html={html}
         />
       )
     }
   })
     .filter(Boolean)
 }
+
+/**
+ * Builds a panel's body: its own render content (if any) plus any controls registered against
+ * its `<panelId>-panel` slot by other plugins, merged with `orderItems` — or, when two or more
+ * distinct `tab`s are present among them, grouped into tabs instead (see `groupIntoTabs`).
+ * Static-html panels don't build a body — dangerouslySetInnerHTML can't host injected content,
+ * so any controls targeting one are silently skipped (with a dev warning).
+ *
+ * @returns {{ items?: object[], tabs?: object[] }} spread directly onto `<Panel>` — exactly one
+ *   of `items`/`tabs` is set (or neither, for a static-html panel).
+ */
+function buildPanelBody ({ panelId, config, bpConfig, props, plugin, pluginId, html, label, appState, evaluateProp }) {
+  const injectedItems = mapControls({
+    slot: `${stringToKebab(panelId)}-panel`,
+    appState,
+    evaluateProp
+  })
+
+  if (html) {
+    /* istanbul ignore next */
+    if (process.env.NODE_ENV !== 'production' && injectedItems.length > 0) {
+      logger.warn(`Panel "${panelId}" uses static html — controls targeting its slot are not rendered.`)
+    }
+    return {}
+  }
+
+  let ownItem = null
+  if (config.render) {
+    const WrappedChild = withPluginContexts(config.render, {
+      ...props,
+      pluginId,
+      pluginConfig: plugin?.config
+    })
+    ownItem = { id: panelId, order: 0, tab: bpConfig.tab, element: <WrappedChild {...props} /> }
+  }
+
+  const allItems = ownItem ? [ownItem, ...injectedItems] : injectedItems
+
+  const tabs = groupIntoTabs({ items: allItems, fallbackLabel: label })
+
+  return tabs ? { tabs } : { items: orderItems(allItems) }
+}

package/src/App/renderer/mapPanels.test.js

@@ -2,10 +2,14 @@ import React from 'react'
 import { mapPanels } from './mapPanels.js'
 import { registeredPlugins } from '../registry/pluginRegistry.js'
 import { withPluginContexts } from './pluginWrapper.js'
+import { mapControls } from './mapControls.js'
+import { logger } from '../../services/logger.js'
 
+jest.mock('../../services/logger.js')
 jest.mock('../registry/panelRegistry.js')
 jest.mock('../registry/pluginRegistry.js', () => ({ registeredPlugins: [] }))
 jest.mock('./pluginWrapper.js', () => ({ withPluginContexts: jest.fn((c) => c) }))
+jest.mock('./mapControls.js', () => ({ mapControls: jest.fn(() => []) }))
 jest.mock('../components/Panel/Panel.jsx', () => ({ Panel: (props) => <div data-testid='panel' {...props} /> }))
 jest.mock('./slots.js', () => ({ allowedSlots: { panel: ['header', 'modal', 'left-top'] } }))
 
@@ -23,6 +27,7 @@ describe('mapPanels', () => {
 
   beforeEach(() => {
     jest.clearAllMocks()
+    mapControls.mockReturnValue([])
     registeredPlugins.length = 0
     defaultAppState = {
       breakpoint: 'desktop',
@@ -116,9 +121,97 @@ describe('mapPanels', () => {
     )
   })
 
-  it('sets WrappedChild null if no render function', () => {
+  it('builds an empty items list if there is no render function and no injected controls', () => {
     const result = map()
-    expect(result[0].element.props.WrappedChild).toBeNull()
+    expect(result[0].element.props.items).toEqual([])
+  })
+
+  it('builds a single-item items list for a panel with its own render content', () => {
+    const renderFn = () => <div>child</div>
+    defaultAppState.panelConfig = ({ p1: { ...baseConfig, render: renderFn } })
+    const result = map()
+    expect(result[0].element.props.items).toEqual([
+      { id: 'p1', order: 0, element: expect.anything() }
+    ])
+  })
+
+  it('requests injected controls using the <panelId>-panel slot convention', () => {
+    map()
+    expect(mapControls).toHaveBeenCalledWith(expect.objectContaining({ slot: 'p1-panel' }))
+  })
+
+  it('merges and orders the panel\'s own content with controls injected via mapControls', () => {
+    const renderFn = () => <div>child</div>
+    mapControls.mockReturnValue([{ id: 'injected1', order: 1, element: <span>injected</span> }])
+    defaultAppState.panelConfig = ({ p1: { ...baseConfig, render: renderFn } })
+    const result = map()
+    // injected1 has order 1, so it's spliced ahead of the panel's own (unordered) content
+    expect(result[0].element.props.items.map(i => i.id)).toEqual(['injected1', 'p1'])
+  })
+
+  it('returns just the injected controls when the panel has neither render nor html', () => {
+    mapControls.mockReturnValue([{ id: 'injected1', order: 0, element: <span>injected</span> }])
+    defaultAppState.panelConfig = ({ p1: { desktop: { slot: 'header' }, includeModes: ['view'] } })
+    const result = map()
+    expect(result[0].element.props.items.map(i => i.id)).toEqual(['injected1'])
+  })
+
+  it('does not build an items list for a static-html panel (dangerouslySetInnerHTML can\'t host injected controls)', () => {
+    defaultAppState.panelConfig = ({ p1: { desktop: { slot: 'header' }, includeModes: ['view'], pluginId: 'plug1', html: '<p>Hi</p>' } })
+    const result = map()
+    expect(result[0].element.props.items).toBeUndefined()
+    expect(result[0].element.props.html).toBe('<p>Hi</p>')
+  })
+
+  it('warns in dev when controls target a static-html panel', () => {
+    mapControls.mockReturnValue([{ id: 'injected1', order: 0, element: <span>injected</span> }])
+    defaultAppState.panelConfig = ({ p1: { desktop: { slot: 'header' }, includeModes: ['view'], pluginId: 'plug1', html: '<p>Hi</p>' } })
+    map()
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('p1'))
+  })
+
+  it('orders multiple injected controls even when the panel has no render (regression: previously returned mapControls output unordered)', () => {
+    mapControls.mockReturnValue([
+      { id: 'first', order: 2, element: <span>first</span> },
+      { id: 'second', order: 1, element: <span>second</span> }
+    ])
+    defaultAppState.panelConfig = ({ p1: { desktop: { slot: 'header' }, includeModes: ['view'] } })
+    const result = map()
+    expect(result[0].element.props.items.map(i => i.id)).toEqual(['second', 'first'])
+  })
+
+  describe('tabs', () => {
+    it('does not build a tabs list when everything shares one (or no) tab', () => {
+      const renderFn = () => <div>child</div>
+      mapControls.mockReturnValue([{ id: 'injected1', order: 0, element: <span>injected</span> }])
+      defaultAppState.panelConfig = ({ p1: { ...baseConfig, render: renderFn } })
+      const result = map()
+      expect(result[0].element.props.tabs).toBeUndefined()
+      expect(result[0].element.props.items).toBeDefined()
+    })
+
+    it('groups the panel\'s own content and an injected control into separate tabs', () => {
+      const renderFn = () => <div>child</div>
+      mapControls.mockReturnValue([{ id: 'injected1', order: 0, tab: 'Injected', element: <span>injected</span> }])
+      defaultAppState.panelConfig = ({
+        p1: { ...baseConfig, render: renderFn, desktop: { slot: 'header', order: 1, tab: 'Own' } }
+      })
+      const result = map()
+      expect(result[0].element.props.items).toBeUndefined()
+      const tabNames = result[0].element.props.tabs.map(t => t.name)
+      expect(tabNames.sort()).toEqual(['Injected', 'Own'])
+    })
+
+    it('falls back to the panel\'s own label for its content\'s implicit tab', () => {
+      const renderFn = () => <div>child</div>
+      mapControls.mockReturnValue([{ id: 'injected1', order: 0, tab: 'Injected', element: <span>injected</span> }])
+      defaultAppState.panelConfig = ({
+        p1: { ...baseConfig, render: renderFn, label: 'Map styles' }
+      })
+      const result = map()
+      const tabNames = result[0].element.props.tabs.map(t => t.name)
+      expect(tabNames).toContain('Map styles')
+    })
   })
 
   it('returns correct structure and defaults', () => {

package/src/App/renderer/orderItems.js

@@ -0,0 +1,28 @@
+// src/core/renderers/orderItems.js
+
+/**
+ * Orders a list of `{ id, order, element }` items for a single render target
+ * (a layout slot, or a panel body).
+ *
+ * Items without an explicit `order` (or `order === 0`) keep their natural/registration
+ * sequence. Items with an explicit `order` are spliced into that 1-based position among
+ * the unordered items, clamped to the valid range.
+ */
+export function orderItems (items) {
+  // Start with items that have no explicit order (in their natural sequence)
+  const withoutOrder = items.filter(item => item.order == null || item.order === 0)
+  const withOrder = items.filter(item => item.order != null && item.order !== 0)
+
+  // Sort items with order by their order value (stable sort preserves ties)
+  withOrder.sort((a, b) => a.order - b.order)
+
+  // Insert each ordered item at its specified position
+  const result = [...withoutOrder]
+  for (const item of withOrder) {
+    // Clamp position to valid range (1-based, so subtract 1 for array index)
+    const pos = Math.min(Math.max(item.order - 1, 0), result.length)
+    result.splice(pos, 0, item)
+  }
+
+  return result
+}

package/src/App/renderer/orderItems.test.js

@@ -0,0 +1,50 @@
+import { orderItems } from './orderItems.js'
+
+describe('orderItems', () => {
+  it('keeps unordered items in their natural sequence', () => {
+    const items = [{ id: 'a' }, { id: 'b' }, { id: 'c' }]
+    expect(orderItems(items).map(i => i.id)).toEqual(['a', 'b', 'c'])
+  })
+
+  it('treats order 0 the same as no order', () => {
+    const items = [{ id: 'a', order: 0 }, { id: 'b' }]
+    expect(orderItems(items).map(i => i.id)).toEqual(['a', 'b'])
+  })
+
+  it('inserts an ordered item at its 1-based position among unordered items', () => {
+    const items = [{ id: 'a' }, { id: 'b' }, { id: 'c', order: 1 }]
+    expect(orderItems(items).map(i => i.id)).toEqual(['c', 'a', 'b'])
+  })
+
+  it('splices ordered items in ascending order, each relative to the growing result', () => {
+    const items = [
+      { id: 'a' },
+      { id: 'b', order: 2 },
+      { id: 'c', order: 1 }
+    ]
+    // c (order 1) is spliced in first, ahead of 'a': [c, a]
+    // b (order 2) is then spliced at index 1 of that 2-item result: [c, b, a]
+    expect(orderItems(items).map(i => i.id)).toEqual(['c', 'b', 'a'])
+  })
+
+  it('clamps an order larger than the list to the end', () => {
+    const items = [{ id: 'a' }, { id: 'b' }, { id: 'c', order: 99 }]
+    expect(orderItems(items).map(i => i.id)).toEqual(['a', 'b', 'c'])
+  })
+
+  it('splices equal-order items each at position 0, reversing their relative order', () => {
+    // The stable sort keeps a before b, but with no unordered items to anchor against,
+    // each splice(0, 0, item) inserts ahead of the previous one.
+    const items = [{ id: 'a', order: 1 }, { id: 'b', order: 1 }]
+    expect(orderItems(items).map(i => i.id)).toEqual(['b', 'a'])
+  })
+
+  it('handles an all-ordered list', () => {
+    const items = [{ id: 'a', order: 2 }, { id: 'b', order: 1 }]
+    expect(orderItems(items).map(i => i.id)).toEqual(['b', 'a'])
+  })
+
+  it('handles an empty list', () => {
+    expect(orderItems([])).toEqual([])
+  })
+})

package/src/App/renderer/slotAggregator.js

@@ -2,28 +2,12 @@
 import { mapControls } from './mapControls.js'
 import { mapPanels } from './mapPanels.js'
 import { mapButtons } from './mapButtons.js'
+import { orderItems } from './orderItems.js'
 
 export function getSlotItems ({ evaluateProp, ...args }) {
   const controls = mapControls({ evaluateProp, ...args })
   const panels = mapPanels({ evaluateProp, ...args })
   const buttons = mapButtons({ evaluateProp, ...args })
 
-  const items = [...controls, ...panels, ...buttons]
-
-  // Start with items that have no explicit order (in their natural sequence)
-  const withoutOrder = items.filter(item => item.order == null || item.order === 0)
-  const withOrder = items.filter(item => item.order != null && item.order !== 0)
-
-  // Sort items with order by their order value (stable sort preserves ties)
-  withOrder.sort((a, b) => a.order - b.order)
-
-  // Insert each ordered item at its specified position
-  const result = [...withoutOrder]
-  for (const item of withOrder) {
-    // Clamp position to valid range (1-based, so subtract 1 for array index)
-    const pos = Math.min(Math.max(item.order - 1, 0), result.length)
-    result.splice(pos, 0, item)
-  }
-
-  return result
+  return orderItems([...controls, ...panels, ...buttons])
 }

package/src/App/renderer/slotHelpers.js

@@ -39,7 +39,9 @@ export const isControlVisible = (control, { breakpoint, mode, isFullscreen }) =>
   if (!bpConfig) {
     return false
   }
-  if (!allowedSlots.control.includes(bpConfig.slot)) {
+  // A control may also target a panel's body directly via the `<panelId>-panel`
+  // slot convention (mirrors the `<buttonId>-button` convention panels already use).
+  if (!allowedSlots.control.includes(bpConfig.slot) && !bpConfig.slot?.endsWith('-panel')) {
     return false
   }
   if (!isModeAllowed(control, mode)) {

package/src/App/renderer/slotHelpers.test.js

@@ -65,6 +65,11 @@ describe('isControlVisible', () => {
   it('returns true when inline:false and fullscreen', () => {
     expect(isControlVisible({ ...base, inline: false }, { breakpoint: 'desktop', mode: 'view', isFullscreen: true })).toBe(true)
   })
+
+  it('returns true for a control targeting a panel-body slot via the <panelId>-panel convention', () => {
+    const panelTargeting = { desktop: { slot: 'map-styles-panel' } }
+    expect(isControlVisible(panelTargeting, { breakpoint: 'desktop', mode: 'view', isFullscreen: false })).toBe(true)
+  })
 })
 
 describe('isConsumerHtml', () => {

package/src/App/renderer/slots.js

@@ -1,6 +1,7 @@
 // src/core/renderers/slots.js
 export const layoutSlots = Object.freeze({
   SIDE: 'side',
+  HEADER: 'header',
   BANNER: 'banner',
   TOP_LEFT: 'top-left',
   TOP_MIDDLE: 'top-middle',
@@ -19,6 +20,7 @@ export const layoutSlots = Object.freeze({
 
 export const allowedSlots = Object.freeze({
   control: [
+    layoutSlots.HEADER,
     layoutSlots.BANNER,
     layoutSlots.TOP_LEFT,
     layoutSlots.TOP_RIGHT,
@@ -31,6 +33,7 @@ export const allowedSlots = Object.freeze({
   ],
   panel: [
     layoutSlots.SIDE,
+    layoutSlots.HEADER,
     layoutSlots.BANNER,
     layoutSlots.LEFT_TOP,
     layoutSlots.LEFT_BOTTOM,

package/src/App/store/AppProvider.jsx

@@ -16,6 +16,7 @@ export const AppProvider = ({ options, children }) => {
     appContainerRef: useRef(null),
     sideRef: useRef(null),
     mainRef: useRef(null),
+    headerRef: useRef(null),
     topRef: useRef(null),
     topLeftColRef: useRef(null),
     topRightColRef: useRef(null),