@hadoku/task-ui-components 0.0.0-stage → 4.20.3

package/src/lib/themeScope.ts

@@ -0,0 +1,23 @@
+/**
+ * Where a popup (tooltip bubble, dropdown list) should be portalled.
+ *
+ * Theme tokens are scoped: HadokuThemeRoot puts `data-theme` on the app
+ * container, and a nested `[data-theme]` scope (a theme preview, an embedded
+ * board) can sit inside that. A popup must render inside the SAME scope as its
+ * anchor, or it paints in the wrong theme — portalled to <body>, it loses the
+ * container's tokens entirely.
+ *
+ * Rendering it in place keeps the theme but breaks on any ancestor with a
+ * `transform`, which becomes the containing block for `position: fixed` and
+ * drags the popup off its anchor. The nearest `[data-theme]` ancestor is the
+ * best of both: the right tokens, and above every transform between the
+ * anchor and the theme root. When the only match is <html>, <body> takes it —
+ * :root tokens reach body, and a portal into <html> itself would sit outside
+ * the document's body.
+ */
+export function themeScopeOf(anchor: Element | null): HTMLElement | null {
+  if (!anchor) return null
+  const scope = anchor.closest<HTMLElement>('[data-theme]')
+  if (!scope || scope === document.documentElement) return document.body
+  return scope
+}

package/src/lib/titleTooltips.ts

@@ -0,0 +1,236 @@
+/**
+ * Card tooltips for every `title=` on a page, with no change to the markup.
+ *
+ *   import { installTitleTooltips } from '@wolffm/task-ui-components/title-tooltips'
+ *   import '@wolffm/task-ui-components/tooltip.css'
+ *   installTitleTooltips()
+ *
+ * hadoku_site calls this once from its shell, which covers every
+ * micro-frontend at once; an app does not call it itself. Framework-free and
+ * React-free on purpose: the shell has no React, and this must not pull a
+ * second copy into the page.
+ *
+ * One delegated listener set on the document. On hover (mouse only — touch
+ * never showed a native title either) or keyboard focus, the nearest element
+ * carrying `title` lends it to the bubble: the attribute moves to
+ * `data-hdk-title` for as long as the bubble is up, which is what stops the
+ * browser drawing its own on top, and goes back the moment it closes. So
+ * outside a hover the DOM is exactly what the app rendered, and code or a
+ * framework that reads or re-sets `title` sees its own value. A title the
+ * app changes mid-hover (a MutationObserver watches the anchor) re-stashes and
+ * updates the open bubble.
+ *
+ * Same contract as <Tooltip>: hover or focus shows it, Escape dismisses it
+ * until the pointer leaves, the pointer can move onto the bubble, a press
+ * closes it, and the anchor gets `aria-describedby` while it is up (skipped
+ * when the title only repeats the aria-label). The bubble is portalled into
+ * the anchor's theme scope, so a nested `[data-theme]` gets its own colours.
+ *
+ * Opt out per subtree with `data-native-title`.
+ */
+
+import { themeScopeOf } from './themeScope'
+import { placeTooltip, type TooltipPlacement } from './tooltipPlacement'
+
+export interface TitleTooltipOptions {
+  /** Hover delay before showing, ms. Focus shows immediately. */
+  delay?: number
+  placement?: TooltipPlacement
+}
+
+const HIDE_GRACE_MS = 120
+const STASH = 'data-hdk-title'
+const BUBBLE_ID = 'hdk-title-tooltip'
+
+let uninstallCurrent: (() => void) | null = null
+
+export function installTitleTooltips(options: TitleTooltipOptions = {}): () => void {
+  if (uninstallCurrent) return uninstallCurrent
+  const delay = options.delay ?? 300
+  const placement = options.placement ?? 'top'
+
+  let anchor: Element | null = null
+  let bubble: HTMLDivElement | null = null
+  let timer: ReturnType<typeof setTimeout> | undefined
+  // Escape closes the bubble until the pointer leaves that anchor (WCAG 1.4.13).
+  let dismissed: Element | null = null
+
+  const observer = new MutationObserver(() => {
+    if (!anchor || !anchor.hasAttribute('title')) return
+    stash(anchor)
+    if (bubble) {
+      bubble.textContent = anchor.getAttribute(STASH)
+      place()
+    }
+  })
+
+  function stash(el: Element) {
+    el.setAttribute(STASH, el.getAttribute('title') ?? '')
+    el.removeAttribute('title')
+  }
+
+  function restore(el: Element) {
+    const text = el.getAttribute(STASH)
+    if (text === null) return
+    el.removeAttribute(STASH)
+    if (!el.hasAttribute('title')) el.setAttribute('title', text)
+  }
+
+  function titledFrom(target: EventTarget | null): Element | null {
+    if (!(target instanceof Element)) return null
+    // The stash too: while the bubble is up the anchor carries data-hdk-title,
+    // not title, and a pointerover on its own icon must still find IT rather
+    // than a titled ancestor.
+    const el = target.closest(`[title], [${STASH}]`)
+    if (!el || el.tagName === 'IFRAME' || el.closest('[data-native-title]')) return null
+    return (el.getAttribute('title') ?? el.getAttribute(STASH) ?? '').trim() ? el : null
+  }
+
+  function place() {
+    if (!anchor || !bubble) return
+    if (!anchor.isConnected) {
+      hide(0)
+      return
+    }
+    const p = placeTooltip(
+      placement,
+      anchor.getBoundingClientRect(),
+      bubble.offsetWidth,
+      bubble.offsetHeight
+    )
+    bubble.style.left = `${p.left}px`
+    bubble.style.top = `${p.top}px`
+    bubble.style.setProperty('--hdk-tooltip-arrow', `${p.arrow}px`)
+    bubble.className = `hdk-tooltip hdk-tooltip--card hdk-tooltip--plain hdk-tooltip--${p.side} hdk-tooltip--visible`
+  }
+
+  /** Take the title off `el` now (before the browser's own ~1s delay runs
+   *  out) and open the bubble after `after` ms. */
+  function arm(el: Element, after: number) {
+    clearTimeout(timer)
+    if (el !== anchor) {
+      release()
+      anchor = el
+      stash(el)
+      observer.observe(el, { attributes: true, attributeFilter: ['title'] })
+    }
+    if (dismissed === el) return
+    timer = setTimeout(open, after)
+  }
+
+  function open() {
+    if (!anchor) return
+    const scope = themeScopeOf(anchor)
+    if (!scope) return
+    if (!bubble) {
+      bubble = document.createElement('div')
+      bubble.id = BUBBLE_ID
+      bubble.setAttribute('role', 'tooltip')
+      bubble.addEventListener('pointerenter', () => clearTimeout(timer))
+      bubble.addEventListener('pointerleave', () => hide(HIDE_GRACE_MS))
+    }
+    const text = anchor.getAttribute(STASH) ?? ''
+    bubble.textContent = text
+    // Parked invisibly at the origin so it can be measured, then placed.
+    bubble.className = `hdk-tooltip hdk-tooltip--card hdk-tooltip--plain hdk-tooltip--${placement}`
+    bubble.style.left = '0px'
+    bubble.style.top = '0px'
+    if (bubble.parentNode !== scope) scope.appendChild(bubble)
+    if (text !== anchor.getAttribute('aria-label')) {
+      const ids = (anchor.getAttribute('aria-describedby') ?? '').split(/\s+/).filter(Boolean)
+      if (!ids.includes(BUBBLE_ID))
+        anchor.setAttribute('aria-describedby', [...ids, BUBBLE_ID].join(' '))
+    }
+    place()
+    window.addEventListener('scroll', place, true)
+    window.addEventListener('resize', place)
+  }
+
+  /** Close the bubble and hand the anchor its title back. */
+  function release() {
+    window.removeEventListener('scroll', place, true)
+    window.removeEventListener('resize', place)
+    bubble?.remove()
+    if (!anchor) return
+    observer.disconnect()
+    const ids = (anchor.getAttribute('aria-describedby') ?? '')
+      .split(/\s+/)
+      .filter(id => id && id !== BUBBLE_ID)
+    if (ids.length) anchor.setAttribute('aria-describedby', ids.join(' '))
+    else anchor.removeAttribute('aria-describedby')
+    restore(anchor)
+    anchor = null
+  }
+
+  function hide(after: number) {
+    clearTimeout(timer)
+    if (after === 0) release()
+    else timer = setTimeout(release, after)
+  }
+
+  const onPointerOver = (e: PointerEvent) => {
+    if (e.pointerType !== 'mouse') return
+    if (bubble && bubble.contains(e.target as Node)) return
+    // Back over the anchor of a bubble still up: just cancel the pending hide.
+    // Over it with no bubble (inside the hide grace, or after a dismissal
+    // that has since cleared), arm it again — otherwise it stays silent.
+    const el = titledFrom(e.target)
+    if (el && el === anchor && bubble?.isConnected) clearTimeout(timer)
+    else if (el) arm(el, delay)
+  }
+
+  const onPointerOut = (e: PointerEvent) => {
+    if (e.pointerType !== 'mouse') return
+    const to = e.relatedTarget as Node | null
+    // Checked before `anchor`: a dismissal has already released the anchor.
+    if (dismissed && !(to && dismissed.contains(to))) dismissed = null
+    if (!anchor || (to && (anchor.contains(to) || bubble?.contains(to)))) return
+    hide(HIDE_GRACE_MS)
+  }
+
+  // A press closes it, as it does a native title: the click usually opens
+  // something the bubble would sit on top of.
+  const onPointerDown = () => {
+    if (anchor) dismissed = anchor
+    hide(0)
+  }
+
+  const onFocusIn = (e: FocusEvent) => {
+    const target = e.target
+    if (!(target instanceof Element) || !target.matches(':focus-visible')) return
+    const el = titledFrom(target)
+    if (el) {
+      dismissed = null
+      arm(el, 0)
+    }
+  }
+
+  const onFocusOut = (e: FocusEvent) => {
+    if (anchor && anchor.contains(e.target as Node)) hide(0)
+  }
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key !== 'Escape' || !anchor || !bubble?.isConnected) return
+    dismissed = anchor
+    hide(0)
+  }
+
+  document.addEventListener('pointerover', onPointerOver)
+  document.addEventListener('pointerout', onPointerOut)
+  document.addEventListener('pointerdown', onPointerDown, true)
+  document.addEventListener('focusin', onFocusIn)
+  document.addEventListener('focusout', onFocusOut)
+  document.addEventListener('keydown', onKeyDown)
+
+  uninstallCurrent = () => {
+    hide(0)
+    document.removeEventListener('pointerover', onPointerOver)
+    document.removeEventListener('pointerout', onPointerOut)
+    document.removeEventListener('pointerdown', onPointerDown, true)
+    document.removeEventListener('focusin', onFocusIn)
+    document.removeEventListener('focusout', onFocusOut)
+    document.removeEventListener('keydown', onKeyDown)
+    uninstallCurrent = null
+  }
+  return uninstallCurrent
+}

package/src/lib/tooltipPlacement.ts

@@ -0,0 +1,59 @@
+/**
+ * Where a tooltip bubble goes, shared by <Tooltip> and installTitleTooltips so
+ * the React and framework-free bubbles sit, flip and clamp identically.
+ */
+
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right'
+
+export interface Placed {
+  side: TooltipPlacement
+  left: number
+  top: number
+  /** Arrow offset along the bubble edge, so it still points at the anchor after clamping. */
+  arrow: number
+}
+
+const GAP = 8
+const EDGE = 8
+
+const OPPOSITE: Record<TooltipPlacement, TooltipPlacement> = {
+  top: 'bottom',
+  bottom: 'top',
+  left: 'right',
+  right: 'left'
+}
+
+function fits(side: TooltipPlacement, a: DOMRect, w: number, h: number) {
+  if (side === 'top') return a.top - GAP - h >= EDGE
+  if (side === 'bottom') return a.bottom + GAP + h <= window.innerHeight - EDGE
+  if (side === 'left') return a.left - GAP - w >= EDGE
+  return a.right + GAP + w <= window.innerWidth - EDGE
+}
+
+/** Onto the device-pixel grid. A bubble at a fractional offset draws its 1px
+ *  border antialiased across two rows of the screen — a blurred edge. */
+function snap(v: number) {
+  const dpr = window.devicePixelRatio || 1
+  return Math.round(v * dpr) / dpr
+}
+
+export function placeTooltip(
+  preferred: TooltipPlacement,
+  a: DOMRect,
+  w: number,
+  h: number
+): Placed {
+  const side =
+    fits(preferred, a, w, h) || !fits(OPPOSITE[preferred], a, w, h)
+      ? preferred
+      : OPPOSITE[preferred]
+  const clamp = (v: number, max: number) => Math.min(Math.max(v, EDGE), max - EDGE)
+  if (side === 'top' || side === 'bottom') {
+    const left = snap(clamp(a.left + a.width / 2 - w / 2, window.innerWidth - w))
+    const top = snap(side === 'top' ? a.top - GAP - h : a.bottom + GAP)
+    return { side, left, top, arrow: a.left + a.width / 2 - left }
+  }
+  const top = snap(clamp(a.top + a.height / 2 - h / 2, window.innerHeight - h))
+  const left = snap(side === 'left' ? a.left - GAP - w : a.right + GAP)
+  return { side, left, top, arrow: a.top + a.height / 2 - top }
+}

package/src/modal.css

@@ -0,0 +1,129 @@
+/* Modal styles for @wolffm/task-ui-components.
+ *
+ * The component shipped without these, which is why it had one adopter: every
+ * other app hand-rolled a dialog rather than reproduce the stylesheet. Import
+ * alongside the other component CSS:
+ *   import '@wolffm/task-ui-components/modal.css'
+ *
+ * Tokens only, so it themes with everything else across all 18 themes.
+ */
+
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background-color: var(--color-bg-overlay);
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: 8vh 16px;
+  z-index: 50;
+}
+
+.modal-card {
+  background-color: var(--color-bg-card);
+  color: var(--color-text);
+  border: 1px solid var(--color-border);
+  border-radius: var(--hdk-radius-lg);
+  padding: 20px;
+  width: min(440px, 92vw);
+  max-height: 84vh;
+  overflow: auto;
+  box-shadow: var(--hdk-shadow-lg);
+}
+
+/* The card takes focus on open so Escape works before anything inside is
+ * focused; it must not draw a focus ring for that. Controls keep theirs. */
+.modal-card:focus {
+  outline: none;
+}
+
+/* A dialog that needs room — a review step, a side-by-side. */
+.modal-card--wide {
+  width: min(680px, 94vw);
+}
+
+.modal-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin: 0 0 14px;
+}
+
+.modal-card h3 {
+  margin: 0;
+  font-size: var(--hdk-text-lg);
+  font-weight: 600;
+}
+
+.modal-card label {
+  display: block;
+  color: var(--color-text-secondary);
+  font-size: var(--hdk-text-sm);
+  margin: 12px 0 5px;
+}
+
+.modal-input {
+  width: 100%;
+  font: inherit;
+  font-size: var(--hdk-text-sm);
+  color: var(--color-text);
+  background-color: var(--color-bg-alt);
+  border: 1px solid var(--color-border);
+  border-radius: var(--hdk-radius);
+  padding: 9px 11px;
+}
+
+.modal-input:focus {
+  outline: none;
+  border-color: var(--color-primary);
+}
+
+.modal-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--hdk-space-sm);
+  margin-top: 18px;
+}
+
+.modal-button {
+  font: inherit;
+  font-size: var(--hdk-text-sm);
+  padding: 8px 14px;
+  border-radius: var(--hdk-radius);
+  border: 1px solid var(--color-border);
+  background: none;
+  color: var(--color-text);
+  cursor: pointer;
+}
+
+.modal-button:hover:not(:disabled) {
+  border-color: var(--color-primary);
+}
+
+.modal-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.modal-button--primary {
+  background-color: var(--color-primary);
+  border-color: var(--color-primary);
+  color: var(--color-on-primary);
+}
+
+/* The destructive button carries its accent on the border, not the label.
+ * `--color-danger` as bare text on the card misses AA in 11 of 18 themes —
+ * the same unvalidated accent-over-surface pair that check-usage now gates. */
+.modal-button--danger {
+  border-color: var(--color-danger);
+  color: var(--color-text);
+}
+
+/* Filled on hover, so the label takes `on-danger` — NOT `on-primary`, which is
+ * derived from primary's luminance and misses AA on a danger fill in 9 of 18
+ * themes. `on-danger` over `danger` is the pair check-contrast guarantees. */
+.modal-button--danger:hover:not(:disabled) {
+  background-color: var(--color-danger);
+  border-color: var(--color-danger);
+  color: var(--color-on-danger);
+}

package/src/number-input.css

@@ -0,0 +1,131 @@
+/* NumberInput styles for @wolffm/task-ui-components.
+ *
+ *   import '@wolffm/task-ui-components/number-input.css'
+ *
+ * One bordered box holding the field and a stacked up/down stepper, so the
+ * focus ring and the border belong to the whole control, as on <Select>.
+ */
+
+.hdk-number {
+  display: inline-flex;
+  align-items: stretch;
+  min-width: 0;
+  vertical-align: middle;
+  color: var(--color-text);
+  background-color: var(--color-bg-card);
+  border: 1px solid var(--color-border);
+  border-radius: var(--hdk-radius);
+  overflow: hidden;
+  transition:
+    border-color var(--transition-fast),
+    box-shadow var(--transition-fast);
+}
+
+.hdk-number:hover:not(.hdk-number--disabled) {
+  border-color: var(--color-text-muted);
+}
+
+.hdk-number:focus-within {
+  border-color: var(--color-primary);
+  box-shadow: var(--hdk-shadow-focus-sm);
+}
+
+.hdk-number--disabled {
+  opacity: 0.5;
+}
+
+.hdk-number__input {
+  flex: 1;
+  width: 100%;
+  min-width: 0;
+  font: inherit;
+  color: inherit;
+  background: transparent;
+  border: 0;
+  appearance: textfield;
+}
+
+.hdk-number__input:focus {
+  outline: none;
+}
+
+.hdk-number__input::-webkit-inner-spin-button,
+.hdk-number__input::-webkit-outer-spin-button {
+  appearance: none;
+  margin: 0;
+}
+
+.hdk-number__steps {
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  border-left: 1px solid var(--color-border);
+}
+
+.hdk-number__step {
+  display: flex;
+  flex: 1;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  color: var(--color-text-secondary);
+  background: transparent;
+  border: 0;
+  cursor: pointer;
+  transition:
+    background-color var(--transition-fast),
+    color var(--transition-fast);
+}
+
+.hdk-number__step + .hdk-number__step {
+  border-top: 1px solid var(--color-border);
+}
+
+.hdk-number__step:hover:not(:disabled) {
+  color: var(--color-on-primary-bg);
+  background-color: var(--color-primary-bg);
+}
+
+.hdk-number__step:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.hdk-number--sm {
+  font-size: var(--hdk-text-xs);
+  min-height: 28px;
+}
+
+.hdk-number--sm .hdk-number__input {
+  padding: 4px 8px;
+}
+
+.hdk-number--sm .hdk-number__step {
+  width: 18px;
+}
+
+.hdk-number--md {
+  font-size: var(--hdk-text-sm);
+  min-height: 34px;
+}
+
+.hdk-number--md .hdk-number__input {
+  padding: 7px 10px;
+}
+
+.hdk-number--md .hdk-number__step {
+  width: 22px;
+}
+
+.hdk-number--lg {
+  font-size: var(--hdk-text-base);
+  min-height: 42px;
+}
+
+.hdk-number--lg .hdk-number__input {
+  padding: 10px 12px;
+}
+
+.hdk-number--lg .hdk-number__step {
+  width: 26px;
+}