@obvi/blueprint 1.2.0 → 1.3.1

package/README.md

@@ -16,6 +16,27 @@ A blueprint is a technical document that should look like one: monochrome ink on
 
 The result is one portable stylesheet, no build step, that turns plain semantic markup into a polished blueprint.
 
+## Host decision integration
+
+`<bp-choice>` keeps its author-facing HTML contract while exposing a semantic
+runtime boundary for Obvious. A connected choice emits `bp-choice-ready` with
+its stable manifest. Committing and reconsidering emit the bubbling, composed
+`bp-choice-commit` and `bp-choice-reconsider` events. Tab preview emits nothing.
+
+Hosts apply ephemeral owner state through `choice.applyDecisionState(state)`:
+
+```js
+choice.applyDecisionState({ status: 'locked', value: 'phased', busy: false })
+choice.applyDecisionState({ status: 'open', value: 'phased', busy: false })
+choice.applyDecisionState(null) // restore the authored open/resolved state
+```
+
+The component retains its authored option model and owns every rerender. Hosts
+must use the manifest, events, and method instead of querying generated
+`.bp-choice__*` markup. Applying host state never mutates the authored
+`resolved` attribute, so a host can present an owner-only reconsideration while
+the stored document remains at its last committed decision.
+
 ## Learn more
 
 Blueprints are created and rendered through Obvious. To see what they are and how to use them, go to **[obvious.ai](https://obvious.ai)**.

package/dist/blueprint-choices.js

@@ -37,7 +37,7 @@ function extractRationale(root) {
   if (!node) return null
   const wrap = node.ownerDocument.createElement('div')
   wrap.className = 'bp-choice-rationale'
-  wrap.append(...node.childNodes)
+  wrap.append(...[...node.childNodes].map((child) => child.cloneNode(true)))
   return wrap
 }
 
@@ -201,6 +201,239 @@ function buildResolvedChoice(doc, { options, verdictKicker, resolvedValue }) {
   return root
 }
 
+/** @param {HTMLElement} host @param {ChoiceLayout} layout @param {ReturnType<typeof readOptions>} options @param {string | null} resolvedValue */
+function buildChoiceManifest(host, layout, options, resolvedValue) {
+  return {
+    id: host.id || host.getAttribute('name') || '',
+    label:
+      host.getAttribute('data-obvious-choice-label') ||
+      host.getAttribute('aria-label') ||
+      host.getAttribute('name') ||
+      host.id ||
+      '',
+    layout,
+    resolvedValue,
+    options: options.map((option) => ({
+      value: option.value,
+      label: option.title || option.tab || option.value,
+      title: option.title,
+    })),
+  }
+}
+
+/**
+ * @param {HTMLElement} host
+ * @param {'bp-choice-ready' | 'bp-choice-commit' | 'bp-choice-reconsider'} type
+ * @param {Record<string, unknown>} detail
+ */
+function dispatchChoiceEvent(host, type, detail) {
+  host.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: true, detail }))
+}
+
+/** @param {HTMLElement} root @param {boolean} disabled */
+function setChoiceControlsDisabled(root, disabled) {
+  for (const control of root.querySelectorAll('input, button')) {
+    if (control instanceof HTMLInputElement || control instanceof HTMLButtonElement) {
+      control.disabled = disabled
+    }
+  }
+}
+
+/**
+ * @param {Document} doc
+ * @param {HTMLElement} root
+ * @param {{ message: string, reconsider: string, busy: boolean }} state
+ */
+function appendLockedHostActions(doc, root, state) {
+  const actions = el(doc, 'div', 'bp-choice__actions')
+  const status = el(doc, 'output', 'bp-choice__hint')
+  status.setAttribute('aria-live', 'polite')
+  status.textContent = state.message
+  const reset = el(doc, 'button', 'bp-choice__reset')
+  reset.type = 'button'
+  reset.disabled = state.busy
+  reset.textContent = state.busy ? 'Saving…' : state.reconsider
+  actions.append(status, reset)
+  root.append(actions)
+  return reset
+}
+
+/**
+ * @param {Document} doc
+ * @param {{
+ *   layout: ChoiceLayout,
+ *   options: ReturnType<typeof readOptions>,
+ *   verdictKicker: string,
+ *   adoptLabel: string,
+ *   hint: string,
+ *   reconsider: string,
+ *   compareSummary: string | null,
+ *   compareBody: Element | null,
+ *   scopeId: string,
+ *   initialValue: string | null,
+ *   busy: boolean,
+ *   message: string,
+ * }} source
+ */
+function buildInteractiveChoice(doc, source) {
+  const {
+    layout,
+    options,
+    verdictKicker,
+    adoptLabel,
+    hint,
+    reconsider,
+    compareSummary,
+    compareBody,
+    scopeId,
+    initialValue,
+    busy,
+    message,
+  } = source
+  const viewName = `${scopeId}-view`
+  const pickName = `${scopeId}-pick`
+  const form = el(doc, 'form', `bp-choice bp-choice--${layout}`)
+  form.dataset.bpChoice = scopeId
+  const titleOpts = options.map((option) => ({ value: option.value, title: option.title }))
+  form.append(buildVerdict(doc, verdictKicker, titleOpts))
+
+  if (layout === 'tabs') {
+    const selectedView = options.some((option) => option.value === initialValue) ? initialValue : options[0]?.value
+    const seg = el(doc, 'div', 'bp-choice__seg')
+    seg.setAttribute('role', 'tablist')
+    for (const opt of options) {
+      const segOpt = el(doc, 'label', 'bp-choice__seg-opt')
+      const input = doc.createElement('input')
+      input.type = 'radio'
+      input.name = viewName
+      input.value = opt.value
+      input.className = 'bp-choice__view'
+      if (opt.value === selectedView) {
+        input.defaultChecked = true
+        input.checked = true
+      }
+      segOpt.append(input, doc.createTextNode(opt.tab))
+      seg.append(segOpt)
+    }
+    form.append(seg)
+
+    const panels = el(doc, 'div', 'bp-choice__panels')
+    for (const opt of options) {
+      const panel = el(doc, 'div', 'bp-choice__panel')
+      panel.dataset.value = opt.value
+      const h3 = el(doc, 'h3')
+      h3.textContent = opt.title
+      panel.append(h3)
+      panel.append(bodyWithoutRationale(opt.el))
+      const rationale = extractRationale(opt.el)
+      if (rationale) panel.append(rationale)
+
+      const actions = el(doc, 'div', 'bp-choice__actions')
+      const adopt = el(doc, 'label', 'bp-choice__adopt')
+      const commit = doc.createElement('input')
+      commit.type = 'radio'
+      commit.name = pickName
+      commit.value = opt.value
+      commit.className = 'bp-choice__commit'
+      adopt.append(commit, doc.createTextNode(adoptLabel))
+      actions.append(adopt)
+      panel.append(actions)
+      panels.append(panel)
+    }
+    form.append(panels)
+
+    const style = el(doc, 'style')
+    style.textContent = scopedTabRules(`[data-bp-choice="${scopeId}"]`, viewName, pickName, titleOpts)
+    form.prepend(style)
+    form.append(buildFooter(doc, hint || 'Switch tabs to preview · adopt to commit', reconsider))
+  }
+
+  if (layout === 'stack') {
+    const stack = el(doc, 'div', 'bp-choice__stack')
+    for (const opt of options) {
+      const card = el(doc, 'label', 'bp-choice__card')
+      const input = doc.createElement('input')
+      input.type = 'radio'
+      input.name = pickName
+      input.value = opt.value
+      input.className = 'bp-choice__pick'
+      card.append(input)
+
+      const head = el(doc, 'div', 'bp-choice__card-head')
+      if (opt.optionLabel) head.append(label(doc, opt.optionLabel))
+      const chosen = el(doc, 'span', 'bp-choice__tag bp-choice__tag--ink bp-choice__card-chosen')
+      chosen.textContent = '✓ Chosen'
+      const rejected = el(doc, 'span', 'bp-choice__tag bp-choice__tag--out bp-choice__card-rejected')
+      rejected.textContent = 'Not chosen'
+      head.append(chosen, rejected)
+      card.append(head)
+
+      const h4 = el(doc, 'h4')
+      h4.textContent = opt.title
+      card.append(h4)
+      card.append(bodyWithoutRationale(opt.el))
+      const rationale = extractRationale(opt.el)
+      if (rationale) card.append(rationale)
+      stack.append(card)
+    }
+    form.append(stack)
+    form.append(buildFooter(doc, hint || 'Select a card to commit · rejected drafts stay readable below', reconsider))
+  }
+
+  if (layout === 'gallery') {
+    const gallery = el(doc, 'div', 'bp-choice__gallery')
+    for (const opt of options) {
+      const mock = el(doc, 'label', 'bp-choice__mock')
+      const input = doc.createElement('input')
+      input.type = 'radio'
+      input.name = pickName
+      input.value = opt.value
+      input.className = 'bp-choice__pick'
+      mock.append(input)
+
+      const frame = el(doc, 'div', 'bp-choice__mock-frame')
+      const frameInner = frameContent(opt.el)
+      if (frameInner) frame.append(frameInner)
+      mock.append(frame)
+
+      const cap = el(doc, 'div', 'bp-choice__mock-cap')
+      const h4 = el(doc, 'h4')
+      h4.textContent = opt.caption
+      cap.append(h4)
+      const chosen = el(doc, 'span', 'bp-choice__tag bp-choice__tag--ink bp-choice__mock-pick bp-choice__mock-chosen')
+      chosen.textContent = '✓ Chosen'
+      const rejected = el(doc, 'span', 'bp-choice__tag bp-choice__tag--out bp-choice__mock-pick bp-choice__mock-rejected')
+      rejected.textContent = 'Not chosen'
+      cap.append(chosen, rejected)
+      mock.append(cap)
+      gallery.append(mock)
+    }
+    form.append(gallery)
+
+    if (compareSummary && compareBody) {
+      const details = el(doc, 'details', 'bp-choice__compare')
+      const summary = el(doc, 'summary')
+      summary.textContent = compareSummary
+      details.append(summary)
+      const body = el(doc, 'div', 'bp-choice__compare-body')
+      body.append(compareBody.cloneNode(true))
+      details.append(body)
+      form.append(details)
+    }
+
+    form.append(buildFooter(doc, hint || 'Select a mockup to track the decision', reconsider))
+  }
+
+  if (message) {
+    const status = el(doc, 'output', 'bp-choice__hint')
+    status.setAttribute('aria-live', 'polite')
+    status.textContent = message
+    form.append(status)
+  }
+  setChoiceControlsDisabled(form, busy)
+  return form
+}
+
 class BlueprintRationaleElement extends HTMLElement {
   connectedCallback() {
     if (this.dataset.bpRendered) return
@@ -212,180 +445,113 @@ class BlueprintRationaleElement extends HTMLElement {
 class BlueprintChoiceOptionElement extends HTMLElement {}
 
 class BlueprintChoiceElement extends HTMLElement {
+  constructor() {
+    super()
+    this.choiceSource = null
+    this.choiceHostState = null
+    this.choiceScopeId = null
+  }
+
   connectedCallback() {
-    if (this.dataset.bpRendered) return
+    if (this.choiceSource) return
     this.dataset.bpRendered = '1'
-
-    const doc = this.ownerDocument
     /** @type {ChoiceLayout} */
     const layout = (this.getAttribute('layout') || 'stack').toLowerCase()
-    const verdictKicker = this.getAttribute('verdict') ?? 'Chosen'
-    const adoptLabel = this.getAttribute('adopt') ?? 'Adopt this direction'
-    const hint = this.getAttribute('hint') ?? ''
-    const reconsider = this.getAttribute('reconsider') ?? 'Reconsider'
-    const compareSummary = this.getAttribute('compare')
-    const compareBody = this.querySelector(':scope > [slot="compare"]')
-
-    const options = readOptions(this)
-
-    // resolved: render the decision as already made (no interaction).
-    const resolvedValue = this.getAttribute('resolved')
-    if (resolvedValue !== null) {
-      this.replaceChildren(buildResolvedChoice(doc, { options, verdictKicker, resolvedValue }))
-      return
+    this.choiceSource = {
+      layout,
+      options: readOptions(this),
+      verdictKicker: this.getAttribute('verdict') ?? 'Chosen',
+      adoptLabel: this.getAttribute('adopt') ?? 'Adopt this direction',
+      hint: this.getAttribute('hint') ?? '',
+      reconsider: this.getAttribute('reconsider') ?? 'Reconsider',
+      compareSummary: this.getAttribute('compare'),
+      compareBody: this.querySelector(':scope > [slot="compare"]'),
+      resolvedValue: this.getAttribute('resolved'),
     }
+    this.choiceScopeId = nextId('bp-choice')
+    this.renderChoice()
+    dispatchChoiceEvent(this, 'bp-choice-ready', this.getDecisionManifest())
+  }
 
-    const scopeId = nextId('bp-choice')
-    const viewName = `${scopeId}-view`
-    const pickName = `${scopeId}-pick`
-
-    const form = el(doc, 'form', `bp-choice bp-choice--${layout}`)
-    form.dataset.bpChoice = scopeId
-
-    const titleOpts = options.map((o) => ({ value: o.value, title: o.title }))
-    form.append(buildVerdict(doc, verdictKicker, titleOpts))
-
-    if (layout === 'tabs') {
-      const seg = el(doc, 'div', 'bp-choice__seg')
-      seg.setAttribute('role', 'tablist')
-      for (const [index, opt] of options.entries()) {
-        const segOpt = el(doc, 'label', 'bp-choice__seg-opt')
-        const input = doc.createElement('input')
-        input.type = 'radio'
-        input.name = viewName
-        input.value = opt.value
-        input.className = 'bp-choice__view'
-        if (index === 0) {
-          input.defaultChecked = true
-          input.checked = true
-        }
-        segOpt.append(input, doc.createTextNode(opt.tab))
-        seg.append(segOpt)
-      }
-      form.append(seg)
-
-      const panels = el(doc, 'div', 'bp-choice__panels')
-      for (const opt of options) {
-        const panel = el(doc, 'div', 'bp-choice__panel')
-        panel.dataset.value = opt.value
-        const h3 = el(doc, 'h3')
-        h3.textContent = opt.title
-        panel.append(h3)
-        panel.append(bodyWithoutRationale(opt.el))
-        const rationale = extractRationale(opt.el)
-        if (rationale) panel.append(rationale)
-
-        const actions = el(doc, 'div', 'bp-choice__actions')
-        const adopt = el(doc, 'label', 'bp-choice__adopt')
-        const commit = doc.createElement('input')
-        commit.type = 'radio'
-        commit.name = pickName
-        commit.value = opt.value
-        commit.className = 'bp-choice__commit'
-        adopt.append(commit, doc.createTextNode(adoptLabel))
-        actions.append(adopt)
-        panel.append(actions)
-        panels.append(panel)
-      }
-      form.append(panels)
-
-      const style = el(doc, 'style')
-      style.textContent = scopedTabRules(`[data-bp-choice="${scopeId}"]`, viewName, pickName, titleOpts)
-      form.prepend(style)
-
-      form.append(
-        buildFooter(
-          doc,
-          hint || 'Switch tabs to preview · adopt to commit',
-          reconsider
-        )
-      )
-    }
+  getDecisionManifest() {
+    if (!this.choiceSource) return null
+    return buildChoiceManifest(
+      this,
+      this.choiceSource.layout,
+      this.choiceSource.options,
+      this.choiceSource.resolvedValue
+    )
+  }
 
-    if (layout === 'stack') {
-      const stack = el(doc, 'div', 'bp-choice__stack')
-      for (const opt of options) {
-        const card = el(doc, 'label', 'bp-choice__card')
-        const input = doc.createElement('input')
-        input.type = 'radio'
-        input.name = pickName
-        input.value = opt.value
-        input.className = 'bp-choice__pick'
-        card.append(input)
-
-        const head = el(doc, 'div', 'bp-choice__card-head')
-        if (opt.optionLabel) head.append(label(doc, opt.optionLabel))
-        const chosen = el(doc, 'span', 'bp-choice__tag bp-choice__tag--ink bp-choice__card-chosen')
-        chosen.textContent = '✓ Chosen'
-        const rejected = el(doc, 'span', 'bp-choice__tag bp-choice__tag--out bp-choice__card-rejected')
-        rejected.textContent = 'Not chosen'
-        head.append(chosen, rejected)
-        card.append(head)
-
-        const h4 = el(doc, 'h4')
-        h4.textContent = opt.title
-        card.append(h4)
-        card.append(bodyWithoutRationale(opt.el))
-        const rationale = extractRationale(opt.el)
-        if (rationale) card.append(rationale)
-        stack.append(card)
-      }
-      form.append(stack)
-      form.append(
-        buildFooter(
-          doc,
-          hint || 'Select a card to commit · rejected drafts stay readable below',
-          reconsider
-        )
-      )
+  /**
+   * Apply ephemeral host-owned state without mutating authored attributes.
+   * Passing null restores the authored open/resolved rendering.
+   *
+   * @param {{ status: 'open' | 'locked', value: string | null, busy?: boolean, message?: string } | null} state
+   */
+  applyDecisionState(state) {
+    if (!this.choiceSource) return false
+    if (state !== null) {
+      const valueExists =
+        state.value === null || this.choiceSource.options.some((option) => option.value === state.value)
+      if ((state.status !== 'open' && state.status !== 'locked') || !valueExists) return false
+      if (state.status === 'locked' && state.value === null) return false
     }
+    this.choiceHostState = state
+      ? { status: state.status, value: state.value, busy: Boolean(state.busy), message: state.message ?? '' }
+      : null
+    this.renderChoice()
+    return true
+  }
 
-    if (layout === 'gallery') {
-      const gallery = el(doc, 'div', 'bp-choice__gallery')
-      for (const opt of options) {
-        const mock = el(doc, 'label', 'bp-choice__mock')
-        const input = doc.createElement('input')
-        input.type = 'radio'
-        input.name = pickName
-        input.value = opt.value
-        input.className = 'bp-choice__pick'
-        mock.append(input)
-
-        const frame = el(doc, 'div', 'bp-choice__mock-frame')
-        const frameInner = frameContent(opt.el)
-        if (frameInner) frame.append(frameInner)
-        mock.append(frame)
-
-        const cap = el(doc, 'div', 'bp-choice__mock-cap')
-        const h4 = el(doc, 'h4')
-        h4.textContent = opt.caption
-        cap.append(h4)
-        const chosen = el(doc, 'span', 'bp-choice__tag bp-choice__tag--ink bp-choice__mock-pick bp-choice__mock-chosen')
-        chosen.textContent = '✓ Chosen'
-        const rejected = el(doc, 'span', 'bp-choice__tag bp-choice__tag--out bp-choice__mock-pick bp-choice__mock-rejected')
-        rejected.textContent = 'Not chosen'
-        cap.append(chosen, rejected)
-        mock.append(cap)
-        gallery.append(mock)
-      }
-      form.append(gallery)
-
-      if (compareSummary && compareBody) {
-        const details = el(doc, 'details', 'bp-choice__compare')
-        const summary = el(doc, 'summary')
-        summary.textContent = compareSummary
-        details.append(summary)
-        const body = el(doc, 'div', 'bp-choice__compare-body')
-        body.append(compareBody.cloneNode(true))
-        details.append(body)
-        form.append(details)
+  renderChoice() {
+    if (!this.choiceSource || !this.choiceScopeId) return
+    const source = this.choiceSource
+    const hostState = this.choiceHostState
+    const lockedValue = hostState?.status === 'locked' ? hostState.value : hostState ? null : source.resolvedValue
+    if (lockedValue !== null) {
+      const root = buildResolvedChoice(this.ownerDocument, {
+        options: source.options,
+        verdictKicker: source.verdictKicker,
+        resolvedValue: lockedValue,
+      })
+      if (hostState) {
+        const reset = appendLockedHostActions(this.ownerDocument, root, {
+          message: hostState.message,
+          reconsider: source.reconsider,
+          busy: hostState.busy,
+        })
+        reset.addEventListener('click', () => {
+          dispatchChoiceEvent(this, 'bp-choice-reconsider', this.getDecisionManifest())
+        })
       }
-
-      form.append(
-        buildFooter(doc, hint || 'Select a mockup to track the decision', reconsider)
-      )
+      this.replaceChildren(root)
+      return
     }
 
+    const form = buildInteractiveChoice(this.ownerDocument, {
+      ...source,
+      scopeId: this.choiceScopeId,
+      initialValue: hostState?.value ?? null,
+      busy: hostState?.busy ?? false,
+      message: hostState?.message ?? '',
+    })
+    form.addEventListener('change', (event) => {
+      const input = event.target
+      if (!(input instanceof HTMLInputElement) || !input.checked) return
+      const isCommit = source.layout === 'tabs' ? input.classList.contains('bp-choice__commit') : input.classList.contains('bp-choice__pick')
+      if (!isCommit) return
+      const option = source.options.find((candidate) => candidate.value === input.value)
+      if (!option) return
+      dispatchChoiceEvent(this, 'bp-choice-commit', {
+        ...this.getDecisionManifest(),
+        value: option.value,
+        option: { value: option.value, label: option.title || option.tab || option.value, title: option.title },
+      })
+    })
+    form.addEventListener('reset', () => {
+      dispatchChoiceEvent(this, 'bp-choice-reconsider', this.getDecisionManifest())
+    })
     this.replaceChildren(form)
   }
 }

package/dist/blueprint-contract.json

@@ -1,13 +1,13 @@
 {
   "markupSchema": 2,
-  "frameworkVersion": "1.2.0",
-  "source": "github:FlatFilers/blueprint-framework@v1.2.0",
+  "frameworkVersion": "1.3.1",
+  "source": "github:FlatFilers/blueprint-framework@v1.3.1",
   "assets": {
     "vendor/blueprint/blueprint.css": {
-      "sha256": "34b0bf5882052a64d60bcbcf3663777d4165012cda555f6ec3f80a7711c73103"
+      "sha256": "eaf4ca1936c6231709fdafea34f47c5e919e31b9a5d3d69398542af7ba30bb83"
     },
     "vendor/blueprint/blueprint.js": {
-      "sha256": "9ec19cbbc24abd6da5331d7ddbace2e8b8c65e407f4734f1d0b9bcbb7a9a7f3b"
+      "sha256": "55f1b677d5302bddba2edb840d26bbe409252fce20345a3d4b6368fd04526954"
     }
   }
 }