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

package/src/App/components/Panel/Panel.test.jsx

@@ -69,7 +69,7 @@ describe('Panel', () => {
       const { container } = renderPanel()
 
       // 2. Target by class to avoid role collision with the parent panel
-      const body = container.querySelector('.im-c-panel__body')
+      const body = container.querySelector('[data-panel-slot]')
 
       expect(body).toHaveAttribute('tabIndex', '0')
       expect(body).toHaveAttribute('role', 'region')
@@ -194,5 +194,118 @@ describe('Panel', () => {
       renderPanel({}, { html: '<p>HTML content</p>' })
       expect(screen.getByText('HTML content')).toBeInTheDocument()
     })
+
+    it('renders each items entry in list order', () => {
+      const items = [
+        { id: 'a', element: <p>First</p> },
+        { id: 'b', element: <p>Second</p> }
+      ]
+      renderPanel({}, { items })
+      expect(screen.getByText('First')).toBeInTheDocument()
+      expect(screen.getByText('Second')).toBeInTheDocument()
+    })
+
+    it('prefers items over WrappedChild/children when provided', () => {
+      const Wrapped = () => <p>Wrapped</p>
+      renderPanel({}, {
+        items: [{ id: 'a', element: <p>Item</p> }],
+        WrappedChild: Wrapped,
+        children: <p>Child content</p>
+      })
+      expect(screen.getByText('Item')).toBeInTheDocument()
+      expect(screen.queryByText('Wrapped')).not.toBeInTheDocument()
+      expect(screen.queryByText('Child content')).not.toBeInTheDocument()
+    })
+
+    it('stamps data-panel-slot on the items-capable body, for controls DOM-projected via the JS API', () => {
+      const { container } = renderPanel({}, { items: [{ id: 'a', element: <p>Item</p> }] })
+      const body = container.querySelector('[data-panel-slot]')
+      expect(body).toHaveAttribute('data-panel-slot', 'settings-panel')
+    })
+
+    it('does not stamp data-panel-slot on a static-html body', () => {
+      const { container } = renderPanel({}, { html: '<p>HTML content</p>' })
+      const body = container.querySelector('.im-c-panel__body')
+      expect(body).not.toHaveAttribute('data-panel-slot')
+    })
+
+    describe('tabs', () => {
+      const tabs = [
+        { name: 'First', items: [{ id: 'a', element: <p>First content</p> }] },
+        { name: 'Second', items: [{ id: 'b', element: <p>Second content</p> }] }
+      ]
+
+      it('renders items grouped into tabs when the tabs prop is provided', () => {
+        renderPanel({}, { tabs })
+        expect(screen.getByRole('tablist')).toBeInTheDocument()
+        expect(screen.getByRole('tab', { name: 'First' })).toBeInTheDocument()
+        expect(screen.getByRole('tab', { name: 'Second' })).toBeInTheDocument()
+        expect(screen.getByText('First content')).toBeInTheDocument()
+      })
+
+      it('switches tab content when a different tab is activated', () => {
+        renderPanel({}, { tabs })
+        fireEvent.click(screen.getByRole('tab', { name: 'Second' }))
+        expect(screen.getByText('Second content')).toBeVisible()
+        expect(screen.getByText('First content')).not.toBeVisible()
+      })
+
+      it('prefers tabs over items/WrappedChild/children when provided', () => {
+        renderPanel({}, {
+          tabs,
+          items: [{ id: 'x', element: <p>Flat item</p> }],
+          WrappedChild: () => <p>Wrapped</p>,
+          children: <p>Child content</p>
+        })
+        expect(screen.getByText('First content')).toBeInTheDocument()
+        expect(screen.queryByText('Flat item')).not.toBeInTheDocument()
+        expect(screen.queryByText('Wrapped')).not.toBeInTheDocument()
+        expect(screen.queryByText('Child content')).not.toBeInTheDocument()
+      })
+
+      it('keeps the panel body wrapper (padding, data-panel-slot) around the whole tabs block', () => {
+        const { container } = renderPanel({}, { tabs })
+        const body = container.querySelector('[data-panel-slot]')
+        expect(body).toHaveAttribute('data-panel-slot', 'settings-panel')
+        expect(body.querySelector('[role="tablist"]')).not.toBeNull()
+        expect(body.querySelector('[role="tabpanel"]')).not.toBeNull()
+      })
+
+      it('keeps the outer wrapper as the normal, unconditional im-c-panel__body — the tablist and tabpanel pick up their inset by being nested inside it, same as any other panel content', () => {
+        const { container } = renderPanel({}, { tabs })
+        const body = container.querySelector('[data-panel-slot]')
+        expect(body).toHaveClass('im-c-panel__body')
+      })
+
+      it('keeps the tablist outside the scrollable tabpanel, so it does not scroll away with long tab content', () => {
+        const { container } = renderPanel({}, { tabs })
+        const tabpanel = container.querySelector('[role="tabpanel"]')
+        expect(tabpanel.querySelector('[role="tablist"]')).toBeNull()
+      })
+
+      it('places the tablist before the tabpanel in DOM order, so keyboard focus reaches it first', () => {
+        const { container } = renderPanel({}, { tabs })
+        const tablist = container.querySelector('[role="tablist"]')
+        const tabpanel = container.querySelector('[role="tabpanel"]')
+        // DOCUMENT_POSITION_FOLLOWING (4) means `tabpanel` comes after `tablist`
+        // eslint-disable-next-line no-bitwise
+        expect(tablist.compareDocumentPosition(tabpanel) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+      })
+
+      it('moves the scrollable-region treatment onto the tabpanel itself, not the outer wrapper', () => {
+        useIsScrollable.mockReturnValue(true)
+
+        const { container } = renderPanel({}, { tabs })
+        const body = container.querySelector('[data-panel-slot]')
+        const tabpanel = screen.getByRole('tabpanel')
+
+        expect(tabpanel).toHaveAttribute('tabIndex', '0')
+        expect(body).not.toHaveAttribute('tabIndex')
+        expect(body).not.toHaveAttribute('role', 'region')
+        expect(tabpanel).not.toHaveAttribute('data-panel-slot')
+
+        useIsScrollable.mockReturnValue(false)
+      })
+    })
   })
 })

package/src/App/components/Tabs/Tabs.jsx

@@ -1,18 +1,31 @@
 import React, { useState, useCallback } from 'react'
+import { useConfig } from '../../store/configContext'
 
-const toTabId = (name) => `im-c-tabs-tab-${name.toLowerCase().replaceAll(/\s+/g, '-')}`
-const toPanelId = (name) => `im-c-tabs-panel-${name.toLowerCase().replaceAll(/\s+/g, '-')}`
+// Prefixed with the app's own id (not the im-c- BEM prefix, which is for CSS classes, not DOM
+// ids — see Panel.jsx's/MapButton.jsx's own ${id}-... ids for the same convention) so these
+// stay unique when more than one map instance is on the same page.
+const toTabId = (idPrefix, name) => `${idPrefix}-tabs-tab-${name.toLowerCase().replaceAll(/\s+/g, '-')}`
+const toPanelId = (idPrefix, name) => `${idPrefix}-tabs-panel-${name.toLowerCase().replaceAll(/\s+/g, '-')}`
 
+/**
+ * @param {object} [panelProps] Extra props merged onto the tabpanel div (not the tablist) —
+ * e.g. a scrollable container's ref/className/tabIndex, for a caller (Panel.jsx) that needs
+ * that behaviour scoped to just the active tab's content, not the tablist above it. `id`,
+ * `role` and `aria-labelledby` are structural to the tabs pattern and always win over any
+ * same-named key in `panelProps`; `tabIndex` defers to `panelProps.tabIndex` when provided,
+ * since a scrollable tabpanel legitimately wants tabIndex 0 rather than the -1 default.
+ */
 // eslint-disable-next-line camelcase, react/jsx-pascal-case
 // sonarjs/disable-next-line function-name
-export const Tabs = ({ tabs, defaultTab }) => { // NOSONAR: project does not use PropTypes
+export const Tabs = ({ tabs, defaultTab, panelProps }) => { // NOSONAR: project does not use PropTypes
+  const { id: idPrefix } = useConfig()
   const names = tabs.map(t => t.name)
   const [activeTab, setActiveTab] = useState(defaultTab ?? names[0])
 
   const activateTab = useCallback((name) => {
     setActiveTab(name)
-    document.getElementById(toTabId(name))?.focus()
-  }, [])
+    document.getElementById(toTabId(idPrefix, name))?.focus()
+  }, [idPrefix])
 
   const handleKeyDown = useCallback((e) => {
     const idx = names.indexOf(activeTab)
@@ -33,7 +46,7 @@ export const Tabs = ({ tabs, defaultTab }) => { // NOSONAR: project does not use
     }
   }, [names, activeTab, activateTab])
 
-  const activeContent = tabs.find(t => t.name === activeTab)?.content
+  const panelClassName = ['im-c-tabs__panel', panelProps?.className].filter(Boolean).join(' ')
 
   return (
     <div className='im-c-tabs'>
@@ -42,10 +55,10 @@ export const Tabs = ({ tabs, defaultTab }) => { // NOSONAR: project does not use
           <button
             type='button'
             key={name}
-            id={toTabId(name)}
+            id={toTabId(idPrefix, name)}
             role='tab'
             aria-selected={activeTab === name}
-            aria-controls={toPanelId(name)}
+            aria-controls={toPanelId(idPrefix, name)}
             tabIndex={activeTab === name ? 0 : -1}
             className='im-c-tabs__tab'
             onClick={() => activateTab(name)}
@@ -55,15 +68,28 @@ export const Tabs = ({ tabs, defaultTab }) => { // NOSONAR: project does not use
           </button>
         ))}
       </div>
-      <div
-        id={toPanelId(activeTab)}
-        role='tabpanel'
-        aria-labelledby={toTabId(activeTab)}
-        tabIndex={-1} // nosonar — panel has no focusable children; -1 per ARIA tabs pattern (AT reads via role/aria-labelledby)
-        className='im-c-tabs__panel'
-      >
-        {activeContent}
-      </div>
+      {/* All tabpanels render, hidden unless active — not swapped in/out — so every tab's
+          aria-controls always resolves to a real element, rather than only the active one's.
+          panelProps (ref/tabIndex — a scrollable container's, from a caller like Panel.jsx)
+          can only meaningfully target one DOM node, so it's applied to the active panel only;
+          className is shared by all of them so there's nothing to restyle on switch. */}
+      {tabs.map(({ name, content }) => {
+        const isActive = activeTab === name
+        return (
+          <div
+            key={name}
+            ref={isActive ? panelProps?.ref : undefined}
+            id={toPanelId(idPrefix, name)}
+            role='tabpanel'
+            aria-labelledby={toTabId(idPrefix, name)}
+            tabIndex={isActive ? (panelProps?.tabIndex ?? -1) : -1} // nosonar — panel has no focusable children by default (-1); a scrollable active one wants 0, via panelProps
+            hidden={!isActive}
+            className={panelClassName}
+          >
+            {content}
+          </div>
+        )
+      })}
     </div>
   )
 }

package/src/App/components/Tabs/Tabs.module.scss

@@ -4,9 +4,18 @@
 // Component: Tabs
 // ===================================================
 
+// Lets a caller (e.g. Panel.jsx) give Tabs a bounded height — only .im-c-tabs__panel scrolls.
+.im-c-tabs {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    flex: 1 1 auto;
+}
+
 .im-c-tabs__list {
     position: relative;
     display: flex;
+    flex: 0 0 auto;
     flex-wrap: wrap;
     padding: 0;
     margin: 0;
@@ -14,8 +23,14 @@
     z-index: 1;
 }
 
+.im-c-tabs__panel {
+    flex: 1 1 auto;
+    overflow: auto;
+}
+
 .im-c-tabs__tab {
     position: relative;
+    z-index: 0; // scopes the active tab's ::before (below) to this button's own stacking context
     appearance: none;
     background: var(--button-hover-color);
     border: 1px solid transparent;
@@ -42,12 +57,24 @@
         }
     }
 
+    // The selected tab looks taller via an absolutely-positioned ::before rather than changing
+    // the button's own box, so the label never moves and the tablist's height never shifts.
     &[aria-selected='true'] {
-        background: var(--background-color);
-        border-color: var(--app-border-color);
-        border-bottom-color: var(--background-color);
-        margin-top: 0;
-        margin-bottom: -1px;
+        z-index: 1; // sit above unselected siblings
+        background: transparent;
+
+        &::before {
+            content: '';
+            position: absolute;
+            z-index: -1;
+            top: -5px;
+            right: -1px;
+            bottom: -6px;
+            left: -1px;
+            background: var(--background-color);
+            border: 1px solid var(--app-border-color);
+            border-bottom-color: var(--background-color);
+        }
     }
 
     &:focus .im-c-tabs__label {

package/src/App/components/Tabs/Tabs.test.jsx

@@ -1,11 +1,18 @@
 import React from 'react'
 import { render, screen, fireEvent } from '@testing-library/react'
 import { Tabs } from './Tabs'
+import { useConfig } from '../../store/configContext'
+
+jest.mock('../../store/configContext', () => ({ useConfig: jest.fn() }))
 
 const TAB_A = { name: 'Alpha', content: <p>Alpha content</p> }
 const TAB_B = { name: 'Beta', content: <p>Beta content</p> }
 const TAB_C = { name: 'Gamma', content: <p>Gamma content</p> }
 
+beforeEach(() => {
+  useConfig.mockReturnValue({ id: 'test-app' })
+})
+
 // ─── rendering ───────────────────────────────────────────────────────────────
 
 describe('Tabs — rendering', () => {
@@ -15,17 +22,17 @@ describe('Tabs — rendering', () => {
     expect(screen.getByRole('tab', { name: 'Beta' })).toBeInTheDocument()
   })
 
-  it('shows content for the active tab only', () => {
+  it('shows content for the active tab only — the inactive one stays in the DOM (so its aria-controls target exists) but hidden', () => {
     render(<Tabs tabs={[TAB_A, TAB_B]} />)
-    expect(screen.getByText('Alpha content')).toBeInTheDocument()
-    expect(screen.queryByText('Beta content')).not.toBeInTheDocument()
+    expect(screen.getByText('Alpha content')).toBeVisible()
+    expect(screen.getByText('Beta content')).not.toBeVisible()
   })
 
   it('uses defaultTab to set the initial active tab', () => {
     render(<Tabs tabs={[TAB_A, TAB_B]} defaultTab='Beta' />)
     expect(screen.getByRole('tab', { name: 'Beta' })).toHaveAttribute('aria-selected', 'true')
-    expect(screen.getByText('Beta content')).toBeInTheDocument()
-    expect(screen.queryByText('Alpha content')).not.toBeInTheDocument()
+    expect(screen.getByText('Beta content')).toBeVisible()
+    expect(screen.getByText('Alpha content')).not.toBeVisible()
   })
 
   it('falls back to first tab when defaultTab is not provided', () => {
@@ -41,8 +48,8 @@ describe('Tabs — click behaviour', () => {
     render(<Tabs tabs={[TAB_A, TAB_B]} />)
     fireEvent.click(screen.getByRole('tab', { name: 'Beta' }))
     expect(screen.getByRole('tab', { name: 'Beta' })).toHaveAttribute('aria-selected', 'true')
-    expect(screen.getByText('Beta content')).toBeInTheDocument()
-    expect(screen.queryByText('Alpha content')).not.toBeInTheDocument()
+    expect(screen.getByText('Beta content')).toBeVisible()
+    expect(screen.getByText('Alpha content')).not.toBeVisible()
   })
 })
 
@@ -55,10 +62,33 @@ describe('Tabs — WCAG attributes', () => {
     expect(screen.getByRole('tab', { name: 'Beta' })).toHaveAttribute('tabindex', '-1')
   })
 
-  it('each tab has aria-controls pointing to an element in the DOM', () => {
+  it('every tab has aria-controls pointing to a real element — including inactive tabs, since their panel stays in the DOM (hidden) rather than being unmounted', () => {
+    render(<Tabs tabs={[TAB_A, TAB_B]} />)
+    const activeTab = screen.getByRole('tab', { name: 'Alpha' })
+    const inactiveTab = screen.getByRole('tab', { name: 'Beta' })
+    expect(document.getElementById(activeTab.getAttribute('aria-controls'))).toBeInTheDocument()
+    expect(document.getElementById(inactiveTab.getAttribute('aria-controls'))).toBeInTheDocument()
+  })
+
+  it('gives every tabpanel its own stable id, distinct per tab, not just the active one', () => {
+    render(<Tabs tabs={[TAB_A, TAB_B]} />)
+    const activeTab = screen.getByRole('tab', { name: 'Alpha' })
+    const inactiveTab = screen.getByRole('tab', { name: 'Beta' })
+    expect(activeTab.getAttribute('aria-controls')).not.toBe(inactiveTab.getAttribute('aria-controls'))
+  })
+
+  it('hides the inactive tabpanel via the hidden attribute rather than unmounting it', () => {
+    render(<Tabs tabs={[TAB_A, TAB_B]} />)
+    const inactiveTab = screen.getByRole('tab', { name: 'Beta' })
+    const inactivePanel = document.getElementById(inactiveTab.getAttribute('aria-controls'))
+    expect(inactivePanel).toHaveAttribute('hidden')
+  })
+
+  it("labels every tabpanel with its own tab, not just the active one's", () => {
     render(<Tabs tabs={[TAB_A, TAB_B]} />)
-    const tab = screen.getByRole('tab', { name: 'Alpha' })
-    expect(document.getElementById(tab.getAttribute('aria-controls'))).toBeInTheDocument()
+    const inactiveTab = screen.getByRole('tab', { name: 'Beta' })
+    const inactivePanel = document.getElementById(inactiveTab.getAttribute('aria-controls'))
+    expect(inactivePanel.getAttribute('aria-labelledby')).toBe(inactiveTab.id)
   })
 
   it('panel has aria-labelledby pointing to the active tab', () => {

package/src/App/components/Tooltip/Tooltip.test.jsx

@@ -45,34 +45,32 @@ describe('Tooltip', () => {
 
   it('shows and hides tooltip on mouse interactions', () => {
     const { button, tooltip } = renderTooltip()
-    act(() => fireEvent.mouseEnter(button))
+    fireEvent.mouseEnter(button)
     advanceTimers()
     expect(tooltip).toHaveClass('im-c-tooltip--is-visible')
     expect(getTooltipPosition).toHaveBeenCalled()
-    act(() => fireEvent.mouseLeave(button))
+    fireEvent.mouseLeave(button)
     advanceTimers(0)
     expect(tooltip).not.toHaveClass('im-c-tooltip--is-visible')
   })
 
   it('cancels tooltip on mouse down or key down', () => {
     const { button, tooltip } = renderTooltip()
-    act(() => {
-      fireEvent.mouseEnter(button)
-      fireEvent.mouseDown(button)
-      fireEvent.mouseEnter(button)
-      fireEvent.keyDown(button)
-    })
+    fireEvent.mouseEnter(button)
+    fireEvent.mouseDown(button)
+    fireEvent.mouseEnter(button)
+    fireEvent.keyDown(button)
     advanceTimers()
     expect(tooltip).not.toHaveClass('im-c-tooltip--is-visible')
   })
 
   it('handles focus interactions for keyboard interface', () => {
     const { button, tooltip, wrapper } = renderTooltip({}, 'keyboard')
-    act(() => fireEvent.focus(button))
+    fireEvent.focus(button)
     advanceTimers()
     expect(wrapper).toHaveClass('im-c-tooltip-wrapper--has-focus')
     expect(tooltip).toHaveClass('im-c-tooltip--is-visible')
-    act(() => fireEvent.blur(button))
+    fireEvent.blur(button)
     advanceTimers(0)
     expect(wrapper).not.toHaveClass('im-c-tooltip-wrapper--has-focus')
     expect(tooltip).not.toHaveClass('im-c-tooltip--is-visible')
@@ -80,22 +78,22 @@ describe('Tooltip', () => {
 
   it('does not show tooltip on focus if interfaceType is mouse', () => {
     const { button, tooltip } = renderTooltip()
-    act(() => fireEvent.focus(button))
+    fireEvent.focus(button)
     advanceTimers()
     expect(tooltip).not.toHaveClass('im-c-tooltip--is-visible')
   })
 
   it('hides tooltip on Escape key', () => {
     const { button, tooltip } = renderTooltip()
-    act(() => fireEvent.mouseEnter(button))
+    fireEvent.mouseEnter(button)
     advanceTimers()
-    act(() => fireEvent.keyDown(window, { key: 'Escape' }))
+    fireEvent.keyDown(window, { key: 'Escape' })
     expect(tooltip).not.toHaveClass('im-c-tooltip--is-visible')
   })
 
   it('removes keydown listener on unmount', () => {
     const { button, unmount } = renderTooltip({}, 'keyboard')
-    act(() => fireEvent.mouseEnter(button))
+    fireEvent.mouseEnter(button)
     advanceTimers()
     const removeSpy = jest.spyOn(window, 'removeEventListener')
     unmount()

package/src/App/hooks/useFeatureItems.js

@@ -1,9 +1,12 @@
 import { useState, useEffect } from 'react'
 
+const SET_FEATURES = 'map:setfeatures'
+const SET_FEATURES_SUPPRESSED = 'map:setfeaturessuppressed'
+
 /**
- * Subscribes to map:setfeatures and exposes the current listbox item list and multiselectable flag.
- * The list is produced by useMapItemList in the interact plugin and pushed via the event bus
- * whenever the visible set of markers or features changes.
+ * Subscribes to map:setfeatures for the listbox item list, and map:setfeaturessuppressed
+ * (any plugin can emit this) to report items as empty while suppressed regardless of what's
+ * actually visible — which is what drives <Features>'s own tabIndex/aria-hidden.
  *
  * @param {object} eventBus
  * @returns {{ items: Array<{ id: string, label: string }>, multiselectable: boolean }}
@@ -11,20 +14,26 @@ import { useState, useEffect } from 'react'
 export function useFeatureItems (eventBus) {
   const [items, setItems] = useState([])
   const [multiselectable, setMultiselectable] = useState(false)
+  const [suppressed, setSuppressed] = useState(false)
 
   useEffect(() => {
     if (!eventBus) {
       return undefined
     }
-    const handle = ({ items: next = [], multiselectable: nextMultiselectable = false }) => {
+    const handleSetFeatures = ({ items: next = [], multiselectable: nextMultiselectable = false }) => {
       setItems(next)
       setMultiselectable(nextMultiselectable)
     }
-    eventBus.on('map:setfeatures', handle)
+    const handleSuppressed = ({ suppressed: next = false } = {}) => {
+      setSuppressed(next)
+    }
+    eventBus.on(SET_FEATURES, handleSetFeatures)
+    eventBus.on(SET_FEATURES_SUPPRESSED, handleSuppressed)
     return () => {
-      eventBus.off('map:setfeatures', handle)
+      eventBus.off(SET_FEATURES, handleSetFeatures)
+      eventBus.off(SET_FEATURES_SUPPRESSED, handleSuppressed)
     }
   }, [eventBus])
 
-  return { items, multiselectable }
+  return { items: suppressed ? [] : items, multiselectable }
 }

package/src/App/hooks/useFeatureItems.test.js

@@ -2,6 +2,7 @@ import { renderHook, act } from '@testing-library/react'
 import { useFeatureItems } from './useFeatureItems.js'
 
 const SET_FEATURES = 'map:setfeatures' // NOSONAR
+const SET_FEATURES_SUPPRESSED = 'map:setfeaturessuppressed' // NOSONAR
 
 const makeEventBus = () => {
   const listeners = {}
@@ -37,11 +38,18 @@ describe('useFeatureItems — event subscription', () => {
     expect(eb.on).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
   })
 
+  it('subscribes to map:setfeaturessuppressed on mount', () => {
+    const eb = makeEventBus()
+    renderHook(() => useFeatureItems(eb))
+    expect(eb.on).toHaveBeenCalledWith(SET_FEATURES_SUPPRESSED, expect.any(Function))
+  })
+
   it('unsubscribes on unmount', () => {
     const eb = makeEventBus()
     const { unmount } = renderHook(() => useFeatureItems(eb))
     unmount()
     expect(eb.off).toHaveBeenCalledWith(SET_FEATURES, expect.any(Function))
+    expect(eb.off).toHaveBeenCalledWith(SET_FEATURES_SUPPRESSED, expect.any(Function))
   })
 
   it('does not subscribe when eventBus is undefined', () => {
@@ -96,3 +104,52 @@ describe('useFeatureItems — multiselectable updates', () => {
     expect(result.current.multiselectable).toBe(false)
   })
 })
+
+// ─── useFeatureItems — suppression ───────────────────────────────────────────
+
+describe('useFeatureItems — suppression', () => {
+  const items = [{ id: 'a', label: 'Feature A' }]
+
+  it('reports empty items while suppressed, regardless of what was last set', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    expect(result.current.items).toEqual([])
+  })
+
+  it('restores the last known items once suppression is lifted', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: false }))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('defaults suppressed to false when the payload omits it', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, {}))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('defaults suppressed to false when the event carries no payload at all', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED))
+    expect(result.current.items).toEqual(items)
+  })
+
+  it('a features update received while suppressed is still applied once restored', () => {
+    const eb = makeEventBus()
+    const { result } = renderHook(() => useFeatureItems(eb))
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: true }))
+    act(() => eb.emit(SET_FEATURES, { items }))
+    expect(result.current.items).toEqual([]) // still suppressed
+    act(() => eb.emit(SET_FEATURES_SUPPRESSED, { suppressed: false }))
+    expect(result.current.items).toEqual(items)
+  })
+})