@defra/interactive-map 0.0.3-alpha → 0.0.5-alpha

package/src/App/registry/panelRegistry.test.js

@@ -1,4 +1,4 @@
-import { registerPanel, addPanel, removePanel, getPanelConfig } from './panelRegistry.js'
+import { createPanelRegistry, registerPanel, addPanel, removePanel, getPanelConfig } from './panelRegistry.js'
 import { defaultPanelConfig } from '../../config/appConfig.js'
 
 describe('panelRegistry', () => {
@@ -88,4 +88,33 @@ describe('panelRegistry', () => {
     expect(updatedConfig.panel1).toBeUndefined()
     expect(updatedConfig).not.toBe(config) // Immutable
   })
+
+  describe('createPanelRegistry (Factory)', () => {
+    let registry
+
+    beforeEach(() => {
+      registry = createPanelRegistry()
+    })
+
+    test('should manage state internally via all methods', () => {
+      // Test registerPanel state
+      registry.registerPanel({ p1: { title: 'P1' } })
+      expect(registry.getPanelConfig()).toHaveProperty('p1')
+      expect(registry.getPanelConfig().p1.showLabel).toBe(true)
+
+      // Test addPanel state and return value
+      const added = registry.addPanel('p2', { title: 'P2' })
+      expect(added.title).toBe('P2')
+      expect(registry.getPanelConfig()).toHaveProperty('p2')
+
+      // Test removePanel state
+      registry.removePanel('p1')
+      expect(registry.getPanelConfig()).not.toHaveProperty('p1')
+      expect(registry.getPanelConfig()).toHaveProperty('p2')
+
+      // Test clear state
+      registry.clear()
+      expect(registry.getPanelConfig()).toEqual({})
+    })
+  })
 })

package/src/App/registry/pluginRegistry.js

@@ -2,6 +2,8 @@
 import { registerIcon } from './iconRegistry.js'
 import { registerKeyboardShortcut } from './keyboardShortcutRegistry.js'
 
+const asArray = (value) => Array.isArray(value) ? value : [value]
+
 export function createPluginRegistry ({ registerButton, registerPanel, registerControl }) {
   const registeredPlugins = []
 
@@ -14,76 +16,37 @@ export function createPluginRegistry ({ registerButton, registerPanel, registerC
       excludeModes: plugin.config?.excludeModes
     }
 
-    // --- Register buttons ---
     if (manifest.buttons) {
-      const buttons = Array.isArray(manifest.buttons)
-        ? manifest.buttons
-        : [manifest.buttons]
-
-      buttons.forEach(button => {
-        registerButton({
-          [button.id]: {
-            ...pluginConfig,
-            ...button
-          }
+      asArray(manifest.buttons).forEach(button => {
+        registerButton({ [button.id]: { ...pluginConfig, ...button } })
+        // Flat button registry including anu menu items
+        button?.menuItems?.forEach(menuItem => {
+          registerButton({ [menuItem.id]: { ...pluginConfig, ...menuItem } })
         })
       })
     }
 
-    // --- Register panels ---
     if (manifest.panels) {
-      const panels = Array.isArray(manifest.panels)
-        ? manifest.panels
-        : [manifest.panels]
-
-      panels.forEach(panel => {
-        registerPanel({
-          [panel.id]: {
-            ...pluginConfig,
-            ...panel
-          }
-        })
+      asArray(manifest.panels).forEach(panel => {
+        registerPanel({ [panel.id]: { ...pluginConfig, ...panel } })
       })
     }
 
-    // --- Register controls ---
     if (manifest.controls) {
-      const controls = Array.isArray(manifest.controls)
-        ? manifest.controls
-        : [manifest.controls]
-
-      controls.forEach(control => {
-        registerControl({
-          [control.id]: {
-            ...pluginConfig,
-            ...control
-          }
-        })
+      asArray(manifest.controls).forEach(control => {
+        registerControl({ [control.id]: { ...pluginConfig, ...control } })
       })
     }
 
-    // --- Register icons ---
     if (manifest.icons) {
-      const icons = Array.isArray(manifest.icons)
-        ? manifest.icons
-        : [manifest.icons]
-
-      icons.forEach(icon =>
+      asArray(manifest.icons).forEach(icon =>
         registerIcon({ [icon.id]: icon.svgContent })
       )
     }
 
-    // --- Register keyboard shortcuts ---
     if (manifest.keyboardShortcuts) {
-      const shortcuts = Array.isArray(manifest.keyboardShortcuts)
-        ? manifest.keyboardShortcuts
-        : [manifest.keyboardShortcuts]
-
-      shortcuts.forEach(shortcut =>
-        registerKeyboardShortcut({
-          ...pluginConfig,
-          shortcut
-        })
+      asArray(manifest.keyboardShortcuts).forEach(shortcut =>
+        registerKeyboardShortcut({ ...pluginConfig, shortcut })
       )
     }
 

package/src/App/registry/pluginRegistry.test.js

@@ -41,7 +41,7 @@ describe('pluginRegistry', () => {
         buttons: { id: 'btn1' },
         panels: [{ id: 'panel1' }],
         controls: { id: 'ctrl1' },
-        icons: { id: 'icon1', svgContent: 'Comp' }, // match implementation
+        icons: { id: 'icon1', svgContent: 'Comp' },
         keyboardShortcuts: { key: 'K' }
       }
     }
@@ -65,15 +65,50 @@ describe('pluginRegistry', () => {
     })
     expect(registerIcon).toHaveBeenCalledWith({ icon1: 'Comp' })
     expect(registerKeyboardShortcut).toHaveBeenCalledWith(
-      expect.objectContaining({
-        ...expectedPluginConfig,
-        shortcut: { key: 'K' }
-      })
+      expect.objectContaining({ ...expectedPluginConfig, shortcut: { key: 'K' } })
     )
-
     expect(pluginRegistry.registeredPlugins).toContain(plugin)
   })
 
+  it('registers nested menuItems for buttons', () => {
+    const plugin = {
+      id: 'plugin-menu',
+      config: { includeModes: ['mode1'], excludeModes: [] },
+      manifest: {
+        buttons: [
+          {
+            id: 'parentBtn',
+            menuItems: [
+              { id: 'childBtn1', label: 'Child 1' },
+              { id: 'childBtn2', label: 'Child 2' }
+            ]
+          }
+        ]
+      }
+    }
+
+    pluginRegistry.registerPlugin(plugin)
+
+    const expectedPluginConfig = {
+      pluginId: 'plugin-menu',
+      includeModes: ['mode1'],
+      excludeModes: []
+    }
+
+    // Parent button
+    expect(registerButton).toHaveBeenCalledWith({
+      parentBtn: expect.objectContaining(expectedPluginConfig)
+    })
+
+    // Each menu item
+    expect(registerButton).toHaveBeenCalledWith({
+      childBtn1: expect.objectContaining(expectedPluginConfig)
+    })
+    expect(registerButton).toHaveBeenCalledWith({
+      childBtn2: expect.objectContaining(expectedPluginConfig)
+    })
+  })
+
   it('handles single vs array manifests correctly', () => {
     const plugin = {
       id: 'plugin3',
@@ -103,4 +138,17 @@ describe('pluginRegistry', () => {
     pluginRegistry.registerPlugin(pluginB)
     expect(pluginRegistry.registeredPlugins).toEqual([pluginA, pluginB])
   })
+
+  it('clears all registered plugins', () => {
+    const pluginA = { id: 'A', config: {}, manifest: {} }
+    const pluginB = { id: 'B', config: {}, manifest: {} }
+
+    pluginRegistry.registerPlugin(pluginA)
+    pluginRegistry.registerPlugin(pluginB)
+    expect(pluginRegistry.registeredPlugins.length).toBe(2)
+
+    pluginRegistry.clear()
+    expect(pluginRegistry.registeredPlugins.length).toBe(0)
+    expect(pluginRegistry.registeredPlugins).toEqual([])
+  })
 })

package/src/App/renderer/HtmlElementHost.jsx

@@ -0,0 +1,186 @@
+// src/App/renderer/HtmlElementHost.jsx
+import React, { useRef, useEffect, useMemo } from 'react'
+import { useApp } from '../store/appContext.js'
+import { Panel } from '../components/Panel/Panel.jsx'
+import { resolveTargetSlot, isModeAllowed, isControlVisible, isConsumerHtml } from './slotHelpers.js'
+import { allowedSlots } from './slots.js'
+import { stringToKebab } from '../../utils/stringToKebab.js'
+
+/**
+ * Maps slot names to their corresponding layout refs.
+ */
+export const getSlotRef = (slot, layoutRefs) => {
+  const slotRefMap = {
+    side: layoutRefs.sideRef,
+    banner: layoutRefs.bannerRef,
+    'top-left': layoutRefs.topLeftColRef,
+    'top-right': layoutRefs.topRightColRef,
+    inset: layoutRefs.insetRef,
+    middle: layoutRefs.middleRef,
+    bottom: layoutRefs.bottomRef,
+    actions: layoutRefs.actionsRef,
+    modal: layoutRefs.modalRef
+  }
+  return slotRefMap[slot] || null
+}
+
+/**
+ * Manages DOM projection for a single persistent element.
+ * Moves the wrapper into the target slot when visible, hides it otherwise.
+ * Depends on breakpoint to handle conditionally rendered slot containers
+ * (e.g. the banner slot swaps DOM nodes between mobile and desktop).
+ */
+export const useDomProjection = (wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint) => {
+  useEffect(() => {
+    const wrapper = wrapperRef.current
+
+    if (isVisible) {
+      const slotRef = getSlotRef(targetSlot, layoutRefs)
+      if (slotRef?.current) {
+        slotRef.current.appendChild(wrapper)
+        wrapper.style.display = ''
+      }
+    } else {
+      wrapper.style.display = 'none'
+    }
+
+    return () => {
+      wrapper.style.display = 'none'
+    }
+  }, [isVisible, targetSlot, layoutRefs, breakpoint, wrapperRef])
+}
+
+/**
+ * Persistent wrapper for a consumer HTML panel.
+ * The Panel component stays mounted for the lifetime of the registration.
+ * DOM projection moves it between slots; CSS hides it when closed.
+ */
+const PersistentPanel = ({ panelId, config, isOpen, openPanelProps, allowedModalPanelId, appState }) => {
+  const panelRootRef = useRef(null)
+  const { breakpoint, mode, isFullscreen, layoutRefs } = appState
+
+  const bpConfig = config[breakpoint]
+  const targetSlot = bpConfig ? resolveTargetSlot(bpConfig, breakpoint) : null
+
+  // Determine visibility using the same logic as mapPanels
+  const isVisible = (() => {
+    // 1. Initial Guard: Basic requirements
+    if (!isOpen || !bpConfig || !targetSlot) {
+      return false
+    }
+
+    // 2. Slot Validation
+    const isNextToButton = `${stringToKebab(panelId)}-button` === targetSlot
+    const isSlotAllowed = allowedSlots.panel.includes(targetSlot) || isNextToButton
+
+    if (!isSlotAllowed) {
+      return false
+    }
+
+    // 3. Business Logic: Combine remaining conditions into a single "fail" check
+    const isForbiddenModal = bpConfig.modal && panelId !== allowedModalPanelId
+    const isForbiddenInline = config.inline === false && !isFullscreen
+    const isInvalidMode = !isModeAllowed(config, mode)
+
+    return !(isForbiddenModal || isForbiddenInline || isInvalidMode)
+  })()
+
+  useDomProjection(panelRootRef, targetSlot, isVisible, layoutRefs, breakpoint)
+
+  return (
+    <Panel
+      panelId={panelId}
+      panelConfig={config}
+      props={openPanelProps}
+      html={config.html}
+      label={config.label}
+      isOpen={isOpen}
+      rootRef={panelRootRef}
+    />
+  )
+}
+
+/**
+ * Persistent wrapper for a consumer HTML control.
+ * The control stays mounted for the lifetime of the registration.
+ */
+const PersistentControl = ({ control, appState }) => {
+  const wrapperRef = useRef(null)
+  const { breakpoint, mode, isFullscreen, layoutRefs } = appState
+
+  const bpConfig = control[breakpoint]
+  const isVisible = isControlVisible(control, { breakpoint, mode, isFullscreen })
+  const targetSlot = bpConfig?.slot || null
+
+  useDomProjection(wrapperRef, targetSlot, isVisible, layoutRefs, breakpoint)
+
+  const innerHtml = useMemo(() => ({ __html: control.html }), [control.html])
+
+  return (
+    <div
+      ref={wrapperRef}
+      className='im-c-control'
+      style={{ display: 'none' }}
+      dangerouslySetInnerHTML={innerHtml}
+    />
+  )
+}
+
+/**
+ * Renders all consumer HTML panels and controls persistently.
+ * Items mount once on registration and only unmount on deregistration.
+ * Visibility and slot placement are handled by DOM projection, not React mount/unmount.
+ */
+export const HtmlElementHost = () => {
+  const appState = useApp()
+  const { panelConfig = {}, controlConfig = {}, openPanels = {}, breakpoint } = appState
+
+  // Find consumer HTML panels
+  const htmlPanels = useMemo(() =>
+    Object.entries(panelConfig).filter(([_, config]) => isConsumerHtml(config)),
+  [panelConfig]
+  )
+
+  // Find consumer HTML controls
+  const htmlControls = useMemo(() =>
+    Object.values(controlConfig).filter(control => isConsumerHtml(control)),
+  [controlConfig]
+  )
+
+  // Determine which modal panel is allowed (topmost open modal)
+  const allowedModalPanelId = useMemo(() => {
+    const openPanelEntries = Object.entries(openPanels)
+    const modalPanels = openPanelEntries.filter(([panelId]) => {
+      const cfg = panelConfig[panelId]?.[breakpoint]
+      return cfg?.modal
+    })
+    return modalPanels.length > 0 ? modalPanels[modalPanels.length - 1][0] : null
+  }, [openPanels, panelConfig, breakpoint])
+
+  if (!htmlPanels.length && !htmlControls.length) {
+    return null
+  }
+
+  return (
+    <>
+      {htmlPanels.map(([panelId, config]) => (
+        <PersistentPanel
+          key={panelId}
+          panelId={panelId}
+          config={config}
+          isOpen={!!openPanels[panelId]}
+          openPanelProps={openPanels[panelId]?.props}
+          allowedModalPanelId={allowedModalPanelId}
+          appState={appState}
+        />
+      ))}
+      {htmlControls.map(control => (
+        <PersistentControl
+          key={control.id}
+          control={control}
+          appState={appState}
+        />
+      ))}
+    </>
+  )
+}

package/src/App/renderer/HtmlElementHost.test.jsx

@@ -0,0 +1,231 @@
+import React from 'react'
+import { render } from '@testing-library/react'
+import { HtmlElementHost, getSlotRef } from './HtmlElementHost.jsx'
+import { useApp } from '../store/appContext'
+
+jest.mock('../store/appContext', () => ({ useApp: jest.fn() }))
+jest.mock('../store/configContext', () => ({ useConfig: jest.fn(() => ({ id: 'test' })) }))
+jest.mock('../components/Panel/Panel.jsx', () => ({
+  Panel: ({ panelId, html, isOpen, rootRef }) => (
+    <div ref={rootRef} data-testid={`panel-${panelId}`} data-open={isOpen}>
+      {html}
+    </div>
+  )
+}))
+jest.mock('./slots.js', () => ({
+  allowedSlots: {
+    panel: ['inset', 'side', 'modal', 'bottom'],
+    control: ['inset', 'banner', 'bottom', 'actions']
+  }
+}))
+
+/**
+ * Wrapper that provides real DOM slot containers as refs.
+ * This keeps projected nodes inside React's render tree so cleanup works.
+ */
+const SlotHarness = ({ layoutRefs, children }) => (
+  <div>
+    <div ref={layoutRefs.insetRef} data-slot='inset' />
+    <div ref={layoutRefs.sideRef} data-slot='side' />
+    <div ref={layoutRefs.modalRef} data-slot='modal' />
+    <div ref={layoutRefs.bottomRef} data-slot='bottom' />
+    <div ref={layoutRefs.bannerRef} data-slot='banner' />
+    <div ref={layoutRefs.actionsRef} data-slot='actions' />
+    {children}
+  </div>
+)
+
+describe('HtmlElementHost', () => {
+  let layoutRefs
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    layoutRefs = {
+      sideRef: { current: null },
+      bannerRef: { current: null },
+      topLeftColRef: { current: null },
+      topRightColRef: { current: null },
+      insetRef: { current: null },
+      middleRef: { current: null },
+      bottomRef: { current: null },
+      actionsRef: { current: null },
+      modalRef: { current: null },
+      viewportRef: { current: null },
+      mainRef: { current: null }
+    }
+  })
+
+  const mockApp = (overrides = {}) => {
+    const state = {
+      breakpoint: 'desktop',
+      mode: 'view',
+      isFullscreen: false,
+      panelConfig: {},
+      controlConfig: {},
+      openPanels: {},
+      layoutRefs,
+      dispatch: jest.fn(),
+      ...overrides
+    }
+    useApp.mockReturnValue(state)
+    return state
+  }
+
+  const renderWithSlots = (appOverrides = {}) => {
+    mockApp(appOverrides)
+    return render(
+      <SlotHarness layoutRefs={layoutRefs}>
+        <HtmlElementHost />
+      </SlotHarness>
+    )
+  }
+
+  it('renders nothing when no consumer HTML panels or controls exist', () => {
+    mockApp()
+    const { container } = render(<HtmlElementHost />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('ignores plugin panels (with pluginId)', () => {
+    mockApp({
+      panelConfig: { p1: { pluginId: 'plug1', html: '<p>Hi</p>', desktop: { slot: 'inset' } } },
+      openPanels: { p1: { props: {} } }
+    })
+    const { container } = render(<HtmlElementHost />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('ignores plugin controls (with pluginId)', () => {
+    mockApp({
+      controlConfig: { c1: { id: 'c1', pluginId: 'plug1', html: '<p>Hi</p>', desktop: { slot: 'inset' } } }
+    })
+    const { container } = render(<HtmlElementHost />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('projects open panel into correct slot', () => {
+    const { container } = renderWithSlots({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Test', desktop: { slot: 'inset' } } },
+      openPanels: { p1: { props: {} } }
+    })
+    expect(container.querySelector('[data-slot="inset"] [data-testid="panel-p1"]')).toBeTruthy()
+  })
+
+  it('hides panel when closed and passes isOpen=false', () => {
+    const { getByTestId } = renderWithSlots({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Test', desktop: { slot: 'inset' } } },
+      openPanels: {}
+    })
+    expect(getByTestId('panel-p1').style.display).toBe('none')
+    expect(getByTestId('panel-p1').dataset.open).toBe('false')
+  })
+
+  it('hides panel when mode is not allowed', () => {
+    const { getByTestId } = renderWithSlots({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Test', desktop: { slot: 'inset' }, includeModes: ['edit'] } },
+      openPanels: { p1: { props: {} } }
+    })
+    expect(getByTestId('panel-p1').style.display).toBe('none')
+  })
+
+  it('hides panel with inline:false when not fullscreen', () => {
+    const { getByTestId } = renderWithSlots({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Test', desktop: { slot: 'inset' }, inline: false } },
+      openPanels: { p1: { props: {} } },
+      isFullscreen: false
+    })
+    expect(getByTestId('panel-p1').style.display).toBe('none')
+  })
+
+  it('resolves bottom slot to inset on desktop', () => {
+    const { container } = renderWithSlots({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Test', desktop: { slot: 'bottom' } } },
+      openPanels: { p1: { props: {} } }
+    })
+    expect(container.querySelector('[data-slot="inset"] [data-testid="panel-p1"]')).toBeTruthy()
+    expect(container.querySelector('[data-slot="bottom"] [data-testid="panel-p1"]')).toBeNull()
+  })
+
+  it('only shows topmost modal panel', () => {
+    const { getByTestId, container } = renderWithSlots({
+      panelConfig: {
+        p1: { html: '<p>1</p>', label: 'M1', desktop: { slot: 'side', modal: true } },
+        p2: { html: '<p>2</p>', label: 'M2', desktop: { slot: 'side', modal: true } }
+      },
+      openPanels: { p1: { props: {} }, p2: { props: {} } }
+    })
+    expect(getByTestId('panel-p1').style.display).toBe('none')
+    expect(container.querySelector('[data-slot="modal"] [data-testid="panel-p2"]')).toBeTruthy()
+  })
+
+  it('hides panel when breakpoint config is missing', () => {
+    const { getByTestId } = renderWithSlots({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Test', mobile: { slot: 'inset' } } },
+      openPanels: { p1: { props: {} } },
+      breakpoint: 'desktop'
+    })
+    expect(getByTestId('panel-p1').style.display).toBe('none')
+  })
+
+  it('projects visible control into correct slot', () => {
+    const { container } = renderWithSlots({
+      controlConfig: { c1: { id: 'c1', html: '<input type="checkbox">', desktop: { slot: 'inset' } } }
+    })
+    const control = container.querySelector('[data-slot="inset"] .im-c-control')
+    expect(control).toBeTruthy()
+    expect(control.innerHTML).toBe('<input type="checkbox">')
+  })
+
+  it('hides panel when slot is not allowed', () => {
+    const { getByTestId } = renderWithSlots({
+      panelConfig: { p1: { html: '<p>Hi</p>', label: 'Test', desktop: { slot: 'invalid' } } },
+      openPanels: { p1: { props: {} } }
+    })
+    expect(getByTestId('panel-p1').style.display).toBe('none')
+  })
+
+  it('hides control when breakpoint config is missing', () => {
+    const { container } = renderWithSlots({
+      controlConfig: { c1: { id: 'c1', html: '<p>Hi</p>', mobile: { slot: 'inset' } } },
+      breakpoint: 'desktop'
+    })
+    const control = container.querySelector('.im-c-control')
+    expect(control.style.display).toBe('none')
+  })
+
+  it('uses default empty objects when appState is missing configs', () => {
+    useApp.mockReturnValue({}) // no panelConfig/controlConfig/openPanels/breakpoint
+    const { container } = render(<HtmlElementHost />)
+    expect(container.firstChild).toBeNull() // still renders safely
+  })
+
+  test('getSlotRef returns null for unknown slot', () => {
+    expect(getSlotRef('unknown-slot', {})).toBeNull()
+  })
+
+  it('does not append child if slotRef exists but current is null', () => {
+    // 1. Setup refs where the slot exists in the map but the DOM node (current) is null
+    const incompleteRefs = {
+      ...layoutRefs,
+      sideRef: { current: null }
+    }
+
+    // 2. Mock the app so the panel IS visible, but the slot it wants is the broken one
+    mockApp({
+      panelConfig: { p1: { html: '<b>Hi</b>', desktop: { slot: 'side' } } },
+      openPanels: { p1: { props: {} } },
+      layoutRefs: incompleteRefs
+    })
+
+    const { getByTestId, container } = render(<HtmlElementHost />)
+
+    const panel = getByTestId('panel-p1')
+
+    // 3. Verify that the panel was NOT moved into a slot container
+    // Since sideRef.current is null, it should still be sitting in the root of the Host
+    expect(container.querySelector('[data-slot="side"] [data-testid="panel-p1"]')).toBeNull()
+
+    // The panel exists in the DOM but hasn't been "projected"
+    expect(panel).toBeTruthy()
+  })
+})