@defra/interactive-map 0.0.36-alpha → 0.0.38-alpha

package/src/services/announcer.js

@@ -19,15 +19,35 @@ import { debounce } from '../utils/debounce.js'
  *              action result is holding priority so they can never clobber what
  *              the user actually requested.
  */
-export function createAnnouncer (mapStatusRef) {
+export function createAnnouncer (mapStatusRef, { startupGraceDelay = 1000 } = {}) {
   const CLEAR_DELAY = 100
   const DEBOUNCE_DELAY = 500
   // How long an action result keeps priority over ambient messages. Covers the
   // debounce + clear write (600ms) plus a short buffer so a hint firing right
   // after a user action can't stomp the action's message before it is read.
   const ACTION_HOLD_DELAY = 1000
+  // Invisible, unpronounced marker appended to alternate repeats of the same
+  // message. Some screen readers (VoiceOver in particular) de-dupe against the
+  // last utterance they spoke for a live region, not just the DOM's final
+  // state — so a genuine ''-then-text mutation can still be silently skipped
+  // if the text matches what was already read. Toggling this marker in keeps
+  // consecutive identical announcements from ever being byte-identical.
+  const REPEAT_MARKER = '\u200B'
+  // A screen reader may still be building its accessibility tree for a
+  // newly-loaded page — the live region's DOM node can exist and mutate
+  // correctly while the AT hasn't registered it yet, so an announcement fired
+  // this soon after boot (e.g. a consumer calling showHint() on 'app:ready')
+  // can be silently missed even though nothing here did anything wrong. Give
+  // any announcement inside this window from creation an extra head start;
+  // announcements after it behave exactly as before, with zero extra delay.
+  // Configurable (default 1000ms) so tests can set it to 0 and not have to
+  // account for it in every unrelated timing assertion.
+  const STARTUP_GRACE_DELAY = startupGraceDelay
+  const startedAt = Date.now()
 
   let actionHoldTimer = null
+  let lastAnnouncedMsg = null
+  let repeatMarkerOn = false
 
   // Core function to write to the live region
   const setLiveRegion = (msg) => {
@@ -35,14 +55,18 @@ export function createAnnouncer (mapStatusRef) {
       return
     }
 
+    const startupDelay = Math.max(0, STARTUP_GRACE_DELAY - (Date.now() - startedAt))
+
     // Clear first (for SR to re-announce)
     mapStatusRef.current.textContent = ''
     setTimeout(() => {
       if (!mapStatusRef.current) {
         return
       }
-      mapStatusRef.current.textContent = msg
-    }, CLEAR_DELAY)
+      repeatMarkerOn = msg === lastAnnouncedMsg ? !repeatMarkerOn : false
+      lastAnnouncedMsg = msg
+      mapStatusRef.current.textContent = repeatMarkerOn ? msg + REPEAT_MARKER : msg
+    }, CLEAR_DELAY + startupDelay)
   }
 
   // Debounced announcer to group rapid action events down to the latest one
@@ -76,5 +100,16 @@ export function createAnnouncer (mapStatusRef) {
     debouncedAnnounce(msg)
   }
 
+  // Blanks the live region without announcing anything. Used when a message is
+  // dismissed (e.g. a hint toast auto-dismissing) so a later identical message
+  // starts from a genuinely empty region — otherwise clear-then-set-same-text
+  // nets out to no change and some screen readers skip the re-announcement.
+  announce.clear = () => {
+    if (!mapStatusRef?.current) {
+      return
+    }
+    mapStatusRef.current.textContent = ''
+  }
+
   return announce
 }

package/src/services/announcer.test.js

@@ -8,7 +8,9 @@ describe('createAnnouncer', () => {
 
   beforeEach(() => {
     mapStatusRef = { current: { textContent: '' } }
-    announce = createAnnouncer(mapStatusRef)
+    // startupGraceDelay: 0 — these tests exercise everything except the startup
+    // grace window itself, which has its own dedicated describe block below.
+    announce = createAnnouncer(mapStatusRef, { startupGraceDelay: 0 })
   })
 
   afterEach(() => {
@@ -106,6 +108,74 @@ describe('createAnnouncer', () => {
     expect(mapStatusRef.current.textContent).toBe('Keyboard hint')
   })
 
+  it('exposes a clear() that blanks the live region without announcing', () => {
+    announce('Hint message', 'ambient')
+    jest.advanceTimersByTime(100)
+    expect(mapStatusRef.current.textContent).toBe('Hint message')
+
+    announce.clear()
+    expect(mapStatusRef.current.textContent).toBe('')
+  })
+
+  it('clear() is a no-op when mapStatusRef.current is null', () => {
+    const announceWithNull = createAnnouncer({ current: null })
+    expect(() => announceWithNull.clear()).not.toThrow()
+  })
+
+  it('a repeated identical ambient message re-announces after clear() blanks stale text', () => {
+    // First announcement: region starts empty, so clear-then-set is a real transition.
+    announce('Same message', 'ambient')
+    jest.advanceTimersByTime(100)
+    expect(mapStatusRef.current.textContent).toBe('Same message')
+
+    // Something (e.g. a hint dismissing) blanks the region before the retry, the way
+    // hints.dismiss() now does — without this, clear-then-set-same-text nets to no
+    // visible change and some screen readers skip the re-announcement.
+    announce.clear()
+    expect(mapStatusRef.current.textContent).toBe('')
+
+    announce('Same message', 'ambient')
+    jest.advanceTimersByTime(100)
+    // Repeat marker kicks in because this is a repeat of the last *spoken* message,
+    // regardless of the clear() in between — see the dedicated marker tests below.
+    expect(mapStatusRef.current.textContent).toBe('Same message' + '\u200B')
+  })
+
+  it('alternates an invisible marker on consecutive identical messages so the text is never byte-identical twice in a row', () => {
+    // VoiceOver has been observed to de-dupe against the last utterance it spoke for a
+    // live region, not just the DOM's final state — so a real ''-then-text mutation can
+    // still be silently skipped if the text matches what it already read out. Repeats
+    // must therefore differ at the string level even though they sound identical.
+    announce('Same message', 'ambient')
+    jest.advanceTimersByTime(100)
+    const first = mapStatusRef.current.textContent
+    expect(first).toBe('Same message')
+
+    announce('Same message', 'ambient')
+    jest.advanceTimersByTime(100)
+    const second = mapStatusRef.current.textContent
+    expect(second).not.toBe(first)
+    expect(second).toBe('Same message' + '\u200B')
+
+    announce('Same message', 'ambient')
+    jest.advanceTimersByTime(100)
+    const third = mapStatusRef.current.textContent
+    expect(third).not.toBe(second)
+    expect(third).toBe(first) // toggles back to the plain form
+  })
+
+  it('resets the repeat marker once a different message interrupts a run of repeats', () => {
+    announce('A', 'ambient')
+    jest.advanceTimersByTime(100)
+    announce('A', 'ambient')
+    jest.advanceTimersByTime(100)
+    expect(mapStatusRef.current.textContent).toBe('A' + '\u200B')
+
+    announce('B', 'ambient')
+    jest.advanceTimersByTime(100)
+    expect(mapStatusRef.current.textContent).toBe('B') // fresh message, no marker
+  })
+
   it('latest action wins: rapid actions announce only the most recent', () => {
     announce('First', 'action')
     jest.advanceTimersByTime(200) // still within debounce window
@@ -115,3 +185,65 @@ describe('createAnnouncer', () => {
     expect(mapStatusRef.current.textContent).toBe('Second')
   })
 })
+
+describe('createAnnouncer — startup grace delay', () => {
+  // A consumer calling showHint() the instant the app is ready (e.g. on
+  // 'app:ready') can fire before the screen reader has finished registering
+  // the live region in its own accessibility tree, even though the DOM node
+  // already exists and mutates correctly. These tests use a small explicit
+  // window (rather than the real 1000ms default) purely so assertions don't
+  // need to advance unrealistic amounts of fake time.
+  const GRACE = 300
+  let mapStatusRef
+  let announce
+
+  beforeEach(() => {
+    mapStatusRef = { current: { textContent: '' } }
+    announce = createAnnouncer(mapStatusRef, { startupGraceDelay: GRACE })
+  })
+
+  afterEach(() => {
+    jest.clearAllTimers()
+  })
+
+  it('delays an announcement fired immediately after creation by the full grace window', () => {
+    announce('Ready', 'ambient')
+    jest.advanceTimersByTime(100) // normal CLEAR_DELAY only
+    expect(mapStatusRef.current.textContent).toBe('') // still withheld
+
+    jest.advanceTimersByTime(GRACE) // the rest of the grace window
+    expect(mapStatusRef.current.textContent).toBe('Ready')
+  })
+
+  it('only waits out the remaining grace window, not the full window again', () => {
+    jest.advanceTimersByTime(200) // partway through the grace window already
+    announce('Ready', 'ambient')
+
+    // Remaining grace (100) + CLEAR_DELAY (100) = 200 total from this point
+    jest.advanceTimersByTime(199)
+    expect(mapStatusRef.current.textContent).toBe('')
+
+    jest.advanceTimersByTime(1)
+    expect(mapStatusRef.current.textContent).toBe('Ready')
+  })
+
+  it('adds no extra delay once the grace window has fully elapsed', () => {
+    jest.advanceTimersByTime(GRACE)
+    announce('Later', 'ambient')
+
+    jest.advanceTimersByTime(100) // normal CLEAR_DELAY only
+    expect(mapStatusRef.current.textContent).toBe('Later')
+  })
+
+  it('defaults to a 1000ms grace window when not configured', () => {
+    const defaultAnnounce = createAnnouncer(mapStatusRef)
+    defaultAnnounce('Ready', 'ambient')
+
+    // 1000ms grace + 100ms CLEAR_DELAY = 1100 total
+    jest.advanceTimersByTime(1099)
+    expect(mapStatusRef.current.textContent).toBe('')
+
+    jest.advanceTimersByTime(1)
+    expect(mapStatusRef.current.textContent).toBe('Ready')
+  })
+})

package/src/services/hints.js

@@ -25,6 +25,9 @@ export function createHints (announce) {
     clearTimer()
     current = null
     notify()
+    // Blank the live region so a later identical hint re-announces instead of
+    // silently netting-out against the stale text left by this dismissal.
+    announce.clear?.()
   }
 
   const show = (html, options = {}) => {

package/src/services/hints.test.js

@@ -85,6 +85,25 @@ describe('dismiss', () => {
   it('is safe to call when no hint is active', () => {
     expect(() => hints.dismiss()).not.toThrow()
   })
+
+  it('blanks the live region via announce.clear so a later identical hint re-announces', () => {
+    announce.clear = jest.fn()
+    hints.show('hello')
+    hints.dismiss()
+    expect(announce.clear).toHaveBeenCalled()
+  })
+
+  it('is safe to call when announce has no clear method', () => {
+    hints.show('hello')
+    expect(() => hints.dismiss()).not.toThrow()
+  })
+
+  it('blanks the live region on auto-dismiss too, not just explicit dismiss', () => {
+    announce.clear = jest.fn()
+    hints.show('hello', { duration: 3000 })
+    jest.advanceTimersByTime(3000)
+    expect(announce.clear).toHaveBeenCalled()
+  })
 })
 
 // ─── subscribe / unsubscribe ──────────────────────────────────────────────────

package/src/types.js

@@ -525,6 +525,18 @@
  *
  */
 
+/**
+ * Options for a toast hint shown via `showHint()`.
+ *
+ * @typedef {Object} HintOptions
+ *
+ * @property {number} [duration=4000]
+ * Auto-dismiss delay in milliseconds. Pass `0` to persist until `dismissHint()` is called.
+ *
+ * @property {string} [announce]
+ * Plain-text override for the screen-reader announcement. Defaults to `text` with any HTML tags stripped.
+ */
+
 /**
  * Defines a panel that can be rendered in the UI at various breakpoints.
  *

package/src/utils/detectInterfaceType.js

@@ -59,7 +59,11 @@ function createInterfaceDetector () {
   }
 
   const handleKeyDown = e => {
-    if (e.key === 'Tab') {
+    // Recognize keyboard mode from Tab (explicit focus), arrow keys (navigation),
+    // Enter (confirmation), or other significant keys. This allows the interface type
+    // to update even when keyboard input happens during drawing (where focus is on map).
+    const keyboardModeKeys = new Set(['Tab', 'Enter', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Escape'])
+    if (keyboardModeKeys.has(e.key)) {
       notifyListeners('keyboard')
     }
   }

package/src/utils/isMac.js

@@ -0,0 +1,15 @@
+/**
+ * Detects whether the current platform is macOS.
+ *
+ * Prefers the modern User-Agent Client Hints API and falls back to the legacy
+ * `navigator.platform`. Guarded so it is safe to call in non-browser
+ * environments (Node/SSR/tests), where it returns `false`.
+ *
+ * @returns {boolean} True when running on macOS.
+ */
+export const isMac = () => {
+  if (typeof navigator === 'undefined') {
+    return false
+  }
+  return /mac/i.test(navigator.userAgentData?.platform || navigator.platform || '')
+}

package/src/utils/isMac.test.js

@@ -0,0 +1,37 @@
+import { isMac } from './isMac.js'
+
+describe('isMac', () => {
+  const original = Object.getOwnPropertyDescriptor(global, 'navigator')
+
+  afterEach(() => {
+    if (original) {
+      Object.defineProperty(global, 'navigator', original)
+    } else {
+      delete global.navigator
+    }
+  })
+
+  const setNavigator = (value) => {
+    Object.defineProperty(global, 'navigator', { value, configurable: true, writable: true })
+  }
+
+  test('returns false when navigator is undefined', () => {
+    setNavigator(undefined)
+    expect(isMac()).toBe(false)
+  })
+
+  test('detects macOS via userAgentData.platform', () => {
+    setNavigator({ userAgentData: { platform: 'macOS' }, platform: '' })
+    expect(isMac()).toBe(true)
+  })
+
+  test('falls back to navigator.platform', () => {
+    setNavigator({ platform: 'MacIntel' })
+    expect(isMac()).toBe(true)
+  })
+
+  test('returns false on non-mac platforms', () => {
+    setNavigator({ userAgentData: { platform: 'Windows' }, platform: 'Win32' })
+    expect(isMac()).toBe(false)
+  })
+})

package/webpack.umd.mjs

@@ -146,6 +146,7 @@ const ALL_BUILDS = [
   { entryPath: './plugins/interact/src/index.js', libraryPath: 'interactPlugin', outDir: 'plugins/interact/dist/umd' },
   { entryPath: './plugins/datasets/src/index.js', libraryPath: 'datasetsPlugin', outDir: 'plugins/datasets/dist/umd', cssOutDir: 'plugins/datasets/dist' },
   { entryPath: './plugins/beta/map-styles/src/index.js', libraryPath: 'mapStylesPlugin', outDir: 'plugins/beta/map-styles/dist/umd' },
+  { entryPath: './plugins/draw/src/index.js', libraryPath: 'drawPlugin', outDir: 'plugins/draw/dist/umd' },
   { entryPath: './plugins/beta/draw-ml/src/index.js', libraryPath: 'drawMLPlugin', outDir: 'plugins/beta/draw-ml/dist/umd' },
   { entryPath: './plugins/beta/frame/src/index.js', libraryPath: 'framePlugin', outDir: 'plugins/beta/frame/dist/umd' }
 ]