From 1ddbbff8a46f10c63570f3e5833bbace56525c19 Mon Sep 17 00:00:00 2001
From: Dan Leech <dan.leech@defra.gov.uk>
Date: Thu, 16 Jul 2026 17:24:44 +0100
Subject: [PATCH] Support aria-controls for buttons that toggle non-panel/popup
 UI

Adds an `ariaControls` button-config prop (string or context-fn) that sets
aria-controls directly, for buttons that expand a plugin-owned control
rather than a panel or popup menu. Also scopes plugin dispatch to the
originating plugin id so it routes correctly through the combined
reducer when called from evaluated props.

Extracted from the search-refactor branch so button+control consumers
don't need to depend on that branch landing first.
---
 docs/api/button-definition.md                   | 13 +++++++++++++
 src/App/components/MapButton/MapButton.jsx      | 12 ++++++++++--
 src/App/components/MapButton/MapButton.test.jsx | 10 ++++++++++
 src/App/hooks/useEvaluateProp.js                |  7 ++++++-
 src/App/hooks/useEvaluateProp.test.js           | 12 ++++++++++--
 src/App/renderer/mapButtons.js                  |  1 +
 src/types.js                                    |  5 +++++
 7 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/docs/api/button-definition.md b/docs/api/button-definition.md
index 499f4b0de..9281bc3dc 100644
--- a/docs/api/button-definition.md
+++ b/docs/api/button-definition.md
@@ -90,6 +90,19 @@ Associated panel identifier. When set, clicking the button toggles the panel ope
 
 ---
 
+### `ariaControls`
+**Type:** `string | function`
+
+Id of a custom control this button toggles, applied as `aria-controls`. Use when the button opens or expands a custom control rendered elsewhere by the plugin. Can be a string or a function that receives the [Context](./context.md) and returns the id.
+
+```js
+ariaControls: (context) => `${context.appConfig.id}-search-form`
+```
+
+> Pair this with [`expandedWhen`](#expandedwhen) to also reflect the open/closed state via `aria-expanded`.
+
+---
+
 ### `keepFocus`
 **Type:** `boolean`
 **Default:** `false`
diff --git a/src/App/components/MapButton/MapButton.jsx b/src/App/components/MapButton/MapButton.jsx
index fe9237f1c..b847d5ad9 100755
--- a/src/App/components/MapButton/MapButton.jsx
+++ b/src/App/components/MapButton/MapButton.jsx
@@ -123,6 +123,9 @@ const getControlledElement = ({ idPrefix, panelId, buttonId, hasMenu }) => {
  * @param {boolean} options.isPanelOpen - Whether the controlled panel is open
  * @param {boolean} options.isPopupOpen - Whether the popup menu is open
  * @param {Object|null} options.controlledElement - The element controlled by this button
+ * @param {string} [options.ariaControls] - Explicit id for aria-controls when the button controls
+ *   inline UI that is neither a panel nor a popup (e.g. a plugin-owned control). Ignored when
+ *   controlledElement is set, which takes precedence.
  * @param {string} options.href - URL for anchor element (if provided, renders as <a> instead of <button>)
  * @returns {Object} Props object suitable for button or anchor element
  */
@@ -140,6 +143,7 @@ const buildButtonProps = ({
   isPanelOpen,
   isPopupOpen,
   controlledElement,
+  ariaControls,
   href
 }) => {
   let ariaExpanded
@@ -163,7 +167,7 @@ const buildButtonProps = ({
     'aria-disabled': isDisabled || undefined,
     'aria-expanded': ariaExpanded,
     'aria-pressed': typeof isPressed === 'boolean' ? isPressed : undefined,
-    'aria-controls': controlledElement?.id,
+    'aria-controls': controlledElement?.id ?? ariaControls,
     'aria-haspopup': controlledElement?.type === 'popup' ? 'menu' : undefined,
     ...(href
       ? { href, target: '_blank', onKeyUp: handleKeyUp, role: 'button' }
@@ -193,6 +197,8 @@ const buildButtonProps = ({
  * @param {Array<Object>} [props.menuItems] - Array of items for popup menu
  * @param {string} [props.idPrefix=''] - Prefix for generated panel/popup IDs
  * @param {string} [props.href] - URL for anchor element; if provided, renders as <a> instead of <button>
+ * @param {string} [props.ariaControls] - Explicit aria-controls target id for buttons that toggle
+ *   inline UI which is neither a panel nor a popup (a panelId/menuItems always takes precedence).
  * @returns {JSX.Element} The rendered button component
  */
 export const MapButton = ({
@@ -211,7 +217,8 @@ export const MapButton = ({
   panelId,
   menuItems,
   idPrefix,
-  href
+  href,
+  ariaControls
 }) => {
   const { id: appId } = useConfig()
   const { buttonRefs } = useApp()
@@ -275,6 +282,7 @@ export const MapButton = ({
     isPanelOpen,
     isPopupOpen,
     controlledElement,
+    ariaControls,
     href
   })
 
diff --git a/src/App/components/MapButton/MapButton.test.jsx b/src/App/components/MapButton/MapButton.test.jsx
index f29dc8773..d1a1db898 100755
--- a/src/App/components/MapButton/MapButton.test.jsx
+++ b/src/App/components/MapButton/MapButton.test.jsx
@@ -96,6 +96,16 @@ describe('MapButton', () => {
     expect(getButton()).toHaveAttribute('aria-expanded', 'true')
   })
 
+  it('sets aria-controls from ariaControls when there is no panel or popup', () => {
+    renderButton({ ariaControls: 'map-search-form' })
+    expect(getButton()).toHaveAttribute('aria-controls', 'map-search-form')
+  })
+
+  it('prefers a controlled panel/popup id over ariaControls', () => {
+    renderButton({ panelId: 'Settings', idPrefix: 'prefix', ariaControls: 'ignored' })
+    expect(getButton()).toHaveAttribute('aria-controls', 'prefix-panel-settings')
+  })
+
   it('handles click events', () => {
     const onClick = jest.fn()
     renderButton({ onClick })
diff --git a/src/App/hooks/useEvaluateProp.js b/src/App/hooks/useEvaluateProp.js
index 7e51bab8d..1c9a008a6 100644
--- a/src/App/hooks/useEvaluateProp.js
+++ b/src/App/hooks/useEvaluateProp.js
@@ -33,7 +33,12 @@ export function useEvaluateProp () {
     // Framework entries like 'appConfig' have no reducer so their buttons get pluginStates instead.
     if (Object.hasOwn(pluginContext?.state ?? {}, pluginId)) {
       const stateForPlugin = pluginContext?.state?.[pluginId] ?? {}
-      const pluginState = { ...stateForPlugin, dispatch: pluginContext?.dispatch }
+      // Scope dispatch to this plugin, mirroring usePlugin — the combined reducer
+      // routes by action.pluginId, so an unscoped dispatch would be a no-op.
+      const pluginState = {
+        ...stateForPlugin,
+        dispatch: (action) => pluginContext?.dispatch?.({ ...action, pluginId })
+      }
       return { pluginConfig, pluginState }
     }
 
diff --git a/src/App/hooks/useEvaluateProp.test.js b/src/App/hooks/useEvaluateProp.test.js
index 65b8a7888..0ba2ebeb3 100644
--- a/src/App/hooks/useEvaluateProp.test.js
+++ b/src/App/hooks/useEvaluateProp.test.js
@@ -100,7 +100,15 @@ describe('useEvaluateProp — plugin state isolation', () => {
     const { result } = renderHook(() => useEvaluateProp(), { wrapper: withPluginContext })
     const ctx = result.current(c => c, 'myPlugin')
     expect(ctx.pluginConfig).toEqual({ pluginId: 'myPlugin', includeModes: ['edit'], excludeModes: ['view'] })
-    expect(ctx.pluginState).toMatchObject({ foo: 'bar', dispatch: pluginDispatch })
+    expect(ctx.pluginState).toMatchObject({ foo: 'bar', dispatch: expect.any(Function) })
+  })
+
+  it('scopes pluginState.dispatch to the plugin by injecting pluginId', () => {
+    mockPluginRegistry.registeredPlugins.push({ id: 'myPlugin', config: {} })
+    const { result } = renderHook(() => useEvaluateProp(), { wrapper: withPluginContext })
+    const ctx = result.current(c => c, 'myPlugin')
+    ctx.pluginState.dispatch({ type: 'DO_THING', payload: 1 })
+    expect(pluginDispatch).toHaveBeenCalledWith({ type: 'DO_THING', payload: 1, pluginId: 'myPlugin' })
   })
 
   it('does not include pluginStates for real plugin buttons', () => {
@@ -123,6 +131,6 @@ describe('useEvaluateProp — plugin state isolation', () => {
     )
     const { result } = renderHook(() => useEvaluateProp(), { wrapper })
     const ctx = result.current(c => c, 'myPlugin')
-    expect(ctx.pluginState).toMatchObject({ dispatch: pluginDispatch })
+    expect(ctx.pluginState).toMatchObject({ dispatch: expect.any(Function) })
   })
 })
diff --git a/src/App/renderer/mapButtons.js b/src/App/renderer/mapButtons.js
index 308507517..e9753754d 100755
--- a/src/App/renderer/mapButtons.js
+++ b/src/App/renderer/mapButtons.js
@@ -159,6 +159,7 @@ function renderButton ({ btn, appState, appConfig, evaluateProp }) {
       panelId={config.panelId}
       menuItems={config.menuItems}
       idPrefix={appConfig.id}
+      ariaControls={evaluateProp(config.ariaControls, config.pluginId)}
     />
   )
 }
diff --git a/src/types.js b/src/types.js
index 3d499ca61..615e592a7 100644
--- a/src/types.js
+++ b/src/types.js
@@ -131,6 +131,11 @@
  *
  * @typedef {Object} ButtonDefinition
  *
+ * @property {string | ((context: PluginContext) => string)} [ariaControls]
+ * Id of a custom control this button toggles, set as aria-controls. Use when the button
+ * opens or expands a custom control rendered elsewhere by the plugin. Text or a function
+ * returning the id.
+ *
  * @property {ButtonBreakpointConfig} [desktop]
  * Desktop breakpoint configuration.
  *