@leftoff/cli 0.9.7 → 0.9.8-beta.2

package/ui/tips.js

@@ -0,0 +1,117 @@
+// 0.9.8 info tips: a small ⓘ button beside a control, with the details in a
+// tooltip. Hover or keyboard focus on the ⓘ shows it (desktop); a tap pins it
+// open as a small popover (touch); a second tap, Escape or a click outside
+// closes it. The tip is a role="tooltip" the control and the ⓘ both point at
+// with aria-describedby, so screen readers get the words without opening it.
+// tipHtml() is pure (the unit tests read it); wireTips() runs once in the board.
+
+import { icon } from './icons.js'
+
+const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }
+const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ESC[c])
+
+// A DOM id from any string (an ask id can carry anything).
+export const tipId = (scope, key) => 'tip-' + String(scope || 't').replace(/[^A-Za-z0-9_-]/g, '_') + '-' + String(key || 'x').replace(/[^A-Za-z0-9_-]/g, '_')
+
+// The ⓘ button and its (hidden) tooltip. `html` is already escaped markup.
+export function tipHtml({ id, label, html }) {
+  return '<button type="button" class="tip-btn" aria-label="' + esc(label) + '" aria-expanded="false" aria-controls="' + esc(id) + '" aria-describedby="' + esc(id) + '">' + icon('info') + '</button>' +
+    '<span class="tip" role="tooltip" id="' + esc(id) + '" hidden>' + html + '</span>'
+}
+
+const OPEN_DELAY = 120
+const CLOSE_DELAY = 180
+
+export function wireTips(doc = document) {
+  const win = doc.defaultView
+  let cur = null // { btn, tip, pinned }
+  let timer = 0
+  const later = (fn, ms) => { win.clearTimeout(timer); timer = win.setTimeout(fn, ms) }
+  const tipOf = (btn) => btn && doc.getElementById(btn.getAttribute('aria-controls'))
+
+  function place(btn, tip) {
+    const r = btn.getBoundingClientRect()
+    const vh = win.innerHeight
+    // kept on screen, and inside a small popover (Quick look) when it sits in one
+    const box = btn.closest('.quicklook')
+    const b = box ? box.getBoundingClientRect() : { left: 0, right: doc.documentElement.clientWidth }
+    const lo = b.left + 8
+    const hi = b.right - 8
+    tip.style.maxWidth = Math.min(320, hi - lo) + 'px'
+    const w = tip.offsetWidth
+    const h = tip.offsetHeight
+    let left = r.right - w // right-aligned with the ⓘ
+    left = Math.max(lo, Math.min(left, hi - w))
+    let top = r.bottom + 6
+    let up = false
+    if (top + h > vh - 8 && r.top - 6 - h >= 8) { top = r.top - 6 - h; up = true }
+    tip.style.left = Math.round(left) + 'px'
+    tip.style.top = Math.round(top) + 'px'
+    tip.classList.toggle('up', up)
+  }
+
+  function show(btn, pinned) {
+    const tip = tipOf(btn)
+    if (!tip) return
+    win.clearTimeout(timer)
+    if (cur && cur.btn !== btn) hide()
+    tip.hidden = false
+    btn.setAttribute('aria-expanded', 'true')
+    place(btn, tip)
+    cur = { btn, tip, pinned: !!pinned || !!(cur && cur.btn === btn && cur.pinned) }
+  }
+  function hide() {
+    win.clearTimeout(timer)
+    if (!cur) return
+    cur.tip.hidden = true
+    if (cur.btn.isConnected) cur.btn.setAttribute('aria-expanded', 'false')
+    cur = null
+  }
+  const inside = (t) => !!(cur && t && t.closest && (cur.btn.contains(t) || cur.tip.contains(t)))
+
+  doc.addEventListener('click', (e) => {
+    if (cur && !cur.tip.isConnected) cur = null // the list was redrawn under it
+    const btn = e.target.closest && e.target.closest('.tip-btn')
+    if (btn) {
+      e.preventDefault(); e.stopPropagation()
+      if (cur && cur.btn === btn && cur.pinned) return hide()
+      return show(btn, true)
+    }
+    if (cur && !inside(e.target)) hide()
+  }, true)
+  // Mouse: hover the ⓘ (or the tip itself, so it can be read and selected)
+  doc.addEventListener('pointerover', (e) => {
+    if (e.pointerType !== 'mouse') return
+    const btn = e.target.closest && e.target.closest('.tip-btn')
+    if (btn) return (cur && cur.btn === btn) ? win.clearTimeout(timer) : later(() => show(btn, false), OPEN_DELAY)
+    if (inside(e.target)) win.clearTimeout(timer)
+  })
+  doc.addEventListener('pointerout', (e) => {
+    if (e.pointerType !== 'mouse') return
+    const from = e.target.closest && e.target.closest('.tip-btn, .tip')
+    if (!from) return
+    if (inside(e.relatedTarget)) return
+    if (!cur) return win.clearTimeout(timer)
+    if (!cur.pinned) later(hide, CLOSE_DELAY)
+  })
+  // Keyboard: focus on the ⓘ shows it, leaving it hides it (unless tapped open)
+  doc.addEventListener('focusin', (e) => {
+    const btn = e.target.closest && e.target.closest('.tip-btn')
+    if (btn && btn.matches(':focus-visible')) show(btn, false)
+  })
+  doc.addEventListener('focusout', (e) => {
+    if (cur && !cur.pinned && e.target === cur.btn && !inside(e.relatedTarget)) hide()
+  })
+  // Escape closes it first (before Quick look or a dialog hears the key)
+  doc.addEventListener('keydown', (e) => {
+    if (e.key !== 'Escape' || !cur) return
+    e.preventDefault(); e.stopImmediatePropagation()
+    const b = cur.btn
+    const back = doc.activeElement && doc.activeElement !== b && cur.tip.contains(doc.activeElement)
+    hide()
+    if (back) b.focus()
+  }, true)
+  win.addEventListener('resize', () => { if (cur) place(cur.btn, cur.tip) })
+  win.addEventListener('scroll', () => { if (cur) { if (!cur.btn.isConnected) hide(); else place(cur.btn, cur.tip) } }, true)
+  return { hide, isOpen: () => !!cur }
+}