@obvi/blueprint 1.0.9

package/dist/blueprint.js

@@ -0,0 +1,416 @@
+// Optional behavior for TOC current state and reading progress.
+export function initializeBlueprintRuntime(doc = document, win = window) {
+  const root = doc.documentElement
+  if (root.dataset.blueprintRuntime === 'ready') return
+  root.dataset.blueprintRuntime = 'ready'
+
+  wireSectionHeadingLinks(doc)
+  wireFigureDiagramSize(doc)
+
+  // The shell becomes the scroll container only while it is fixed (wide
+  // layout). At ≤700px the CSS reverts it to static and the window scrolls, so
+  // resolve the scroller live rather than caching it — a wide→narrow resize
+  // otherwise leaves the scroll listener bound to an element that no longer
+  // scrolls, silently freezing reading-progress and TOC highlighting.
+  const shell = doc.querySelector('.bp-shell')
+  const resolveScroller = () =>
+    shell && win.getComputedStyle(shell).position === 'fixed' ? shell : null
+  let shellScroller = resolveScroller()
+  const scrollTop = () => (shellScroller ? shellScroller.scrollTop : win.scrollY)
+  const scrollHeight = () =>
+    shellScroller ? shellScroller.scrollHeight : root.scrollHeight
+  const clientHeight = () =>
+    shellScroller ? shellScroller.clientHeight : win.innerHeight
+
+  const progress = doc.querySelector('.scroll-progress')
+  // Only the fixed rails track an active entry. A full-width .bp-contents
+  // index (typically parked at the top of a document) has no "current" entry,
+  // so it stays a static index and is intentionally excluded here.
+  const entries = [...doc.querySelectorAll('.bp-sidebar a[href^="#"], .bp-toc a[href^="#"], .sidebar a[href^="#"]')]
+    .map((link) => ({
+      link,
+      section: doc.getElementById(decodeURIComponent(link.hash.slice(1))),
+    }))
+    .filter(({ section }) => section)
+  // Unique target sections in DOCUMENT order — independent of the order links
+  // appear across a sidebar and one or more inline .bp-contents blocks.
+  const sections = [...new Set(entries.map(({ section }) => section))].sort((a, b) =>
+    a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
+  )
+  let scheduled = false
+  let scrollingTo = null
+
+  // Position each contents list's gliding marker + read-so-far fill to the
+  // active entry. Pure progressive enhancement: with JS off the aria-current
+  // rail still marks the active section.
+  const placeMarker = (link) => {
+    const container = link.closest('.bp-sidebar, .bp-toc, .sidebar')
+    // Top-level list is normally a direct child, but may sit inside a wrapper
+    // (e.g. a sliding panel); fall back to the first list in the container.
+    const list = container?.querySelector(':scope > ul') ?? container?.querySelector('ul')
+    if (!list) return
+    list.style.setProperty('--bp-toc-y', `${link.offsetTop}px`)
+    list.style.setProperty('--bp-toc-h', `${link.offsetHeight}px`)
+  }
+
+  // Mark every entry that points at the active section, so multiple fixed
+  // rails on a page stay in sync, each showing exactly one current link.
+  const setCurrent = (section) => {
+    for (const item of entries) {
+      if (section && item.section === section) {
+        item.link.setAttribute('aria-current', 'location')
+        placeMarker(item.link)
+      } else {
+        item.link.removeAttribute('aria-current')
+      }
+    }
+  }
+  const update = () => {
+    scheduled = false
+    if (progress) {
+      const max = scrollHeight() - clientHeight()
+      progress.style.transform = `scaleX(${max > 0 ? scrollTop() / max : 0})`
+    }
+    if (sections.length === 0) return
+    if (scrollingTo) {
+      const top = scrollingTo.getBoundingClientRect().top
+      if (top <= win.innerHeight * 0.35 && top >= -8) scrollingTo = null
+      else {
+        setCurrent(scrollingTo)
+        return
+      }
+    }
+    if (scrollTop() + clientHeight() >= scrollHeight() - 2) {
+      setCurrent(sections.at(-1))
+      return
+    }
+    const threshold = win.innerHeight * 0.35
+    setCurrent(
+      sections.reduce(
+        (current, section) => (section.getBoundingClientRect().top <= threshold ? section : current),
+        sections[0]
+      )
+    )
+  }
+  const scheduleUpdate = () => {
+    if (scheduled) return
+    scheduled = true
+    win.requestAnimationFrame(update)
+  }
+  const updateFromHash = () => {
+    const match = entries.find(({ link }) => link.hash === win.location.hash)
+    if (match) {
+      scrollingTo = match.section
+      setCurrent(match.section)
+      return
+    }
+    scrollingTo = null
+    scheduleUpdate()
+  }
+
+  const navLinkSelector =
+    '.bp-sidebar a[href^="#"], .bp-toc a[href^="#"], .sidebar a[href^="#"], .bp-contents a[href^="#"]'
+  const prefersReducedMotion = () => win.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+  const scrollToSection = (section) => {
+    scrollingTo = section
+    section.scrollIntoView({
+      behavior: prefersReducedMotion() ? 'auto' : 'smooth',
+      block: 'start',
+    })
+    const finish = () => {
+      if (scrollingTo === section) scrollingTo = null
+    }
+    if ('onscrollend' in win) {
+      const scrollTarget = shellScroller ?? win
+      scrollTarget.addEventListener('scrollend', finish, { once: true })
+    } else {
+      win.setTimeout(finish, prefersReducedMotion() ? 0 : 800)
+    }
+    scheduleUpdate()
+  }
+
+  doc.addEventListener('click', (event) => {
+    const link = event.target.closest?.(navLinkSelector)
+    if (!link?.hash) return
+    if (
+      event.defaultPrevented ||
+      event.button !== 0 ||
+      event.metaKey ||
+      event.ctrlKey ||
+      event.shiftKey ||
+      event.altKey
+    ) {
+      return
+    }
+    const section = doc.getElementById(decodeURIComponent(link.hash.slice(1)))
+    if (!section) return
+    event.preventDefault()
+    if (win.location.hash !== link.hash) win.history.pushState(null, '', link.hash)
+    if (entries.some(({ section: target }) => target === section)) setCurrent(section)
+    scrollToSection(section)
+  })
+
+  // Keep the scroll listener on whichever element currently scrolls, moving it
+  // when a resize flips the shell between fixed and static.
+  let scrollSource = shellScroller ?? win
+  scrollSource.addEventListener('scroll', scheduleUpdate, { passive: true })
+  const syncScrollSource = () => {
+    shellScroller = resolveScroller()
+    const nextSource = shellScroller ?? win
+    if (nextSource !== scrollSource) {
+      scrollSource.removeEventListener('scroll', scheduleUpdate, { passive: true })
+      nextSource.addEventListener('scroll', scheduleUpdate, { passive: true })
+      scrollSource = nextSource
+    }
+  }
+
+  win.addEventListener('hashchange', updateFromHash)
+  win.addEventListener('popstate', updateFromHash)
+  win.addEventListener('resize', () => {
+    syncScrollSource()
+    scheduleUpdate()
+  }, { passive: true })
+  updateFromHash()
+}
+
+// Section heading permalink — pixelarticons in the main-column gutter; link on
+// heading hover, copy on icon hover, check after a successful copy.
+const HEADING_LINK_ICON =
+  'M4 6h7v2H4zm0 10h7v2H4zM2 8h2v8H2zm18-2h-7v2h7zm0 10h-7v2h7zm2-8h-2v8h2zM7 11h10v2H7z'
+const HEADING_COPY_ICON =
+  'M8 6h12v2H8zM4 2h12v2H4zm2 6h2v12H6zM2 4h2v12H2zm6 16h12v2H8zM20 8h2v12h-2zm-4-4h2v2h-2zM4 16h2v2H4z'
+const HEADING_CHECK_ICON =
+  'M10 18H8v-2h2v2Zm-2-2H6v-2h2v2Zm4-2v2h-2v-2h2Zm-6 0H4v-2h2v2Zm8 0h-2v-2h2v2Zm2-2h-2v-2h2v2Zm2-2h-2V8h2v2Zm2-2h-2V6h2v2Z'
+const headingLinkTimers = new WeakMap()
+
+function createHeadingPixelIcon(doc, name, pathD) {
+  const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('width', '16')
+  svg.setAttribute('height', '16')
+  svg.setAttribute('fill', 'currentColor')
+  svg.setAttribute('aria-hidden', 'true')
+  svg.classList.add('bp-heading-link__icon', `bp-heading-link__icon--${name}`)
+  const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
+  path.setAttribute('d', pathD)
+  svg.append(path)
+  return svg
+}
+
+function createHeadingLinkButton(doc, label) {
+  const button = doc.createElement('button')
+  button.type = 'button'
+  button.className = 'bp-heading-link'
+  button.setAttribute('aria-label', `Copy link to ${label}`)
+
+  const icons = doc.createElement('span')
+  icons.className = 'bp-heading-link__icons'
+  icons.append(
+    createHeadingPixelIcon(doc, 'link', HEADING_LINK_ICON),
+    createHeadingPixelIcon(doc, 'copy', HEADING_COPY_ICON),
+    createHeadingPixelIcon(doc, 'check', HEADING_CHECK_ICON)
+  )
+  button.append(icons)
+  return button
+}
+
+async function copySectionUrl(url) {
+  if (!globalThis.isSecureContext || !navigator.clipboard?.writeText) {
+    throw new Error('The Clipboard API requires a secure context')
+  }
+  await navigator.clipboard.writeText(url)
+}
+
+function showHeadingLinkState(button, state, label) {
+  const previousTimer = headingLinkTimers.get(button)
+  if (previousTimer) clearTimeout(previousTimer)
+
+  const heading = button.closest('h2')
+
+  if (state === 'idle') {
+    delete button.dataset.bpCopyState
+    button.setAttribute('aria-label', `Copy link to ${label}`)
+    headingLinkTimers.delete(button)
+    if (heading && !heading.matches(':hover') && !heading.matches(':focus-within')) {
+      delete heading.dataset.headingLink
+    }
+    return
+  }
+
+  button.dataset.bpCopyState = state
+  button.setAttribute(
+    'aria-label',
+    state === 'copied' ? 'Link copied' : 'Copy failed'
+  )
+  if (heading) heading.dataset.headingLink = 'visible'
+
+  headingLinkTimers.set(
+    button,
+    setTimeout(() => showHeadingLinkState(button, 'idle', label), 1800)
+  )
+}
+
+function wireFigureDiagramSize(doc) {
+  for (const svg of doc.querySelectorAll('figure svg[viewBox]')) {
+    const { width } = svg.viewBox.baseVal
+    if (width > 0) svg.style.setProperty('--bp-diagram-w', `${width}px`)
+  }
+}
+
+function wireSectionHeadingLinks(doc, win = doc.defaultView) {
+  for (const section of doc.querySelectorAll('section[id]')) {
+    const heading =
+      section.querySelector(':scope > h2:first-child') ??
+      section.querySelector(':scope > hgroup:first-child > h2')
+    if (!heading || heading.querySelector(':scope > .bp-heading-row')) continue
+
+    const label = heading.textContent.trim()
+    heading.replaceChildren()
+
+    const row = doc.createElement('span')
+    row.className = 'bp-heading-row'
+
+    const button = createHeadingLinkButton(doc, label)
+
+    const title = doc.createElement('span')
+    title.className = 'bp-heading-title'
+    title.textContent = label
+
+    row.append(button, title)
+    heading.append(row)
+
+    let hideTimer = 0
+    const showLink = () => {
+      win.clearTimeout(hideTimer)
+      heading.dataset.headingLink = 'visible'
+    }
+    const scheduleHide = (event) => {
+      const next = event?.relatedTarget
+      if (next instanceof Node && heading.contains(next)) return
+      hideTimer = win.setTimeout(() => {
+        if (button.dataset.bpCopyState) return
+        if (heading.matches(':hover') || button.matches(':hover')) return
+        delete heading.dataset.headingLink
+      }, 120)
+    }
+
+    heading.addEventListener('mouseenter', showLink)
+    heading.addEventListener('mouseleave', scheduleHide)
+    button.addEventListener('mouseenter', showLink)
+    button.addEventListener('mouseleave', scheduleHide)
+    heading.addEventListener('focusin', showLink)
+    heading.addEventListener('focusout', (event) => {
+      const next = event.relatedTarget
+      if (next instanceof Node && heading.contains(next)) return
+      if (!button.dataset.bpCopyState) scheduleHide(event)
+    })
+
+    button.addEventListener('click', (event) => {
+      event.preventDefault()
+      const url = new URL(`#${section.id}`, win?.location.href ?? '').href
+      copySectionUrl(url)
+        .then(() => showHeadingLinkState(button, 'copied', label))
+        .catch(() => showHeadingLinkState(button, 'error', label))
+    })
+  }
+}
+
+// ---------------------------------------------------------------------
+// <bp-callout> — typed callout (drafting corner-tick family).
+//
+// Authoring shrinks to a single element; the component expands to the
+// .bp-callout structure (corner ticks come from blueprint.css) with the
+// matching type icon and label. Light DOM, so the stylesheet applies
+// directly and the raw .bp-callout markup stays equally valid.
+//
+//   <bp-callout type="invariant">
+//     The fence token is monotonic and never reused.
+//   </bp-callout>
+//
+// type:  locked | invariant | ref (alias: reference). Default: locked.
+// label: overrides the caption text. icon="none" drops the glyph.
+// ---------------------------------------------------------------------
+const CALLOUT_ICONS = {
+  locked:
+    'M5 8h14v2H5zm0 12h14v2H5zM3 10h2v10H3zm16 0h2v10h-2zM7 4h2v4H7zm2-2h6v2H9zm6 2h2v4h-2z',
+  invariant:
+    'M4 2h16v2H4zM2 4h2v10H2zm18 0h2v10h-2zM4 14h2v2H4zm2 2h2v2H6zm4 4h4v2h-4zm10-6h-2v2h2zm-2 2h-2v2h2zm-2 2h-2v2h2zm-6 0H8v2h2z',
+  ref:
+    'M4 2h16v2H4zm2 5h2v2H6zm4 0h8v2h-8zm-4 4h2v2H6zm4 0h8v2h-8zm-4 4h2v2H6zm4 0h8v2h-8zm-6 5h16v2H4zM2 4h2v16H2zm18 0h2v16h-2z',
+}
+const CALLOUT_TYPES = {
+  locked: { mod: 'locked', label: 'Locked', icon: 'locked' },
+  invariant: { mod: 'invariant', label: 'Invariant', icon: 'invariant' },
+  ref: { mod: 'ref', label: 'Reference', icon: 'ref' },
+  reference: { mod: 'ref', label: 'Reference', icon: 'ref' },
+}
+// Author content that already carries its own block boxes passes straight
+// through; anything else (bare text, inline runs) gets wrapped in a <p>.
+const CALLOUT_BLOCK = new Set([
+  'P', 'UL', 'OL', 'DL', 'DIV', 'PRE', 'BLOCKQUOTE', 'TABLE', 'FIGURE',
+  'SECTION', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'BP-SOURCE', 'BP-CITE',
+])
+
+function createCalloutIcon(doc, pathD) {
+  const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('fill', 'currentColor')
+  svg.setAttribute('aria-hidden', 'true')
+  const path = doc.createElementNS('http://www.w3.org/2000/svg', 'path')
+  path.setAttribute('d', pathD)
+  svg.append(path)
+  return svg
+}
+
+class BlueprintCalloutElement extends HTMLElement {
+  #rendered = false
+
+  connectedCallback() {
+    if (this.#rendered) return
+    this.#rendered = true
+
+    const doc = this.ownerDocument
+    const key = (this.getAttribute('type') || 'locked').toLowerCase()
+    const spec = CALLOUT_TYPES[key] ?? CALLOUT_TYPES.locked
+    const label = this.getAttribute('label') ?? spec.label
+
+    const aside = doc.createElement('aside')
+    aside.className = `bp-callout bp-callout--${spec.mod}`
+
+    const tag = doc.createElement('span')
+    tag.className = 'bp-ctag'
+    const iconPath = CALLOUT_ICONS[spec.icon]
+    if (iconPath && this.getAttribute('icon') !== 'none') {
+      tag.append(createCalloutIcon(doc, iconPath))
+    }
+    if (label) tag.append(doc.createTextNode(label))
+    aside.append(tag)
+
+    const body = [...this.childNodes]
+    const hasBlock = body.some(
+      (node) => node.nodeType === 1 && CALLOUT_BLOCK.has(node.tagName)
+    )
+    if (hasBlock) {
+      aside.append(...body)
+    } else {
+      const p = doc.createElement('p')
+      p.append(...body)
+      if (p.childNodes.length) aside.append(p)
+    }
+
+    this.replaceChildren(aside)
+  }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('bp-callout')) {
+  customElements.define('bp-callout', BlueprintCalloutElement)
+}
+
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => initializeBlueprintRuntime(), { once: true })
+  } else {
+    initializeBlueprintRuntime()
+  }
+}