@defra/interactive-map 0.0.41-alpha → 0.0.43-fmp-experimental

package/src/App/renderer/mapButtons.js

@@ -1,6 +1,8 @@
 // src/core/renderers/mapButtons.js
 import { MapButton } from '../components/MapButton/MapButton.jsx'
 import { allowedSlots } from './slots.js'
+import { groupByKey } from './groupByKey.js'
+import { orderItems } from './orderItems.js'
 import { logger } from '../../services/logger.js'
 
 function getMatchingButtons ({ appState, buttonConfig, slot, evaluateProp }) {
@@ -74,47 +76,6 @@ function createButtonClickHandler (config, appState, evaluateProp) {
   }
 }
 
-/**
- * Resolves the group name from a button config's group property.
- * Accepts either the new object form `{ name, label?, order? }` or a deprecated plain string.
- * @param {string|{name: string, label?: string, order?: number}|null|undefined} group
- * @returns {string|null}
- */
-function resolveGroupName (group) {
-  if (group == null) {
-    return null
-  }
-  return typeof group === 'string' ? group : (group.name ?? null)
-}
-
-/**
- * Resolves the accessible label for a group.
- * Uses `label` if provided, otherwise falls back to `name`.
- * @param {string|{name: string, label?: string, order?: number}|null|undefined} group
- * @returns {string}
- */
-function resolveGroupLabel (group) {
-  if (!group) {
-    return ''
-  }
-  if (typeof group === 'string') {
-    return group
-  }
-  return group.label ?? group.name ?? ''
-}
-
-/**
- * Resolves the slot-level order for a group.
- * @param {string|{name: string, label?: string, order?: number}|null|undefined} group
- * @returns {number}
- */
-function resolveGroupOrder (group) {
-  if (!group || typeof group === 'string') {
-    return 0
-  }
-  return group.order ?? 0
-}
-
 function applySlotExclusivity (matching, appState) {
   let exclusivePluginId = null
 
@@ -181,6 +142,69 @@ function SlotButton ({ buttonId, config, appState, appConfig, evaluateProp }) {
   )
 }
 
+/**
+ * Ungrouped buttons — one result item per button, ordered by its own breakpoint-level
+ * slot position.
+ */
+function buildUngroupedItems (members, ctx) {
+  return members.map(([buttonId, config]) => ({
+    id: buttonId,
+    type: 'button',
+    order: config[ctx.breakpoint]?.order ?? 0,
+    element: <SlotButton key={buttonId} {...slotButtonProps({ buttonId, config, ...ctx })} />
+  }))
+}
+
+/**
+ * A named group's own slot order/label come from whichever member is encountered first —
+ * unlike panel tabs (see groupIntoTabs.js), this is never derived from members' own order:
+ * groups render simultaneously (not one-at-a-time like tabs), so an unspecified order
+ * defaults to 0, same as every other slot item, rather than borrowing a member's position.
+ * A single-member group still degrades to a plain button (no wrapping container), but keeps
+ * the group's own slot order rather than falling back to its own breakpoint-level order.
+ */
+function buildGroupItem (key, members, ctx) {
+  const [, firstConfig] = members[0]
+  const order = firstConfig.group.slotOrder ?? 0
+
+  /* istanbul ignore next */
+  if (process.env.NODE_ENV !== 'production') {
+    const distinctOrders = new Set(members.map(([, config]) => config.group?.slotOrder ?? 0))
+    if (distinctOrders.size > 1) {
+      logger.warn(`Button group "${firstConfig.group.label}" has inconsistent slotOrder values (${[...distinctOrders].join(', ')}) across its members — using ${order} (the first member's).`)
+    }
+  }
+
+  if (members.length < 2) {
+    const [buttonId, config] = members[0]
+    return {
+      id: buttonId,
+      type: 'button',
+      order,
+      element: <SlotButton key={buttonId} {...slotButtonProps({ buttonId, config, ...ctx })} />
+    }
+  }
+
+  // Order members within the group the same way panel/control content orders within a tab
+  const sorted = orderItems(members.map(([buttonId, config]) => ({
+    id: buttonId,
+    order: config[ctx.breakpoint]?.order ?? 0,
+    buttonId,
+    config
+  })))
+
+  return {
+    id: `group-${key}`,
+    type: 'group',
+    order,
+    element: (
+      <div key={`group-${key}`} role='group' aria-label={firstConfig.group.label} className='im-c-button-group'>{/* NOSONAR - div with role="group" is correct for a button group */}
+        {sorted.map(({ buttonId, config }) => <SlotButton key={buttonId} {...slotButtonProps({ buttonId, config, ...ctx })} />)}
+      </div>
+    )
+  }
+}
+
 function mapButtons ({ slot, appState, appConfig, evaluateProp }) {
   const { buttonConfig, breakpoint } = appState
 
@@ -191,86 +215,17 @@ function mapButtons ({ slot, appState, appConfig, evaluateProp }) {
     return []
   }
 
-  // Partition matching buttons into named groups and ungrouped singletons
-  const groupMap = new Map() // name -> { label, order, members: [[buttonId, config]] }
-  const singletons = []
-
-  matching.forEach(([buttonId, config]) => {
-    const { group } = config
-
-    if (group == null) {
-      singletons.push([buttonId, config])
-      return
-    }
-
-    /* istanbul ignore next */
-    if (process.env.NODE_ENV !== 'production' && typeof group === 'string') {
-      logger.warn(`Button "${buttonId}": group should be an object { name, label?, order? } — string groups are deprecated.`)
-    }
-
-    const name = resolveGroupName(group)
-    const label = resolveGroupLabel(group)
-    const order = resolveGroupOrder(group)
-
-    if (groupMap.has(name)) {
-      const existing = groupMap.get(name)
-      /* istanbul ignore next */
-      if (process.env.NODE_ENV !== 'production' && existing.order !== order) {
-        logger.warn(`Group "${name}" has inconsistent order values (${existing.order} vs ${order}). Using the lower value.`)
-        existing.order = Math.min(existing.order, order)
-      }
-    } else {
-      groupMap.set(name, { label, order, members: [] })
-    }
-
-    groupMap.get(name).members.push([buttonId, config])
-  })
+  // Partition into named groups (keyed by kebab-cased group.label) plus one ungrouped bucket
+  const buckets = groupByKey({ items: matching, keyFn: ([, config]) => config.group?.label })
+  const ctx = { breakpoint, appState, appConfig, evaluateProp }
 
   const result = []
-
-  // Ungrouped buttons — order is the breakpoint-level slot position
-  for (const btn of singletons) {
-    const [buttonId, config] = btn
-    const order = config[breakpoint]?.order ?? 0
-    result.push({
-      id: buttonId,
-      type: 'button',
-      order,
-      element: <SlotButton key={buttonId} {...slotButtonProps({ buttonId, config, appState, appConfig, evaluateProp })} />
-    })
-  }
-
-  for (const [groupName, { label, order: groupOrder, members }] of groupMap) {
-    if (members.length < 2) {
-      // Singleton group: degrade to a regular button using the group's slot order
-      const [buttonId, config] = members[0]
-      const order = groupOrder || config[breakpoint]?.order || 0
-      result.push({
-        id: buttonId,
-        type: 'button',
-        order,
-        element: <SlotButton key={buttonId} {...slotButtonProps({ buttonId, config, appState, appConfig, evaluateProp })} />
-      })
-      continue
+  for (const [key, members] of buckets) {
+    if (key === null) {
+      result.push(...buildUngroupedItems(members, ctx))
+    } else {
+      result.push(buildGroupItem(key, members, ctx))
     }
-
-    // Sort group members by their intra-group order (breakpoint-level order prop)
-    const sorted = [...members].sort((a, b) => {
-      const orderA = a[1][breakpoint]?.order ?? 0
-      const orderB = b[1][breakpoint]?.order ?? 0
-      return orderA - orderB
-    })
-
-    result.push({
-      id: `group-${groupName}`,
-      type: 'group',
-      order: groupOrder,
-      element: (
-        <div key={`group-${groupName}`} role='group' aria-label={label} className='im-c-button-group'>{/* NOSONAR - div with role="group" is correct for a button group */}
-          {sorted.map(([buttonId, config]) => <SlotButton key={buttonId} {...slotButtonProps({ buttonId, config, appState, appConfig, evaluateProp })} />)}
-        </div>
-      )
-    })
   }
 
   return result
@@ -280,8 +235,5 @@ export {
   mapButtons,
   getMatchingButtons,
   applySlotExclusivity,
-  SlotButton,
-  resolveGroupName,
-  resolveGroupLabel,
-  resolveGroupOrder
+  SlotButton
 }

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

@@ -1,5 +1,5 @@
 import React from 'react'
-import { mapButtons, getMatchingButtons, applySlotExclusivity, SlotButton, 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
   // -------------------------
@@ -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', () => {

package/src/App/renderer/mapControls.js

@@ -74,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

@@ -180,4 +180,20 @@ describe('mapControls', () => {
     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

@@ -6,6 +6,7 @@ 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'
 
@@ -48,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]
@@ -78,6 +79,7 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
     const pluginId = plugin?.id
 
     const html = pluginId ? evaluateProp(config.html, pluginId) : config.html
+    const label = evaluateProp(config.label, pluginId)
 
     return {
       id: panelId,
@@ -90,8 +92,8 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
           panelConfig={config}
           props={props}
           focusOnOpen={focusOnOpen}
-          items={buildPanelBodyItems({ panelId, config, props, plugin, pluginId, html, appState, evaluateProp })}
-          label={evaluateProp(config.label, pluginId)}
+          {...buildPanelBody({ panelId, config, bpConfig, props, plugin, pluginId, html, label, appState, evaluateProp })}
+          label={label}
           html={html}
         />
       )
@@ -101,12 +103,16 @@ export function mapPanels ({ slot, appState, evaluateProp }) {
 }
 
 /**
- * Builds the ordered list of body items for a panel: its own render content (if any) plus
- * any controls registered against its `<panelId>-panel` slot by other plugins. Static-html
- * panels don't build an items list — dangerouslySetInnerHTML can't host injected controls,
+ * 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 buildPanelBodyItems ({ panelId, config, props, plugin, pluginId, html, appState, evaluateProp }) {
+function buildPanelBody ({ panelId, config, bpConfig, props, plugin, pluginId, html, label, appState, evaluateProp }) {
   const injectedItems = mapControls({
     slot: `${stringToKebab(panelId)}-panel`,
     appState,
@@ -118,21 +124,22 @@ function buildPanelBodyItems ({ panelId, config, props, plugin, pluginId, html,
     if (process.env.NODE_ENV !== 'production' && injectedItems.length > 0) {
       logger.warn(`Panel "${panelId}" uses static html — controls targeting its slot are not rendered.`)
     }
-    return undefined
+    return {}
   }
 
-  if (!config.render) {
-    return injectedItems
+  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 WrappedChild = withPluginContexts(config.render, {
-    ...props,
-    pluginId,
-    pluginConfig: plugin?.config
-  })
+  const allItems = ownItem ? [ownItem, ...injectedItems] : injectedItems
+
+  const tabs = groupIntoTabs({ items: allItems, fallbackLabel: label })
 
-  return orderItems([
-    { id: panelId, order: 0, element: <WrappedChild {...props} /> },
-    ...injectedItems
-  ])
+  return tabs ? { tabs } : { items: orderItems(allItems) }
 }

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

@@ -170,6 +170,50 @@ describe('mapPanels', () => {
     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', () => {
     defaultAppState.panelConfig = ({ p1: { desktop: { slot: 'header' }, includeModes: ['view'] } })
     const result = map()

package/src/config/appConfig.js

@@ -74,7 +74,7 @@ export const defaultAppConfig = {
     desktop: buttonSlots
   }, {
     id: 'zoomIn',
-    group: { name: 'zoom', label: 'Zoom controls', order: 0 },
+    group: { label: 'Zoom controls', slotOrder: 0 },
     label: 'Zoom in',
     iconId: 'plus',
     keepFocus: true,
@@ -86,7 +86,7 @@ export const defaultAppConfig = {
     desktop: buttonSlots
   }, {
     id: 'zoomOut',
-    group: { name: 'zoom', label: 'Zoom controls', order: 0 },
+    group: { label: 'Zoom controls', slotOrder: 0 },
     label: 'Zoom out',
     iconId: 'minus',
     keepFocus: true,

package/src/types.js

@@ -40,6 +40,15 @@
  * different plugin. The panel's own content and every control targeting it are ordered together
  * via `order`. Only supported by panels with a `render` component — a panel using static `html`
  * can't host injected controls, since `dangerouslySetInnerHTML` owns its body's children.
+ *
+ * @property {string} [tab]
+ * Groups this item into a tab within its target panel. Two items share a tab by giving it the
+ * same `tab` string (case/whitespace-insensitive — compared kebab-cased); items with no `tab`
+ * share one implicit tab, labelled with the panel's own `label`. Tabs only render once this
+ * produces more than one distinct group — a panel with zero or one tab renders flat, with no
+ * tab UI at all. A tab's position and displayed label both come from whichever member ends up
+ * first once its own members are ordered by `order`, so there's no separate tab-order property
+ * to set. Like `order`, only respected for controls with a `render` component.
  */
 
 /**
@@ -67,6 +76,11 @@
  * @property {string} slot
  * Slot identifier.
  *
+ * @property {string} [tab]
+ * Groups the panel's own content into a tab alongside any controls injected into it — see
+ * `ControlBreakpointConfig.tab`. Optional even once tabs are active: the panel's own content
+ * falls back to an implicit tab labelled with the panel's `label` when omitted.
+ *
  * @property {string} [width]
  * Panel width.
  */
@@ -156,8 +170,12 @@
  * @property {(context: PluginContext) => boolean} [excludeWhen]
  * Callback to determine if the button should be excluded from rendering.
  *
- * @property {string} [group]
- * Button group label for grouping related buttons.
+ * @property {{ label: string, slotOrder?: number }} [group]
+ * Groups this button with any other button sharing the same `label` (kebab-cased) into one
+ * `role="group"` container, rendered as a single item in the slot. `label` is also the
+ * group's accessible name (aria-label) — buttons whose labels differ only by case/whitespace
+ * still merge into one group. `slotOrder` positions the group itself within the slot (defaults
+ * to 0); each button's own breakpoint `order` controls its position *within* the group.
  *
  * @property {(context: PluginContext) => boolean} [hiddenWhen]
  * Callback to determine if the button should be hidden. Sets display: none if true.