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

package/src/App/renderer/groupByKey.js

@@ -0,0 +1,28 @@
+import { stringToKebab } from '../../utils/stringToKebab.js'
+
+/**
+ * Partitions a list of items into buckets, keyed by `keyFn(item)` kebab-cased — two items
+ * share a bucket by producing the same key (so 'Map Size' and 'map size' merge). Items for
+ * which `keyFn` returns a falsy value all share one `null`-keyed bucket. Bucket iteration
+ * order follows first-encountered order, same as `Map`.
+ *
+ * Shared by `groupIntoTabs` (panel/control tabs) and `mapButtons` (button groups) — the two
+ * callers differ only in what happens *after* bucketing (how a bucket's own order/label is
+ * derived), not in how items get partitioned.
+ *
+ * @returns {Map<string|null, object[]>}
+ */
+export function groupByKey ({ items, keyFn }) {
+  const buckets = new Map()
+
+  for (const item of items) {
+    const raw = keyFn(item)
+    const key = raw ? stringToKebab(raw) : null
+    if (!buckets.has(key)) {
+      buckets.set(key, [])
+    }
+    buckets.get(key).push(item)
+  }
+
+  return buckets
+}

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

@@ -0,0 +1,39 @@
+import { groupByKey } from './groupByKey.js'
+
+describe('groupByKey', () => {
+  it('returns one bucket per distinct key', () => {
+    const items = [{ id: 'a', k: 'Styles' }, { id: 'b', k: 'Sizes' }]
+    const buckets = groupByKey({ items, keyFn: item => item.k })
+    expect([...buckets.keys()].sort()).toEqual(['sizes', 'styles'])
+  })
+
+  it('lowercases the key, hyphenating only camelCase-style boundaries (stringToKebab)', () => {
+    const items = [{ id: 'a', k: 'mapSize' }]
+    const buckets = groupByKey({ items, keyFn: item => item.k })
+    expect([...buckets.keys()]).toEqual(['map-size'])
+  })
+
+  it('merges items whose key differs only by case/whitespace into one bucket', () => {
+    const items = [{ id: 'a', k: 'Map Size' }, { id: 'b', k: 'map size' }]
+    const buckets = groupByKey({ items, keyFn: item => item.k })
+    expect(buckets.size).toBe(1)
+    expect([...buckets.values()][0]).toHaveLength(2)
+  })
+
+  it('puts items with no key into one null-keyed bucket', () => {
+    const items = [{ id: 'a' }, { id: 'b' }]
+    const buckets = groupByKey({ items, keyFn: () => null })
+    expect(buckets.size).toBe(1)
+    expect(buckets.get(null)).toHaveLength(2)
+  })
+
+  it('keeps items within a bucket in their original relative order', () => {
+    const items = [{ id: 'a', k: 'g' }, { id: 'b', k: 'g' }, { id: 'c', k: 'g' }]
+    const buckets = groupByKey({ items, keyFn: item => item.k })
+    expect(buckets.get('g').map(i => i.id)).toEqual(['a', 'b', 'c'])
+  })
+
+  it('returns an empty map for an empty list', () => {
+    expect(groupByKey({ items: [], keyFn: () => 'x' }).size).toBe(0)
+  })
+})

package/src/App/renderer/groupIntoTabs.js

@@ -0,0 +1,42 @@
+import { orderItems } from './orderItems.js'
+import { groupByKey } from './groupByKey.js'
+
+/**
+ * Groups a flat list of `{ id, order, tab, element }` items into tabs, when warranted.
+ *
+ * Items are partitioned by `tab` via `groupByKey` — two items share a tab by producing the
+ * same kebab-cased key. Items with no `tab` share one fallback bucket. Returns `null` when
+ * there's one bucket or fewer, so the caller can fall back to flat rendering unchanged.
+ *
+ * Each bucket's members are ordered via `orderItems`; the resulting tab's own `order` and
+ * displayed `name` both come from whichever member ends up first in that ordering — the same
+ * item that "wins" the position also wins the label, so there's nothing separate to reconcile
+ * when members disagree. The tabs themselves are then ordered the same way, via `orderItems`
+ * again — no new ordering concept, just the existing one applied twice.
+ *
+ * This derived-order approach is safe here because tabs are mutually exclusive — only the
+ * active tab's content is ever visible, so a "losing" member's own order never has to compete
+ * against anything outside its own tab at the same time. `mapButtons`'s button groups don't
+ * have that property (every group renders simultaneously), so they don't derive a group's
+ * order from its members the same way — see `mapButtons.js`.
+ */
+export function groupIntoTabs ({ items, fallbackLabel }) {
+  const buckets = groupByKey({ items, keyFn: item => item.tab })
+
+  if (buckets.size <= 1) {
+    return null
+  }
+
+  const tabs = Array.from(buckets.entries()).map(([key, members]) => {
+    const orderedMembers = orderItems(members)
+    const first = orderedMembers[0]
+    return {
+      id: key ?? 'default',
+      order: first.order,
+      name: key ? first.tab : fallbackLabel,
+      items: orderedMembers
+    }
+  })
+
+  return orderItems(tabs)
+}

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

@@ -0,0 +1,95 @@
+import { groupIntoTabs } from './groupIntoTabs.js'
+
+describe('groupIntoTabs', () => {
+  it('returns null when there are no items', () => {
+    expect(groupIntoTabs({ items: [], fallbackLabel: 'Panel' })).toBeNull()
+  })
+
+  it('returns null when all items share the same tab', () => {
+    const items = [
+      { id: 'a', order: 0, tab: 'Styles' },
+      { id: 'b', order: 0, tab: 'Styles' }
+    ]
+    expect(groupIntoTabs({ items, fallbackLabel: 'Panel' })).toBeNull()
+  })
+
+  it('returns null when no items have a tab', () => {
+    const items = [{ id: 'a', order: 0 }, { id: 'b', order: 0 }]
+    expect(groupIntoTabs({ items, fallbackLabel: 'Panel' })).toBeNull()
+  })
+
+  it('partitions items into distinct tabs', () => {
+    const items = [
+      { id: 'a', order: 0, tab: 'Styles' },
+      { id: 'b', order: 0, tab: 'Sizes' }
+    ]
+    const tabs = groupIntoTabs({ items, fallbackLabel: 'Panel' })
+    expect(tabs.map(t => t.name).sort()).toEqual(['Sizes', 'Styles'])
+  })
+
+  it('groups untagged items into one fallback bucket named after fallbackLabel', () => {
+    const items = [
+      { id: 'a', order: 0, tab: 'Styles' },
+      { id: 'b', order: 0 },
+      { id: 'c', order: 0 }
+    ]
+    const tabs = groupIntoTabs({ items, fallbackLabel: 'Map styles' })
+    const fallback = tabs.find(t => t.name === 'Map styles')
+    expect(fallback.items.map(i => i.id).sort()).toEqual(['b', 'c'])
+  })
+
+  it('merges items whose tab differs only by case/whitespace into one bucket', () => {
+    const items = [
+      { id: 'a', order: 0, tab: 'Map Size' },
+      { id: 'b', order: 1, tab: 'map size' },
+      { id: 'c', order: 0, tab: 'Styles' }
+    ]
+    const tabs = groupIntoTabs({ items, fallbackLabel: 'Panel' })
+    expect(tabs).toHaveLength(2)
+    const merged = tabs.find(t => t.items.length === 2)
+    expect(merged.items.map(i => i.id)).toEqual(expect.arrayContaining(['a', 'b']))
+  })
+
+  it("uses the winning (lowest-order) member's raw tab string as the displayed name", () => {
+    const items = [
+      { id: 'a', order: 2, tab: 'MAP SIZE' },
+      { id: 'b', order: 1, tab: 'map size' }, // lower order wins the label
+      { id: 'c', order: 0, tab: 'Styles' }
+    ]
+    const tabs = groupIntoTabs({ items, fallbackLabel: 'Panel' })
+    const merged = tabs.find(t => t.items.length === 2)
+    expect(merged.name).toBe('map size')
+  })
+
+  it("derives a tab's order from its first ordered member", () => {
+    const items = [
+      { id: 'a', order: 5, tab: 'Styles' },
+      { id: 'b', order: 1, tab: 'Styles' },
+      { id: 'c', order: 0, tab: 'Sizes' }
+    ]
+    const tabs = groupIntoTabs({ items, fallbackLabel: 'Panel' })
+    const stylesTab = tabs.find(t => t.name === 'Styles')
+    expect(stylesTab.order).toBe(1)
+  })
+
+  it('orders tabs among themselves using the derived order', () => {
+    const items = [
+      { id: 'a', order: 2, tab: 'Second' },
+      { id: 'b', order: 1, tab: 'First' }
+    ]
+    const tabs = groupIntoTabs({ items, fallbackLabel: 'Panel' })
+    expect(tabs.map(t => t.name)).toEqual(['First', 'Second'])
+  })
+
+  it('orders items within a tab using orderItems', () => {
+    const items = [
+      { id: 'a', order: 0, tab: 'Styles' },
+      { id: 'b', order: 1, tab: 'Styles' },
+      { id: 'c', order: 0, tab: 'Sizes' }
+    ]
+    const tabs = groupIntoTabs({ items, fallbackLabel: 'Panel' })
+    const stylesTab = tabs.find(t => t.name === 'Styles')
+    // b (order 1) is spliced ahead of the unordered item a
+    expect(stylesTab.items.map(i => i.id)).toEqual(['b', 'a'])
+  })
+})

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 }) {
@@ -49,8 +51,7 @@ function getMatchingButtons ({ appState, buttonConfig, slot, evaluateProp }) {
   })
 }
 
-function createButtonClickHandler (btn, appState, evaluateProp) {
-  const [, config] = btn
+function createButtonClickHandler (config, appState, evaluateProp) {
   const isPanelOpen = !!(config.panelId && appState.openPanels[config.panelId])
   const isToggle = config.isPressed !== undefined || !!config.pressedWhen
 
@@ -75,47 +76,6 @@ function createButtonClickHandler (btn, 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
 
@@ -134,15 +94,33 @@ function applySlotExclusivity (matching, appState) {
   return matching.filter(([_, config]) => config.pluginId === exclusivePluginId)
 }
 
-function renderButton ({ btn, appState, appConfig, evaluateProp }) {
-  const [buttonId, config] = btn
+/**
+ * Builds the props for a <SlotButton>. isHidden/variant are included here (not just derived
+ * inside SlotButton) because Actions.jsx also reads them directly off the 'actions' slot's
+ * immediate children via React.Children.toArray — they need to be top-level props on whatever
+ * element ends up there, not just used internally to build MapButton.
+ */
+const slotButtonProps = ({ buttonId, config, appState, appConfig, evaluateProp }) => ({
+  buttonId,
+  config,
+  appState,
+  appConfig,
+  evaluateProp,
+  isHidden: appState.hiddenButtons.has(buttonId),
+  variant: config.variant
+})
+
+/**
+ * Renders a single button's MapButton element for its slot, computing its click handler
+ * and derived state (panel-open, showLabel fallback, etc.) from its config and appState.
+ */
+function SlotButton ({ buttonId, config, appState, appConfig, evaluateProp }) {
   const bpConfig = config[appState.breakpoint] ?? {}
-  const handleClick = createButtonClickHandler(btn, appState, evaluateProp)
+  const handleClick = createButtonClickHandler(config, appState, evaluateProp)
   const isPanelOpen = !!(config.panelId && appState.openPanels[config.panelId])
 
   return (
     <MapButton
-      key={buttonId}
       buttonId={buttonId}
       iconId={evaluateProp(config.iconId, config.pluginId)}
       iconSvgContent={evaluateProp(config.iconSvgContent, config.pluginId)}
@@ -164,6 +142,69 @@ function renderButton ({ btn, 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
 
@@ -174,87 +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: renderButton({ btn, 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 btn = members[0]
-      const [buttonId, config] = btn
-      const order = groupOrder || config[breakpoint]?.order || 0
-      result.push({
-        id: buttonId,
-        type: 'button',
-        order,
-        element: renderButton({ btn, 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(btn => renderButton({ btn, appState, appConfig, evaluateProp }))}
-        </div>
-      )
-    })
   }
 
   return result
@@ -264,8 +235,5 @@ export {
   mapButtons,
   getMatchingButtons,
   applySlotExclusivity,
-  renderButton,
-  resolveGroupName,
-  resolveGroupLabel,
-  resolveGroupOrder
+  SlotButton
 }