@brightspot/ui 3.0.1 → 5.0.1

package/src/legacy/tool-ui/src/dom/TetherLayout.ts

@@ -0,0 +1,149 @@
+import { CSSUnit } from '../Types'
+import repaint from '../util/repaint'
+import Tether from './Tether'
+
+interface TetherCoordinates {
+  element: HTMLElement
+  x: 'l' | 'r'
+  y: 't' | 'b'
+  w: CSSUnit
+  h: CSSUnit
+  t: CSSUnit
+  l: CSSUnit
+}
+
+export default class TetherLayout {
+  #oldUpdates: WeakMap<HTMLElement, TetherCoordinates>
+  #tethers: Tether[]
+  #update: () => void
+  #updateInterval: number | null
+
+  constructor() {
+    this.#oldUpdates = new WeakMap()
+    this.#tethers = []
+    this.#updateInterval = null
+    this.#update = repaint(this.updateImmediately.bind(this))
+  }
+
+  get tethers() {
+    return this.#tethers
+  }
+
+  add(tether: Tether): void {
+    this.#tethers.push(tether)
+    this.start()
+  }
+
+  remove(tether: Tether): void {
+    const tethers = this.#tethers
+    const index = tethers.indexOf(tether)
+
+    if (index > -1) {
+      tethers.splice(index, 1)
+    }
+
+    if (tethers.length < 0) {
+      this.stop()
+    }
+  }
+
+  start(): void {
+    this.updateImmediately()
+
+    if (this.#updateInterval === null) {
+      window.addEventListener('resize', this.#update, true)
+      window.addEventListener('scroll', this.#update, true)
+      this.#updateInterval = setInterval(this.#update, 50)
+    }
+  }
+
+  stop(): void {
+    if (this.#updateInterval !== null) {
+      window.removeEventListener('resize', this.#update)
+      window.removeEventListener('scroll', this.#update)
+      clearInterval(this.#updateInterval)
+      this.#updateInterval = null
+    }
+  }
+
+  updateImmediately(): void {
+    const tethers = this.#tethers
+
+    if (tethers.length === 0) {
+      return
+    }
+
+    const updates: Array<TetherCoordinates> = []
+    const root = document.documentElement
+    let rw2 = root.clientWidth / 2
+    let rh2 = root.clientHeight / 2
+    const isRTL = root.dir === 'rtl'
+
+    for (const tether of tethers) {
+      const e = tether.element
+      const rr = tether.reference.getBoundingClientRect()
+      const w = rr.width
+      const h = rr.height
+
+      if (w === 0 && h === 0) {
+        continue
+      }
+
+      let top = rr.top
+      let left = rr.left
+      let viewportWidth = root.clientWidth
+
+      // Adjust top and left values if inside fixed-position popover.
+      if (e.parentElement?.hasAttribute('popover')) {
+        top = tether.reference.offsetTop
+        left = tether.reference.offsetLeft
+
+        const popover = e.parentElement
+        viewportWidth = popover.clientWidth
+        rw2 = viewportWidth / 2
+        rh2 = popover.clientHeight / 2
+      }
+
+      // Calculate horizontal position, accounting for RTL direction
+      let horizontalPosition: 'l' | 'r'
+      let calculatedLeft = left
+
+      if (isRTL) {
+        // In RTL, we need to mirror the positioning
+        // Convert left position to right position, then back to left for calculation
+        const rightPosition = viewportWidth - left - w
+        calculatedLeft = rightPosition
+        // Determine which side based on mirrored position
+        horizontalPosition = rightPosition < rw2 ? 'l' : 'r'
+      } else {
+        // In LTR, use normal logic: left side uses 'l', right side uses 'r'
+        horizontalPosition = left < rw2 ? 'l' : 'r'
+      }
+
+      updates.push({
+        element: e,
+        x: horizontalPosition,
+        y: top + h / 2 < rh2 ? 't' : 'b',
+        l: `${calculatedLeft}px`,
+        w: `${w}px`,
+        t: `${top}px`,
+        h: `${h}px`,
+      })
+    }
+
+    for (const update of updates) {
+      const e = update.element
+      const oldUpdate = this.#oldUpdates.get(e) || ({} as TetherCoordinates)
+      const es = e.style
+
+      if (update.x !== oldUpdate.x) e.setAttribute('data-tether-rx', update.x)
+      if (update.y !== oldUpdate.y) e.setAttribute('data-tether-ry', update.y)
+      if (update.l !== oldUpdate.l) es.setProperty('--Tether-rl', update.l)
+      if (update.w !== oldUpdate.w) es.setProperty('--Tether-rw', update.w)
+      if (update.t !== oldUpdate.t) es.setProperty('--Tether-rt', update.t)
+      if (update.h !== oldUpdate.h) es.setProperty('--Tether-rh', update.h)
+
+      this.#oldUpdates.set(e, update)
+    }
+  }
+}

package/src/legacy/tool-ui/src/dom/aria.ts

@@ -0,0 +1,123 @@
+import onFind from './onFind'
+import debounce from '../util/debounce'
+import onVisible from './onVisible'
+
+/*
+  Simple string replacement utility.
+  Find all instances of "___" in the string
+  and replace with each string in the list of data.
+  eg:
+    template = 'Today is ___ and the weather is ___.'
+    data = ['Friday', 'sunnny']
+    --------------------------
+    <- 'Today is Friday and the weather is sunny.'
+*/
+export function replaceWithEach(template: string, data: string[]) {
+  return template.replace(
+    /_{3}/g,
+    (
+      (i) => (_: string) =>
+        data[i++]
+    )(0),
+  )
+}
+
+export function announce(message: string, data?: string[]) {
+  let container = document.getElementById('aria-live-container')
+  if (!container) {
+    container = document.createElement('div')
+    container.setAttribute('id', 'aria-live-container')
+    document.body.appendChild(container)
+  }
+  const status = document.createElement('div')
+  const id = 'speak-' + Date.now()
+  status.setAttribute('id', id)
+  status.setAttribute('aria-atomic', 'true')
+  status.setAttribute('aria-live', 'polite')
+  status.classList.add('screen-reader-only')
+  if (data && data.length) {
+    message = replaceWithEach(`${message}`, data)
+  }
+  container.appendChild(status)
+
+  setTimeout(() => {
+    const liveRegion = document.getElementById(id)
+    if (liveRegion) liveRegion.innerHTML = message
+  }, 150)
+
+  if (window.BRIGHTSPOT?.ariaDebug === true) {
+    console.log(`ARIA Announced: "${message}"`)
+  }
+
+  setTimeout(() => {
+    document.getElementById(id)?.remove()
+  }, 2000)
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  document.body.addEventListener('btu-announce', (event) => {
+    if (event instanceof CustomEvent) {
+      announce(event.detail)
+    }
+  })
+})
+
+const announcements: HTMLElement[] = []
+
+onFind('[data-aria-announce]', (element: HTMLElement) => {
+  announcements.push(element)
+  setTimeout(() => {
+    if (announcements.length > 0) {
+      const message = announcements
+        .map((element) =>
+          'true' === element.dataset.ariaAnnounce
+            ? element.textContent
+            : element.dataset.ariaAnnounce,
+        )
+        .join(', ')
+      announcements.length = 0
+      announce(message)
+    }
+  }, 2500)
+})
+
+/**
+ * Buttons like "Add" or calendar are created on the frontend and bound to hidden input(s).
+ * Copy the error message 'id' attribute to set the 'aria-describedby' attribute value to
+ * the button.
+ */
+onVisible(
+  [
+    '.addButton',
+    '.Workflow-addState',
+    '.Workflow-addTransition',
+    '.calendarButton',
+    '.ComboInput',
+  ],
+  (element: HTMLElement) => {
+    const row = element.closest('.CIG-row')
+    if (!row) return
+    const message = row.querySelector('.Message.is-error')
+    if (!message) return
+    const id = message.getAttribute('id')
+    if (!id) return
+    element.setAttribute('aria-describedby', id)
+    element.setAttribute('aria-invalid', 'true')
+  },
+)
+
+/**
+ * All anchor tags acting as buttons need to respond to Enter and Space keys.
+ */
+onVisible('a[role="button"]', (element: HTMLElement) => {
+  element.addEventListener('keydown', (event) => {
+    if (event.code === 'Space') {
+      event.preventDefault()
+      element.click()
+    }
+  })
+})
+
+export const announceWithDelay = (message: string) => {
+  debounce(1000, () => announce(message))
+}

package/src/legacy/tool-ui/src/dom/closest.ts

@@ -0,0 +1,5 @@
+export default function (element: HTMLElement, selectors: string | string[]) {
+  if (!element) return null
+  if (Array.isArray(selectors)) selectors = selectors.join(',')
+  return element.closest(selectors)
+}

package/src/legacy/tool-ui/src/dom/create.ts

@@ -0,0 +1,46 @@
+type Child = Node | object | string
+
+export default function <K extends keyof HTMLElementTagNameMap>(
+  tagName: K,
+  ...children: Child[]
+): HTMLElementTagNameMap[K] {
+  const element = document.createElement(tagName)
+  const properties = children[0]
+
+  if (
+    typeof properties === 'object' &&
+    !Array.isArray(properties) &&
+    !(properties instanceof Node)
+  ) {
+    children.shift()
+
+    for (const [name, value] of Object.entries(properties)) {
+      if (name === 'dataset') {
+        Object.keys(value).forEach((dk) => (element.dataset[dk] = value[dk]))
+      } else if (typeof value === 'undefined') {
+        element.removeAttribute(name)
+      } else if (name in element) {
+        Object.assign(element, { [name]: value })
+      } else {
+        element.setAttribute(name, value)
+      }
+    }
+  }
+
+  appendChild(element, children)
+  return element
+}
+
+function appendChild(element: Element, child: Child) {
+  if (child) {
+    if (Array.isArray(child) || child instanceof NodeList) {
+      for (const c of child) {
+        appendChild(element, c)
+      }
+    } else if (child instanceof Node) {
+      element.appendChild(child)
+    } else {
+      element.appendChild(document.createTextNode(child.toString()))
+    }
+  }
+}

package/src/legacy/tool-ui/src/dom/find.ts

@@ -0,0 +1,5 @@
+export default function (element: Element, selectors: string | string[]) {
+  if (!element) return null
+  if (Array.isArray(selectors)) selectors = selectors.join(',')
+  return element.querySelector(selectors)
+}

package/src/legacy/tool-ui/src/dom/findAll.ts

@@ -0,0 +1,5 @@
+export default function (element: HTMLElement, selectors: string | string[]) {
+  if (!element) return []
+  if (Array.isArray(selectors)) selectors = selectors.join(',')
+  return element.querySelectorAll(selectors)
+}

package/src/legacy/tool-ui/src/dom/focusable.ts

@@ -0,0 +1,29 @@
+import { tabbable } from 'tabbable'
+
+export function getFocusableDescendants(
+  selector: string,
+  domElement: Element | null,
+  startIndex = 0,
+) {
+  const element = domElement
+    ? domElement.querySelector(selector)
+    : document.querySelector(selector) // changed
+  if (!element) return null
+  return getFirstAndLastFocusableDescendants(element, startIndex)
+}
+
+// A function to get the first and last tabbable elements of a container
+export function getFirstAndLastFocusableDescendants(
+  el: Element,
+  startIndex = 0,
+) {
+  const tabbableArray = tabbable(el, { includeContainer: true })
+
+  if (tabbableArray.length === 0) return null
+  const safeStartIndex = Math.min(startIndex, tabbableArray.length - 1)
+
+  return {
+    first: tabbableArray[safeStartIndex],
+    last: tabbableArray[tabbableArray.length - 1],
+  }
+}

package/src/legacy/tool-ui/src/dom/ifClick.ts

@@ -0,0 +1,18 @@
+let mousedownTarget: EventTarget | null
+
+window.addEventListener('mousedown', ({ target }) => {
+  mousedownTarget = target
+})
+
+export default function ifClick(fn: (...args: unknown[]) => unknown) {
+  return function (...args: unknown[]) {
+    if (args[0] instanceof Event || args[0] instanceof window.jQuery.Event) {
+      const event = args[0]
+      const target = (event as Event).target
+
+      if (target === mousedownTarget) {
+        fn.apply(target, args)
+      }
+    }
+  }
+}

package/src/legacy/tool-ui/src/dom/ifMatches.ts

@@ -0,0 +1,17 @@
+export default function ifMatches(
+  selectors: string | string[],
+  fn: (...args: unknown[]) => unknown,
+) {
+  const selector = Array.isArray(selectors) ? selectors.join(',') : selectors
+
+  return function (...args: unknown[]) {
+    if (args[0] instanceof Event || args[0] instanceof window.jQuery.Event) {
+      const event = args[0]
+      const target = (event as Event).target
+
+      if (target instanceof Element && target.matches(selector)) {
+        fn.apply(target, args)
+      }
+    }
+  }
+}

package/src/legacy/tool-ui/src/dom/ifUnmodified.ts

@@ -0,0 +1,16 @@
+export default function ifUnmodified(fn: (...args: unknown[]) => unknown) {
+  return function (...args: unknown[]) {
+    if (args[0] instanceof KeyboardEvent) {
+      const event = args[0]
+
+      if (
+        !event.ctrlKey &&
+        !event.shiftKey &&
+        !event.altKey &&
+        !event.metaKey
+      ) {
+        fn.apply(event.target, args)
+      }
+    }
+  }
+}

package/src/legacy/tool-ui/src/dom/insertBefore.ts

@@ -0,0 +1,4 @@
+export default function insertBefore(node: Node, reference: Node) {
+  reference?.parentNode?.insertBefore(node, reference)
+  return node
+}

package/src/legacy/tool-ui/src/dom/insertFirst.ts

@@ -0,0 +1,4 @@
+export default function insertFirst(node: Node, reference: Node) {
+  reference.insertBefore(node, reference.firstChild)
+  return node
+}

package/src/legacy/tool-ui/src/dom/insertLast.ts

@@ -0,0 +1,4 @@
+export default function insertLast(node: Node, reference: Node) {
+  reference.appendChild(node)
+  return node
+}

package/src/legacy/tool-ui/src/dom/keyboard.ts

@@ -0,0 +1,176 @@
+import { FocusableElement, tabbable } from 'tabbable'
+import { announce } from './aria'
+import { localizeShortcut } from '../platform'
+
+interface FocusableGroup {
+  first: FocusableElement
+  last: FocusableElement
+}
+
+/*
+NOTE: This function will not perform as expected with the Safari Browser. Safari by default
+does not tab to anchor and button elements. Therefore, if the item being checked is a button or anchor tag,
+it will not be triggered since Safari will not tab to that element. For this functionality to work with Safari, the following 
+must be set in the Safari settings: 'Press Tab to highlight each item on a webpage' in the 'advanced' section.
+*/
+export function trapFocusWithin(
+  e: KeyboardEvent,
+  elementGroups: FocusableGroup[],
+  cycle = true,
+) {
+  let keyType
+  if (e.key === 'Tab' && e.shiftKey) {
+    keyType = 'back'
+  } else if (e.key === 'Tab') {
+    keyType = 'forward'
+  } else {
+    return
+  }
+
+  /*
+   * NOTE: The following guard is a temporary workound for users who get stuck in a focus trap due to poor DOM
+   * ordering not playing nicely with our focus trap logic. This code will become unnecessary once we reorder
+   * key elements in the DOM to match visual/tabbing order.
+   */
+  if (!cycle) {
+    guardAgainstFocusLoop(e, elementGroups, keyType)
+  }
+
+  for (let i = 0; i < elementGroups.length; i++) {
+    const group = elementGroups[i]
+
+    if (keyType === 'forward' && e.target === group.last) {
+      const nextGroup =
+        elementGroups[i + 1] || (cycle ? elementGroups[0] : undefined)
+      if (nextGroup) {
+        e.preventDefault()
+        nextGroup.first?.focus()
+        return
+      }
+    } else if (keyType === 'back' && e.target === group.first) {
+      const prevGroup =
+        elementGroups[i - 1] ||
+        (cycle ? elementGroups[elementGroups.length - 1] : undefined)
+      if (prevGroup) {
+        e.preventDefault()
+        prevGroup.last?.focus()
+        return
+      }
+    }
+  }
+}
+
+/*
+ * Checks if one of the following conditions are met, and shows an escape hint if so:
+ * 1. User is tabbing forward from the last element of the last group, and there are elements
+ *    from earlier groups positioned after the last element in DOM order.
+ * 2. User is tabbing backward from the first element of the first group, and there are elements
+ *    from later groups positioned before the first element in DOM order.
+ */
+function guardAgainstFocusLoop(
+  e: KeyboardEvent,
+  elementGroups: FocusableGroup[],
+  keyType: string,
+) {
+  const lastGroup = elementGroups[elementGroups.length - 1]
+  const firstGroup = elementGroups[0]
+
+  if (keyType === 'forward' && e.target === lastGroup?.last) {
+    // Check if any element from an earlier group comes after the last element in DOM order
+    const lastElement = lastGroup.last
+
+    for (let i = 0; i < elementGroups.length - 1; i++) {
+      const group = elementGroups[i]
+      if (
+        comesAfter(group.first, lastElement) ||
+        comesAfter(group.last, lastElement)
+      ) {
+        showEscapeHint()
+        return
+      }
+    }
+  }
+
+  if (keyType === 'back' && e.target === firstGroup?.first) {
+    // Check if any element from a later group comes before the first element in DOM order
+    const firstElement = firstGroup.first
+
+    for (let i = 1; i < elementGroups.length; i++) {
+      const group = elementGroups[i]
+      if (
+        comesBefore(group.first, firstElement) ||
+        comesBefore(group.last, firstElement)
+      ) {
+        showEscapeHint()
+        return
+      }
+    }
+  }
+}
+
+/*
+ * Checks if an element comes after a reference element in DOM order.
+ */
+function comesAfter(element: Element, reference: Element): boolean {
+  const position = reference.compareDocumentPosition(element)
+  return Boolean(position & Node.DOCUMENT_POSITION_FOLLOWING)
+}
+
+/*
+ * Checks if an element comes before a reference element in DOM order.
+ */
+function comesBefore(element: Element, reference: Element): boolean {
+  const position = reference.compareDocumentPosition(element)
+  return Boolean(position & Node.DOCUMENT_POSITION_PRECEDING)
+}
+
+/*
+ * Shows a hint to the user about how to escape the focus trap.
+ * This hint is shown at most once every HINT_COOLDOWN milliseconds.
+ */
+let lastHintTime = 0
+const HINT_COOLDOWN = 5000
+
+function showEscapeHint() {
+  const now = Date.now()
+  if (now - lastHintTime < HINT_COOLDOWN) return
+  lastHintTime = now
+
+  const raw = window.BRIGHTSPOT?.ui.tooltips?.focusTrapHint
+  if (!raw) return
+  const message = localizeShortcut(raw)
+
+  // ARIA announcement for screen readers
+  announce(message)
+
+  // Visual popover for sighted users
+  showVisualPopover(message)
+}
+
+// A rudimentary visual popover that should be replaced later on with a list of landmark skip links.
+function showVisualPopover(message: string) {
+  const existingPopover = document.getElementById('focus-escape-hint')
+  if (existingPopover) existingPopover.remove()
+
+  const popover = document.createElement('div')
+  popover.id = 'focus-escape-hint'
+  popover.textContent = message
+  popover.setAttribute('role', 'status')
+  popover.style.position = 'fixed'
+  popover.style.bottom = '20px'
+  popover.style.right = '20px'
+  popover.style.padding = '12px 16px'
+  popover.style.backgroundColor = '#333'
+  popover.style.color = '#fff'
+  popover.style.borderRadius = '4px'
+  popover.style.fontSize = '14px'
+  popover.style.zIndex = '10000'
+  popover.style.boxShadow = '0 2px 8px rgba(0,0,0,0.3)'
+  popover.style.pointerEvents = 'none'
+
+  document.body.appendChild(popover)
+
+  setTimeout(() => {
+    popover.remove()
+  }, 4000)
+}