@invisibleloop/pulse 0.1.21

package/src/ui/breadcrumbs.js

@@ -0,0 +1,38 @@
+/**
+ * Pulse UI — Breadcrumbs
+ *
+ * Accessible breadcrumb navigation. The last item (current page) renders as a
+ * <span> with aria-current="page". All other items render as links.
+ *
+ * @param {object} opts
+ * @param {Array}  opts.items      - Array of { label, href }. Last item has no href.
+ * @param {string} opts.separator  - Separator character (default: '/')
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function breadcrumbs({
+  items      = [],
+  separator  = '/',
+  class: cls = '',
+} = {}) {
+  const navClasses = ['ui-breadcrumbs', cls].filter(Boolean).join(' ')
+
+  const listItems = items.map((item, i) => {
+    const isLast = i === items.length - 1
+    const sep = i > 0
+      ? `<span class="ui-breadcrumbs-sep" aria-hidden="true">${e(separator)}</span>`
+      : ''
+
+    const content = isLast
+      ? `<span class="ui-breadcrumbs-current" aria-current="page">${e(item.label)}</span>`
+      : `<a href="${e(item.href)}" class="ui-breadcrumbs-link">${e(item.label)}</a>`
+
+    return `<li class="ui-breadcrumbs-item">${sep}${content}</li>`
+  }).join('')
+
+  return `<nav aria-label="Breadcrumb" class="${e(navClasses)}">
+  <ol class="ui-breadcrumbs-list">${listItems}</ol>
+</nav>`
+}

package/src/ui/button.js

@@ -0,0 +1,66 @@
+/**
+ * Pulse UI — Button
+ *
+ * Renders as <a> when href is provided, <button> otherwise.
+ * All visual variation goes through CSS modifier classes — never inline styles.
+ *
+ * @param {object} opts
+ * @param {string}  opts.label     - Visible text (required)
+ * @param {'primary'|'secondary'|'ghost'|'danger'} opts.variant
+ * @param {'sm'|'md'|'lg'} opts.size
+ * @param {string}  opts.href      - Renders as <a> when set
+ * @param {boolean} opts.disabled
+ * @param {'button'|'submit'|'reset'} opts.type
+ * @param {string}  opts.icon      - SVG HTML prepended inside the element
+ * @param {string}  opts.iconAfter - SVG HTML appended inside the element
+ * @param {boolean} opts.fullWidth
+ * @param {string}  opts.class     - Extra CSS classes appended to the element
+ * @param {object}  opts.attrs     - Extra HTML attributes (key→value) for <button> only
+ */
+
+import { escHtml as e } from '../html.js'
+
+const VARIANTS = new Set(['primary', 'secondary', 'ghost', 'danger'])
+const SIZES    = new Set(['sm', 'md', 'lg'])
+
+export function button({
+  label      = '',
+  variant    = 'primary',
+  size       = 'md',
+  href,
+  disabled   = false,
+  type       = 'button',
+  icon       = '',
+  iconAfter  = '',
+  fullWidth  = false,
+  class: cls = '',
+  attrs      = {},
+} = {}) {
+  if (!VARIANTS.has(variant)) variant = 'primary'
+  if (!SIZES.has(size))       size    = 'md'
+
+  const classes = [
+    'ui-btn',
+    `ui-btn--${variant}`,
+    `ui-btn--${size}`,
+    fullWidth  ? 'ui-btn--full'     : '',
+    disabled   ? 'ui-btn--disabled' : '',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const inner = [
+    icon      ? `<span class="ui-btn-icon" aria-hidden="true">${icon}</span>` : '',
+    `<span>${e(label)}</span>`,
+    iconAfter ? `<span class="ui-btn-icon ui-btn-icon--after" aria-hidden="true">${iconAfter}</span>` : '',
+  ].join('')
+
+  if (href) {
+    return `<a href="${e(href)}" class="${e(classes)}"${disabled ? ' aria-disabled="true" tabindex="-1"' : ''}>${inner}</a>`
+  }
+
+  const attrsStr = Object.entries(attrs)
+    .map(([k, v]) => ` ${e(k)}="${e(String(v))}"`)
+    .join('')
+
+  return `<button type="${e(type)}" class="${e(classes)}"${disabled ? ' disabled aria-disabled="true"' : ''}${attrsStr}>${inner}</button>`
+}

package/src/ui/card.js

@@ -0,0 +1,34 @@
+/**
+ * Pulse UI — Card
+ *
+ * Surface container with optional title and footer.
+ * Pass HTML strings for content and footer — they are not escaped.
+ * Escape user data before passing it in.
+ *
+ * @param {object} opts
+ * @param {string}  opts.title   - Escaped heading text (optional)
+ * @param {number}  opts.level   - Heading level 1–6 (default 3). Controls the tag; visual style is always ui-card-title.
+ * @param {string}  opts.content - HTML string for the card body
+ * @param {string}  opts.footer  - HTML string for the card footer (optional)
+ * @param {boolean} opts.flush   - Remove internal padding (for full-bleed content)
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function card({
+  title      = '',
+  level      = 3,
+  content    = '',
+  footer     = '',
+  flush      = false,
+  class: cls = '',
+} = {}) {
+  const classes = ['ui-card', flush ? 'ui-card--flush' : '', cls].filter(Boolean).join(' ')
+  const tag = `h${Math.min(Math.max(Math.floor(level), 1), 6)}`
+
+  const titleHtml  = title  ? `<div class="ui-card-header"><${tag} class="ui-card-title">${e(title)}</${tag}></div>` : ''
+  const footerHtml = footer ? `<div class="ui-card-footer">${footer}</div>` : ''
+
+  return `<div class="${e(classes)}">${titleHtml}<div class="ui-card-body">${content}</div>${footerHtml}</div>`
+}

package/src/ui/carousel.js

@@ -0,0 +1,59 @@
+/**
+ * Pulse UI — Carousel / Slider
+ *
+ * CSS scroll-snap carousel with optional prev/next arrows and dot navigation.
+ * Requires pulse-ui.js for button and dot interactivity.
+ *
+ * @param {object}   opts
+ * @param {string[]} opts.slides  - Array of raw HTML strings — one per slide
+ * @param {boolean}  opts.arrows  - Show prev/next arrow buttons (default: true)
+ * @param {boolean}  opts.dots    - Show dot navigation (default: true)
+ * @param {string}   opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+import { iconChevronLeft, iconChevronRight } from './icons.js'
+
+let _carouselId = 0
+
+export function carousel({
+  slides     = [],
+  arrows     = true,
+  dots       = true,
+  class: cls = '',
+} = {}) {
+  const id = `carousel-${++_carouselId}`
+  const classes = ['ui-carousel', cls].filter(Boolean).join(' ')
+
+  const slidesHtml = slides
+    .map((s, i) => {
+      const panelId = `${id}-panel-${i + 1}`
+      const tabId   = `${id}-tab-${i + 1}`
+      return `<div class="ui-carousel-slide" id="${panelId}" role="tabpanel" aria-labelledby="${tabId}" tabindex="0">${s}</div>`
+    })
+    .join('\n    ')
+
+  const arrowsHtml = arrows ? `
+  <button class="ui-carousel-btn ui-carousel-prev" type="button" aria-label="Previous slide" hidden>
+    ${iconChevronLeft({ size: 16 })}
+  </button>
+  <button class="ui-carousel-btn ui-carousel-next" type="button" aria-label="Next slide"${slides.length <= 1 ? ' hidden' : ''}>
+    ${iconChevronRight({ size: 16 })}
+  </button>` : ''
+
+  const dotsHtml = dots && slides.length > 1 ? `
+  <div class="ui-carousel-dots" role="tablist" aria-label="Slides">
+    ${slides.map((_, i) => {
+      const tabId   = `${id}-tab-${i + 1}`
+      const panelId = `${id}-panel-${i + 1}`
+      const active  = i === 0
+      return `<button class="ui-carousel-dot${active ? ' active' : ''}" id="${tabId}" type="button" role="tab" aria-selected="${active}" aria-controls="${panelId}" tabindex="${active ? '0' : '-1'}" aria-label="Slide ${i + 1}"></button>`
+    }).join('\n    ')}
+  </div>` : ''
+
+  return `<div class="${e(classes)}">
+  <div class="ui-carousel-track">
+    ${slidesHtml}
+  </div>${arrowsHtml}${dotsHtml}
+</div>`
+}

package/src/ui/charts.js

@@ -0,0 +1,321 @@
+/**
+ * Pulse UI — Charts
+ *
+ * Server-rendered SVG charts. Pure functions, no client JS, no dependencies.
+ * All charts use CSS custom properties for colours and scale to 100% width
+ * (except sparkline and donutChart which have explicit dimensions).
+ *
+ * @exports barChart   - Vertical bar chart
+ * @exports lineChart  - Line chart with optional area fill
+ * @exports donutChart - Donut / pie chart
+ * @exports sparkline  - Minimal inline line for stat tiles
+ */
+
+import { escHtml as e } from '../html.js'
+
+// ─── Internal constants ───────────────────────────────────────────────────────
+
+const IW = 500 // internal viewBox width for bar / line charts
+
+const COLOR_MAP = {
+  accent:  'var(--ui-accent)',
+  success: 'var(--ui-green)',
+  warning: 'var(--ui-yellow)',
+  error:   'var(--ui-red)',
+  blue:    'var(--ui-blue)',
+  muted:   'var(--ui-muted)',
+}
+
+const PALETTE = ['accent', 'blue', 'success', 'warning', 'error', 'muted']
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function col(c)  { return COLOR_MAP[c] ?? COLOR_MAP.accent }
+function r1(n)   { return Math.round(n * 10) / 10 }         // 1 decimal place
+function clamp(v, lo, hi) { return Math.max(lo, Math.min(hi, v)) }
+
+function fmt(n) {
+  const abs = Math.abs(n)
+  if (abs >= 1e6) return (n / 1e6).toFixed(1).replace(/\.0$/, '') + 'M'
+  if (abs >= 1e3) return (n / 1e3).toFixed(1).replace(/\.0$/, '') + 'k'
+  return String(Math.round(n))
+}
+
+// ─── Bar chart ────────────────────────────────────────────────────────────────
+
+/**
+ * Vertical bar chart.
+ *
+ * @param {object}  opts
+ * @param {Array<{label:string, value:number}>} opts.data
+ * @param {number}  opts.height     - SVG height in px (default: 220)
+ * @param {'accent'|'success'|'warning'|'error'|'blue'|'muted'} opts.color
+ * @param {boolean} opts.showValues - Show value labels above each bar
+ * @param {boolean} opts.showGrid   - Show horizontal grid lines (default: true)
+ * @param {number}  opts.gap        - Gap between bars as fraction 0–0.9 (default: 0.25)
+ * @param {string}  opts.class
+ */
+export function barChart({
+  data       = [],
+  height     = 220,
+  color      = 'accent',
+  showValues = false,
+  showGrid   = true,
+  gap        = 0.25,
+  class: cls = '',
+} = {}) {
+  if (!data.length) return ''
+
+  const pad   = { top: showValues ? 28 : 16, right: 16, bottom: 40, left: 44 }
+  const plotW = IW - pad.left - pad.right
+  const plotH = height - pad.top - pad.bottom
+
+  const values = data.map(d => Number(d.value) || 0)
+  const maxVal = Math.max(...values, 0)
+  const minVal = Math.min(...values, 0)
+  const range  = maxVal - minVal || 1
+  const c      = col(color)
+
+  const yFor  = v => r1(pad.top + plotH - ((v - minVal) / range) * plotH)
+  const zeroY = yFor(0)
+
+  // Grid lines + Y-axis labels
+  let grid = ''
+  if (showGrid) {
+    for (let i = 0; i <= 4; i++) {
+      const v = minVal + (i / 4) * range
+      const y = yFor(v)
+      grid += `<line x1="${pad.left}" y1="${r1(y)}" x2="${IW - pad.right}" y2="${r1(y)}" stroke="var(--ui-border)" stroke-width="1"/>`
+      grid += `<text x="${pad.left - 6}" y="${r1(y + 4)}" text-anchor="end" font-size="11" fill="var(--ui-muted)" font-family="var(--ui-font)">${e(fmt(v))}</text>`
+    }
+  }
+
+  // Zero baseline
+  const baseline = `<line x1="${pad.left}" y1="${zeroY}" x2="${IW - pad.right}" y2="${zeroY}" stroke="var(--ui-border)" stroke-width="1.5"/>`
+
+  // Bars + labels
+  const slotW = plotW / data.length
+  const barW  = r1(slotW * (1 - clamp(gap, 0.05, 0.9)))
+
+  const bars = data.map((d, i) => {
+    const v  = Number(d.value) || 0
+    const bx = r1(pad.left + i * slotW + (slotW - barW) / 2)
+    const by = r1(Math.min(yFor(v), zeroY))
+    const bh = r1(Math.max(Math.abs(yFor(v) - zeroY), 1))
+    const mx = r1(bx + barW / 2)
+
+    let out = `<rect x="${bx}" y="${by}" width="${barW}" height="${bh}" fill="${c}" rx="2"/>`
+    if (showValues) {
+      out += `<text x="${mx}" y="${r1(by - 5)}" text-anchor="middle" font-size="11" font-weight="600" fill="${c}" font-family="var(--ui-font)">${e(fmt(v))}</text>`
+    }
+    if (d.label != null) {
+      out += `<text x="${mx}" y="${height - 8}" text-anchor="middle" font-size="11" fill="var(--ui-muted)" font-family="var(--ui-font)">${e(String(d.label))}</text>`
+    }
+    return out
+  }).join('')
+
+  const ariaLabel = `Bar chart: ${data.map(d => `${d.label ?? ''} ${d.value}`).join(', ')}`
+  const clsAttr   = cls ? ` class="${e(cls)}"` : ''
+
+  return `<svg${clsAttr} viewBox="0 0 ${IW} ${height}" width="100%" height="${height}" role="img" aria-label="${e(ariaLabel)}">${grid}${baseline}${bars}</svg>`
+}
+
+// ─── Line chart ───────────────────────────────────────────────────────────────
+
+/**
+ * Line chart with optional area fill.
+ *
+ * @param {object}  opts
+ * @param {Array<{label:string, value:number}>} opts.data
+ * @param {number}  opts.height   - SVG height in px (default: 220)
+ * @param {'accent'|'success'|'warning'|'error'|'blue'|'muted'} opts.color
+ * @param {boolean} opts.area     - Fill the area under the line
+ * @param {boolean} opts.showDots - Show dots at each data point (default: true)
+ * @param {boolean} opts.showGrid - Show horizontal grid lines (default: true)
+ * @param {string}  opts.class
+ */
+export function lineChart({
+  data       = [],
+  height     = 220,
+  color      = 'accent',
+  area       = false,
+  showDots   = true,
+  showGrid   = true,
+  class: cls = '',
+} = {}) {
+  if (data.length < 2) return ''
+
+  const pad   = { top: 16, right: 16, bottom: 40, left: 44 }
+  const plotW = IW - pad.left - pad.right
+  const plotH = height - pad.top - pad.bottom
+
+  const values = data.map(d => Number(d.value) || 0)
+  const maxVal = Math.max(...values)
+  const minVal = Math.min(...values)
+  const range  = maxVal - minVal || 1
+  const c      = col(color)
+
+  const xFor = i => r1(pad.left + (i / (data.length - 1)) * plotW)
+  const yFor = v => r1(pad.top + plotH - ((v - minVal) / range) * plotH)
+
+  // Grid lines + Y-axis labels
+  let grid = ''
+  if (showGrid) {
+    for (let i = 0; i <= 4; i++) {
+      const v = minVal + (i / 4) * range
+      const y = yFor(v)
+      grid += `<line x1="${pad.left}" y1="${r1(y)}" x2="${IW - pad.right}" y2="${r1(y)}" stroke="var(--ui-border)" stroke-width="1"/>`
+      grid += `<text x="${pad.left - 6}" y="${r1(y + 4)}" text-anchor="end" font-size="11" fill="var(--ui-muted)" font-family="var(--ui-font)">${e(fmt(v))}</text>`
+    }
+  }
+
+  const pts    = data.map((d, i) => [xFor(i), yFor(Number(d.value) || 0)])
+  const points = pts.map(([x, y]) => `${x},${y}`).join(' ')
+
+  // Area fill
+  let areaPath = ''
+  if (area) {
+    const bottom = r1(pad.top + plotH)
+    const d = `M${pts[0][0]},${bottom} ` + pts.map(([x, y]) => `L${x},${y}`).join(' ') + ` L${pts.at(-1)[0]},${bottom} Z`
+    areaPath = `<path d="${d}" fill="${c}" fill-opacity="0.12"/>`
+  }
+
+  const line = `<polyline points="${points}" fill="none" stroke="${c}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>`
+  const dots = showDots ? pts.map(([x, y]) => `<circle cx="${x}" cy="${y}" r="3.5" fill="${c}"/>`).join('') : ''
+
+  // X-axis labels
+  const xlabels = data.map((d, i) =>
+    d.label != null
+      ? `<text x="${xFor(i)}" y="${height - 8}" text-anchor="middle" font-size="11" fill="var(--ui-muted)" font-family="var(--ui-font)">${e(String(d.label))}</text>`
+      : ''
+  ).join('')
+
+  const ariaLabel = `Line chart: ${data.map(d => `${d.label ?? ''} ${d.value}`).join(', ')}`
+  const clsAttr   = cls ? ` class="${e(cls)}"` : ''
+
+  return `<svg${clsAttr} viewBox="0 0 ${IW} ${height}" width="100%" height="${height}" role="img" aria-label="${e(ariaLabel)}">${grid}${areaPath}${line}${dots}${xlabels}</svg>`
+}
+
+// ─── Donut chart ──────────────────────────────────────────────────────────────
+
+/**
+ * Donut (ring) chart. Each segment can have its own colour.
+ *
+ * @param {object}  opts
+ * @param {Array<{label:string, value:number, color?:string}>} opts.data
+ * @param {number}  opts.size      - Diameter in px (default: 200)
+ * @param {number}  opts.thickness - Ring thickness in px (default: 40)
+ * @param {string}  opts.label     - Large text in the centre
+ * @param {string}  opts.sublabel  - Smaller text below the centre label
+ * @param {string}  opts.class
+ */
+export function donutChart({
+  data       = [],
+  size       = 200,
+  thickness  = 40,
+  label      = '',
+  sublabel   = '',
+  class: cls = '',
+} = {}) {
+  if (!data.length) return ''
+
+  const cx     = size / 2
+  const cy     = size / 2
+  const r      = cx - 8
+  const innerR = r - clamp(thickness, 4, r - 4)
+  const total  = data.reduce((s, d) => s + Math.max(0, Number(d.value) || 0), 0)
+  if (!total) return ''
+
+  let angle = -Math.PI / 2 // start at 12 o'clock
+
+  const segments = data.map((d, i) => {
+    const v     = Math.max(0, Number(d.value) || 0)
+    const frac  = v / total
+    const sweep = frac * 2 * Math.PI
+    const start = angle
+    const end   = angle + sweep
+    angle       = end
+
+    const c     = col(d.color || PALETTE[i % PALETTE.length])
+
+    // Full circle edge case
+    if (frac >= 1 - 1e-10) {
+      const mid = r1((r + innerR) / 2)
+      return `<circle cx="${cx}" cy="${cy}" r="${mid}" fill="none" stroke="${c}" stroke-width="${thickness}"/>`
+    }
+
+    const x1 = r1(cx + r      * Math.cos(start))
+    const y1 = r1(cy + r      * Math.sin(start))
+    const x2 = r1(cx + r      * Math.cos(end))
+    const y2 = r1(cy + r      * Math.sin(end))
+    const x3 = r1(cx + innerR * Math.cos(end))
+    const y3 = r1(cy + innerR * Math.sin(end))
+    const x4 = r1(cx + innerR * Math.cos(start))
+    const y4 = r1(cy + innerR * Math.sin(start))
+    const lg  = sweep > Math.PI ? 1 : 0
+
+    const path = `M${x1},${y1} A${r},${r} 0 ${lg} 1 ${x2},${y2} L${x3},${y3} A${innerR},${innerR} 0 ${lg} 0 ${x4},${y4} Z`
+    return `<path d="${path}" fill="${c}"/>`
+  }).join('')
+
+  // Centre text
+  const hasTwo  = label && sublabel
+  const labelY  = r1(cy + (hasTwo ? -6 : 6))
+  const subY    = r1(cy + 16)
+  const labelEl = label    ? `<text x="${cx}" y="${labelY}" text-anchor="middle" font-size="${thickness > 30 ? 22 : 16}" font-weight="700" fill="var(--ui-text)" font-family="var(--ui-font)">${e(label)}</text>` : ''
+  const subEl   = sublabel ? `<text x="${cx}" y="${subY}"   text-anchor="middle" font-size="12" fill="var(--ui-muted)" font-family="var(--ui-font)">${e(sublabel)}</text>` : ''
+
+  const ariaLabel = `Donut chart: ${data.map(d => `${d.label ?? ''} ${d.value}`).join(', ')}`
+  const clsAttr   = cls ? ` class="${e(cls)}"` : ''
+
+  return `<svg${clsAttr} viewBox="0 0 ${size} ${size}" width="${size}" height="${size}" role="img" aria-label="${e(ariaLabel)}">${segments}${labelEl}${subEl}</svg>`
+}
+
+// ─── Sparkline ────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal inline line chart for use inside stat tiles or table cells.
+ * Accepts a plain array of numbers.
+ *
+ * @param {object}   opts
+ * @param {number[]} opts.data   - Array of numeric values
+ * @param {number}   opts.width  - SVG width in px (default: 80)
+ * @param {number}   opts.height - SVG height in px (default: 32)
+ * @param {'accent'|'success'|'warning'|'error'|'blue'|'muted'} opts.color
+ * @param {boolean}  opts.area   - Fill area under the line
+ * @param {string}   opts.class
+ */
+export function sparkline({
+  data       = [],
+  width      = 80,
+  height     = 32,
+  color      = 'accent',
+  area       = false,
+  class: cls = '',
+} = {}) {
+  if (data.length < 2) return ''
+
+  const values = data.map(v => Number(v) || 0)
+  const min    = Math.min(...values)
+  const max    = Math.max(...values)
+  const range  = max - min || 1
+  const pad    = 2
+  const c      = col(color)
+
+  const xFor = i => r1(i * (width / (data.length - 1)))
+  const yFor = v => r1(height - pad - ((v - min) / range) * (height - pad * 2))
+
+  const pts    = values.map((v, i) => [xFor(i), yFor(v)])
+  const points = pts.map(([x, y]) => `${x},${y}`).join(' ')
+
+  let areaPath = ''
+  if (area) {
+    const bottom = height - pad
+    const d = `M${pts[0][0]},${bottom} ` + pts.map(([x, y]) => `L${x},${y}`).join(' ') + ` L${pts.at(-1)[0]},${bottom} Z`
+    areaPath = `<path d="${d}" fill="${c}" fill-opacity="0.15"/>`
+  }
+
+  const clsAttr = cls ? ` class="${e(cls)}"` : ''
+
+  return `<svg${clsAttr} viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" aria-hidden="true">${areaPath}<polyline points="${points}" fill="none" stroke="${c}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>`
+}

package/src/ui/checkbox.js

@@ -0,0 +1,65 @@
+/**
+ * Pulse UI — Checkbox
+ *
+ * Styled checkbox with optional label. Wraps a visually-hidden <input> and a
+ * custom box element driven by CSS :checked state.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.name       - Field name
+ * @param {string}  opts.value      - Submitted value
+ * @param {string}  opts.label      - Visible label text (escaped)
+ * @param {string}  opts.labelHtml  - Raw HTML label slot (not escaped — use for styled spans)
+ * @param {boolean} opts.checked
+ * @param {boolean} opts.disabled
+ * @param {string}  opts.id         - Override generated id
+ * @param {string}  opts.event      - data-event binding (e.g. 'change:toggle')
+ * @param {string}  opts.hint       - Helper text below the label
+ * @param {string}  opts.error      - Validation error message
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function checkbox({
+  name       = '',
+  value      = '',
+  label      = '',
+  labelHtml  = '',
+  checked    = false,
+  disabled   = false,
+  id         = '',
+  event      = '',
+  hint       = '',
+  error      = '',
+  class: cls = '',
+} = {}) {
+  const uid = e(id || ['checkbox', name, value].filter(Boolean).join('-'))
+
+  const classes = [
+    'ui-checkbox',
+    disabled        ? 'ui-checkbox--disabled' : '',
+    error           ? 'ui-checkbox--error'    : '',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const labelContent = labelHtml
+    ? labelHtml
+    : label ? `<span class="ui-checkbox-label">${e(label)}</span>` : ''
+
+  return `<label class="${e(classes)}">
+  <input
+    type="checkbox"
+    id="${uid}"
+    ${name  ? `name="${e(name)}"` : ''}
+    ${value ? `value="${e(value)}"` : ''}
+    class="ui-checkbox-input"
+    ${checked  ? 'checked'  : ''}
+    ${disabled ? 'disabled' : ''}
+    ${event    ? `data-event="${e(event)}"` : ''}
+  >
+  <span class="ui-checkbox-box" aria-hidden="true"></span>
+  ${labelContent}
+  ${hint  ? `<p class="ui-hint">${e(hint)}</p>`               : ''}
+  ${error ? `<p class="ui-error" role="alert">${e(error)}</p>` : ''}
+</label>`
+}

package/src/ui/cluster.js

@@ -0,0 +1,44 @@
+/**
+ * Pulse UI — Cluster
+ *
+ * Flex row with wrapping. Groups inline elements horizontally
+ * with consistent gap — buttons, badges, app store badges, stat rows, etc.
+ *
+ * @param {object} opts
+ * @param {string} opts.content                              - Raw HTML slot
+ * @param {'xs'|'sm'|'md'|'lg'} opts.gap                   - Gap between children (default: 'md')
+ * @param {'start'|'center'|'end'|'between'} opts.justify   - justify-content (default: 'start')
+ * @param {'start'|'center'|'end'} opts.align               - align-items (default: 'center')
+ * @param {boolean} opts.wrap                               - Allow wrapping (default: true)
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const GAPS     = new Set(['xs', 'sm', 'md', 'lg'])
+const JUSTIFYS = new Set(['start', 'center', 'end', 'between'])
+const ALIGNS   = new Set(['start', 'center', 'end'])
+
+export function cluster({
+  content    = '',
+  gap        = 'md',
+  justify    = 'start',
+  align      = 'center',
+  wrap       = true,
+  class: cls = '',
+} = {}) {
+  if (!GAPS.has(gap))       gap     = 'md'
+  if (!JUSTIFYS.has(justify)) justify = 'start'
+  if (!ALIGNS.has(align))   align   = 'center'
+
+  const classes = [
+    'ui-cluster',
+    gap     !== 'md'     && `ui-cluster--gap-${gap}`,
+    justify !== 'start'  && `ui-cluster--justify-${justify}`,
+    align   !== 'center' && `ui-cluster--align-${align}`,
+    !wrap                && 'ui-cluster--nowrap',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  return `<div class="${e(classes)}">${content}</div>`
+}

package/src/ui/code-window.js

@@ -0,0 +1,39 @@
+/**
+ * Pulse UI — Code Window
+ *
+ * A code block with macOS-style window chrome — three coloured dots and an
+ * optional filename label. The content slot accepts pre-highlighted HTML
+ * (spans with syntax-token classes) or plain text.
+ *
+ * Interactive syntax highlighting is out of scope — pass pre-rendered HTML
+ * or plain text. The component handles all the chrome, layout, scroll, and
+ * monospace typography.
+ *
+ * @param {object} opts
+ * @param {string} opts.content   - Raw HTML slot — highlighted code HTML or plain text
+ * @param {string} opts.filename  - Filename shown in the chrome bar (e.g. 'home.js')
+ * @param {string} opts.lang      - Language label shown on the right of the chrome (e.g. 'JavaScript')
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function codeWindow({
+  content    = '',
+  filename   = '',
+  lang       = '',
+  class: cls = '',
+} = {}) {
+  const classes = ['ui-code-window', cls].filter(Boolean).join(' ')
+
+  return `<div class="${e(classes)}" role="region"${filename ? ` aria-label="${e(filename)}"` : ''}>
+  <div class="ui-code-window-chrome" aria-hidden="true">
+    <span class="ui-code-window-dot"></span>
+    <span class="ui-code-window-dot"></span>
+    <span class="ui-code-window-dot"></span>
+    ${filename ? `<span class="ui-code-window-filename">${e(filename)}</span>` : ''}
+    ${lang     ? `<span class="ui-code-window-lang">${e(lang)}</span>` : ''}
+  </div>
+  <pre class="ui-code-window-pre"><code class="ui-code-window-code">${content}</code></pre>
+</div>`
+}