@invisibleloop/pulse 0.1.21

package/src/ui/index.js

@@ -0,0 +1,89 @@
+/**
+ * Pulse UI — Component library
+ *
+ * Server-rendered HTML string components. Import what you need:
+ *
+ *   import { button, card, input } from '@invisibleloop/pulse/ui'
+ *
+ * All components:
+ * - Are pure functions: (props) => HTML string
+ * - Escape user data automatically
+ * - Use CSS custom properties for all visual values
+ * - Require no client-side JS
+ * - Meet WCAG AA contrast and keyboard accessibility requirements
+ * - Work at all viewport sizes
+ *
+ * Theming: override CSS custom properties in :root in your stylesheet.
+ * Extending: add new CSS modifier classes (e.g. .ui-btn--brand).
+ * Do not modify component source files — extend via CSS only.
+ */
+
+export { button }      from './button.js'
+export { badge }       from './badge.js'
+export { card }        from './card.js'
+export { input }       from './input.js'
+export { search }      from './search.js'
+export { fieldset }    from './fieldset.js'
+export { select }      from './select.js'
+export { textarea }    from './textarea.js'
+export { alert }       from './alert.js'
+export { stat }        from './stat.js'
+export { avatar }      from './avatar.js'
+export { empty }       from './empty.js'
+export { table }       from './table.js'
+export { hero }        from './hero.js'
+export { testimonial } from './testimonial.js'
+export { feature }     from './feature.js'
+export { pricing }     from './pricing.js'
+export { accordion }   from './accordion.js'
+export { nav }         from './nav.js'
+export { appBadge }    from './app-badge.js'
+export { container }   from './container.js'
+export { section }     from './section.js'
+export { grid }        from './grid.js'
+export { stack }       from './stack.js'
+export { cluster }     from './cluster.js'
+export { divider }     from './divider.js'
+export { banner }        from './banner.js'
+export { media }         from './media.js'
+export { tooltip }       from './tooltip.js'
+export { modal, modalTrigger } from './modal.js'
+export { carousel }      from './carousel.js'
+export { cta }           from './cta.js'
+export { codeWindow }    from './code-window.js'
+export { footer }        from './footer.js'
+export { timeline, timelineItem } from './timeline.js'
+export { toggle }                from './switch.js'
+export { checkbox }              from './checkbox.js'
+export { radio, radioGroup }     from './radio.js'
+export { rating }                from './rating.js'
+export { spinner }               from './spinner.js'
+export { progress }              from './progress.js'
+export { barChart, lineChart, donutChart, sparkline } from './charts.js'
+export { slider }      from './slider.js'
+export { segmented }   from './segmented.js'
+export { fileUpload }  from './fileupload.js'
+export { breadcrumbs } from './breadcrumbs.js'
+export { stepper }     from './stepper.js'
+export { uiImage }     from './uiimage.js'
+export { pullquote }   from './pullquote.js'
+export { prose }       from './prose.js'
+export { heading }     from './heading.js'
+export { list }        from './list.js'
+export {
+  iconArrowLeft, iconArrowRight, iconArrowUp, iconArrowDown,
+  iconChevronLeft, iconChevronRight, iconChevronUp, iconChevronDown,
+  iconExternalLink, iconMenu, iconX, iconMoreHorizontal, iconMoreVertical,
+  iconCheck, iconCheckCircle, iconXCircle, iconAlertCircle, iconAlertTriangle, iconInfo,
+  iconPlus, iconMinus, iconEdit, iconTrash, iconCopy, iconSearch, iconFilter,
+  iconDownload, iconUpload, iconRefresh, iconSend,
+  iconEye, iconEyeOff, iconLock, iconUnlock, iconSettings, iconBell,
+  iconUser, iconUsers, iconMail, iconMessageSquare,
+  iconHome, iconLogOut, iconLogIn,
+  iconFile, iconImage, iconLink, iconCode, iconCalendar, iconClock, iconBookmark, iconTag,
+  iconPlay, iconPause, iconVolume, iconStar, iconHeart,
+  iconPhone, iconGamepad,
+  iconHandPointUp, iconHandPointDown, iconHandPointLeft, iconHandPointRight,
+  iconGlobe, iconShield, iconZap, iconTrendingUp, iconTrendingDown, iconLoader, iconGrid, iconBug, iconMapPin,
+  iconSun, iconMoon,
+} from './icons.js'

package/src/ui/input.js

@@ -0,0 +1,74 @@
+/**
+ * Pulse UI — Input
+ *
+ * Text input with label, hint, and error message.
+ * aria-describedby is wired automatically from name when error/hint are present.
+ *
+ * @param {object} opts
+ * @param {string}  opts.name        - Field name (also used as id base)
+ * @param {string}  opts.label       - Visible label text
+ * @param {string}  opts.type        - Input type (default: 'text')
+ * @param {string}  opts.placeholder
+ * @param {string}  opts.value       - Pre-filled value
+ * @param {string}  opts.error       - Validation error message
+ * @param {string}  opts.hint        - Helper text below the input
+ * @param {boolean} opts.required
+ * @param {boolean} opts.disabled
+ * @param {string}  opts.id          - Override generated id
+ * @param {string}  opts.class
+ * @param {object}  opts.attrs       - Extra HTML attributes for the <input>
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function input({
+  name        = '',
+  label       = '',
+  type        = 'text',
+  placeholder = '',
+  value       = '',
+  error       = '',
+  hint        = '',
+  required    = false,
+  disabled    = false,
+  id          = '',
+  class: cls  = '',
+  attrs       = {},
+} = {}) {
+  const fieldId   = e(id || `field-${name}`)
+  const errorId   = `${fieldId}-error`
+  const hintId    = `${fieldId}-hint`
+  const described = [error ? errorId : '', hint ? hintId : ''].filter(Boolean).join(' ')
+
+  const wrapClasses = ['ui-field', error ? 'ui-field--error' : '', cls].filter(Boolean).join(' ')
+
+  const attrsStr = Object.entries(attrs)
+    .map(([k, v]) => ` ${e(k)}="${e(String(v))}"`)
+    .join('')
+
+  const labelHtml = label
+    ? `<label for="${fieldId}" class="ui-label">${e(label)}${required ? ' <span class="ui-required" aria-hidden="true">*</span>' : ''}</label>`
+    : ''
+
+  const hintHtml  = hint  ? `<p id="${hintId}" class="ui-hint">${e(hint)}</p>`                    : ''
+  const errorHtml = error ? `<p id="${errorId}" class="ui-error" role="alert">${e(error)}</p>`    : ''
+
+  return `<div class="${e(wrapClasses)}">
+  ${labelHtml}
+  <input
+    id="${fieldId}"
+    name="${e(name)}"
+    type="${e(type)}"
+    class="ui-input"
+    ${placeholder ? `placeholder="${e(placeholder)}"` : ''}
+    ${value       ? `value="${e(value)}"`              : ''}
+    ${required    ? 'required aria-required="true"'    : ''}
+    ${disabled    ? 'disabled'                         : ''}
+    ${described   ? `aria-describedby="${described}"`  : ''}
+    ${error       ? 'aria-invalid="true"'              : ''}
+    ${attrsStr}
+  >
+  ${hintHtml}
+  ${errorHtml}
+</div>`
+}

package/src/ui/list.js

@@ -0,0 +1,36 @@
+/**
+ * Pulse UI — List
+ *
+ * Styled ordered or unordered list. Use this instead of raw <ul>/<ol> to get
+ * consistent spacing, bullets, and colour tokens.
+ *
+ * Items are HTML strings — escape user data before passing them in.
+ *
+ * @param {object}   opts
+ * @param {string[]} opts.items   - Array of HTML strings for each list item
+ * @param {boolean}  [opts.ordered] - true for <ol>, false for <ul> (default: false)
+ * @param {string}   [opts.gap]     - Item spacing: 'xs'|'sm'|'md' (default: 'sm')
+ * @param {string}   [opts.class]   - Extra classes on the list element
+ */
+
+export function list({
+  items      = [],
+  ordered    = false,
+  gap        = 'sm',
+  class: cls = '',
+} = {}) {
+  if (!items.length) return ''
+
+  const tag     = ordered ? 'ol' : 'ul'
+  const gapMap  = { xs: 'u-gap-1', sm: 'u-gap-2', md: 'u-gap-3' }
+  const classes = [
+    'ui-list',
+    ordered ? 'ui-list--ordered' : 'ui-list--unordered',
+    gapMap[gap] || 'u-gap-2',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const itemsHtml = items.map(item => `<li class="ui-list-item">${item}</li>`).join('')
+
+  return `<${tag} class="${classes}">${itemsHtml}</${tag}>`
+}

package/src/ui/media.js

@@ -0,0 +1,44 @@
+/**
+ * Pulse UI — Media
+ *
+ * Image + text side-by-side layout. Stacks vertically on mobile.
+ * The image slot accepts any HTML — <img>, <figure>, an SVG, or a styled div.
+ *
+ * @param {object} opts
+ * @param {string} opts.image              - Raw HTML slot — the visual side
+ * @param {string} opts.content            - Raw HTML slot — the text side
+ * @param {boolean} opts.reverse           - Put text left, image right (default: false)
+ * @param {'start'|'center'} opts.align    - Vertical alignment of columns (default: 'center')
+ * @param {'sm'|'md'|'lg'} opts.gap        - Gap between columns (default: 'md')
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const ALIGNS = new Set(['start', 'center'])
+const GAPS   = new Set(['sm', 'md', 'lg'])
+
+export function media({
+  image      = '',
+  content    = '',
+  reverse    = false,
+  align      = 'center',
+  gap        = 'md',
+  class: cls = '',
+} = {}) {
+  if (!ALIGNS.has(align)) align = 'center'
+  if (!GAPS.has(gap))     gap   = 'md'
+
+  const classes = [
+    'ui-media',
+    reverse         && 'ui-media--reverse',
+    align !== 'center' && `ui-media--align-${align}`,
+    gap   !== 'md'  && `ui-media--gap-${gap}`,
+    cls,
+  ].filter(Boolean).join(' ')
+
+  return `<div class="${e(classes)}">
+  <div class="ui-media-image">${image}</div>
+  <div class="ui-media-content">${content}</div>
+</div>`
+}

package/src/ui/modal.js

@@ -0,0 +1,80 @@
+/**
+ * Pulse UI — Modal
+ *
+ * A <dialog>-based modal. Use modal() to render the dialog element and
+ * modalTrigger() (or any element with data-modal-open="id") to open it.
+ *
+ * Requires pulse-ui.js for the open trigger.
+ * The close button inside the dialog uses native <form method="dialog"> — no JS needed.
+ * Clicking the backdrop also closes the modal (handled by pulse-ui.js).
+ *
+ * @param {object}            opts
+ * @param {string}            opts.id       - Unique ID — required so triggers can target this dialog
+ * @param {string}            opts.title    - Dialog heading
+ * @param {number}            opts.level    - Heading level 1–6 (default 2). Visual style is always ui-modal-title.
+ * @param {string}            opts.content  - Body HTML
+ * @param {string}            opts.footer   - Footer HTML — typically button() calls
+ * @param {'sm'|'md'|'lg'|'xl'} opts.size
+ * @param {string}            opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+import { iconX } from './icons.js'
+
+const SIZES = new Set(['sm', 'md', 'lg', 'xl'])
+
+export function modal({
+  id         = '',
+  title      = '',
+  level      = 2,
+  content    = '',
+  footer     = '',
+  size       = 'md',
+  class: cls = '',
+} = {}) {
+  if (!SIZES.has(size)) size = 'md'
+
+  const classes = ['ui-modal', size !== 'md' && `ui-modal--${size}`, cls].filter(Boolean).join(' ')
+  const tag = `h${Math.min(Math.max(Math.floor(level), 1), 6)}`
+
+  return `<dialog class="${e(classes)}"${id ? ` id="${e(id)}"` : ''}${id ? ` aria-labelledby="${e(id)}-title"` : ''}>
+  <form method="dialog" class="ui-modal-inner">
+    <header class="ui-modal-header">
+      <${tag} class="ui-modal-title"${id ? ` id="${e(id)}-title"` : ''}>${e(title)}</${tag}>
+      <button type="submit" class="ui-modal-close" aria-label="Close dialog">
+        ${iconX({ size: 16 })}
+      </button>
+    </header>
+    <div class="ui-modal-body">${content}</div>
+    ${footer ? `<footer class="ui-modal-footer">${footer}</footer>` : ''}
+  </form>
+</dialog>`
+}
+
+/**
+ * Button that opens a modal by ID.
+ * Any element with data-modal-open="<id>" also works with pulse-ui.js.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.target   - The modal's id attribute
+ * @param {string}  opts.label    - Button label
+ * @param {'primary'|'secondary'|'ghost'|'danger'} opts.variant
+ * @param {'sm'|'md'|'lg'} opts.size
+ * @param {string}  opts.class
+ */
+export function modalTrigger({
+  target     = '',
+  label      = 'Open',
+  variant    = 'primary',
+  size       = 'md',
+  class: cls = '',
+} = {}) {
+  const VARIANTS = new Set(['primary', 'secondary', 'ghost', 'danger'])
+  const BTN_SIZES = new Set(['sm', 'md', 'lg'])
+  if (!VARIANTS.has(variant)) variant = 'primary'
+  if (!BTN_SIZES.has(size))   size    = 'md'
+
+  const classes = ['ui-btn', `ui-btn--${variant}`, `ui-btn--${size}`, cls].filter(Boolean).join(' ')
+
+  return `<button type="button" class="${e(classes)}" data-dialog-open="${e(target)}"><span>${e(label)}</span></button>`
+}

package/src/ui/nav.js

@@ -0,0 +1,61 @@
+/**
+ * Pulse UI — Nav
+ *
+ * Site header with logo, navigation links, and an optional CTA slot.
+ * Set sticky: true for a position: sticky top bar with backdrop blur.
+ *
+ * On mobile (< 640px) links are hidden behind a burger button. Clicking
+ * the burger toggles the .ui-nav--open class on the <header>, which
+ * reveals an absolutely-positioned dropdown that overlays page content.
+ * Wired automatically by pulse-ui.js — no extra JS needed.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.logo      - Raw HTML slot — SVG, img, or text
+ * @param {string}  opts.logoHref  - Logo link destination (default: '/')
+ * @param {Array<{label: string, href: string}>} opts.links
+ * @param {string}  opts.action    - Raw HTML slot — typically a button()
+ * @param {boolean} opts.sticky      - Position sticky with backdrop blur
+ * @param {'right'|'left'} opts.burgerAlign - Mobile burger position (default: 'right')
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+import { iconMenu, iconX } from './icons.js'
+
+let _navId = 0
+
+export function nav({
+  logo          = '',
+  logoHref      = '/',
+  links         = [],
+  action        = '',
+  sticky        = false,
+  burgerAlign   = 'right',
+  class: cls    = '',
+} = {}) {
+  const id      = `ui-nav-${++_navId}`
+  const classes = ['ui-nav', sticky && 'ui-nav--sticky', burgerAlign === 'left' && 'ui-nav--burger-left', cls].filter(Boolean).join(' ')
+
+  const linksHtml = links.map(({ label = '', href = '' }) =>
+    `<a href="${e(href)}" class="ui-nav-link">${e(label)}</a>`
+  ).join('')
+
+  const burgerHtml = links.length ? `
+  <button class="ui-nav-burger" type="button" aria-label="Toggle menu" aria-expanded="false" aria-controls="${id}-mobile">
+    ${iconMenu({ size: 20, class: 'ui-nav-burger-open' })}
+    ${iconX({ size: 20, class: 'ui-nav-burger-close' })}
+  </button>` : ''
+
+  const mobileMenuHtml = links.length ? `
+  <div class="ui-nav-mobile" id="${id}-mobile" aria-label="Mobile navigation">
+    <nav>${linksHtml}</nav>
+  </div>` : ''
+
+  return `<header class="${e(classes)}">
+  <div class="ui-nav-inner">
+    <a href="${e(logoHref)}" class="ui-nav-logo">${logo}</a>
+    ${links.length ? `<nav class="ui-nav-links" aria-label="Site navigation">${linksHtml}</nav>` : ''}
+    ${action ? `<div class="ui-nav-action">${action}</div>` : ''}${burgerHtml}
+  </div>${mobileMenuHtml}
+</header>`
+}

package/src/ui/pricing.js

@@ -0,0 +1,56 @@
+/**
+ * Pulse UI — Pricing
+ *
+ * A single pricing plan card with feature list and CTA.
+ * Compose multiple in a flex/grid container for a full pricing section.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.name        - Plan name (e.g. "Pro")
+ * @param {number}   opts.level       - Heading level 1–6 for the plan name (default 3). Visual style is always ui-pricing-name.
+ * @param {string}   opts.price       - Price string (e.g. "$9", "Free")
+ * @param {string}   opts.period      - Billing period (e.g. "/month")
+ * @param {string}   opts.description - One-line plan description
+ * @param {string[]} opts.features    - Array of feature strings
+ * @param {string}   opts.action      - Raw HTML slot — typically a button()
+ * @param {boolean}  opts.highlighted - Accent border + elevated appearance
+ * @param {string}   opts.badge       - Floating label above the card (e.g. "Most popular")
+ * @param {string}   opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function pricing({
+  name        = '',
+  level       = 3,
+  price       = '',
+  period      = '',
+  description = '',
+  features    = [],
+  action      = '',
+  highlighted = false,
+  badge       = '',
+  class: cls  = '',
+} = {}) {
+  const classes = ['ui-pricing', highlighted && 'ui-pricing--highlighted', cls].filter(Boolean).join(' ')
+  const tag = `h${Math.min(Math.max(Math.floor(level), 1), 6)}`
+
+  const featureList = features.length
+    ? `<ul class="ui-pricing-features">
+  ${features.map(f => `<li class="ui-pricing-feature"><span class="ui-pricing-check" aria-hidden="true">✓</span>${e(f)}</li>`).join('\n  ')}
+</ul>`
+    : ''
+
+  return `<div class="${e(classes)}">
+  ${badge ? `<p class="ui-pricing-badge">${e(badge)}</p>` : ''}
+  <div class="ui-pricing-header">
+    ${name        ? `<${tag} class="ui-pricing-name">${e(name)}</${tag}>` : ''}
+    ${description ? `<p class="ui-pricing-desc">${e(description)}</p>` : ''}
+  </div>
+  <div class="ui-pricing-price">
+    <span class="ui-pricing-amount">${e(price)}</span>
+    ${period ? `<span class="ui-pricing-period">${e(period)}</span>` : ''}
+  </div>
+  ${featureList}
+  ${action ? `<div class="ui-pricing-action">${action}</div>` : ''}
+</div>`
+}

package/src/ui/progress.js

@@ -0,0 +1,62 @@
+/**
+ * Pulse UI — Progress
+ *
+ * Horizontal progress bar. Supports determinate and indeterminate states.
+ *
+ * @param {object}  opts
+ * @param {number}  opts.value      - Current value (0–max). Omit for indeterminate.
+ * @param {number}  opts.max        - Maximum value (default: 100)
+ * @param {string}  opts.label      - Accessible label
+ * @param {boolean} opts.showLabel  - Render label text above the bar
+ * @param {boolean} opts.showValue  - Render percentage above the bar (right-aligned)
+ * @param {'accent'|'success'|'warning'|'error'} opts.variant
+ * @param {'sm'|'md'|'lg'} opts.size
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const VARIANTS = { accent: 'accent', success: 'success', warning: 'warning', error: 'error' }
+const SIZES    = { sm: '.25rem', md: '.5rem', lg: '1rem' }
+
+export function progress({
+  value      = undefined,
+  max        = 100,
+  label      = '',
+  showLabel  = false,
+  showValue  = false,
+  variant    = 'accent',
+  size       = 'md',
+  class: cls = '',
+} = {}) {
+  const indeterminate = value === undefined || value === null
+  const clamped       = indeterminate ? 0 : Math.min(Math.max(Number(value), 0), max)
+  const pct           = indeterminate ? 0 : Math.round((clamped / max) * 100)
+  const v             = VARIANTS[variant] ?? 'accent'
+  const h             = SIZES[size]       ?? SIZES.md
+
+  const classes = [
+    'ui-progress',
+    `ui-progress--${v}`,
+    indeterminate ? 'ui-progress--indeterminate' : '',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const header = (showLabel || showValue) ? `
+  <div class="ui-progress-header">
+    ${showLabel && label ? `<span class="ui-progress-label">${e(label)}</span>` : '<span></span>'}
+    ${showValue && !indeterminate ? `<span class="ui-progress-value">${pct}%</span>` : ''}
+  </div>` : ''
+
+  return `<div
+  class="${e(classes)}"
+  role="progressbar"
+  ${!indeterminate ? `aria-valuenow="${clamped}" aria-valuemin="0" aria-valuemax="${max}"` : ''}
+  ${label ? `aria-label="${e(label)}"` : ''}
+  style="--progress-height:${h}"
+>${header}
+  <div class="ui-progress-track">
+    <div class="ui-progress-fill" style="${indeterminate ? '' : `width:${pct}%`}"></div>
+  </div>
+</div>`
+}

package/src/ui/prose.js

@@ -0,0 +1,29 @@
+/**
+ * Pulse UI — Prose
+ *
+ * Typography wrapper for rich text content: CMS output, markdown-rendered HTML,
+ * blog posts, article bodies, legal text, etc.
+ *
+ * Styles all descendant elements (h1–h6, p, ul, ol, li, a, blockquote, code,
+ * pre, table, hr, img) without requiring classes on individual elements.
+ * Use this any time you're outputting HTML you don't control.
+ *
+ * @param {object} opts
+ * @param {string}  opts.content - Raw HTML string (NOT escaped — trust only server-side content)
+ * @param {string}  [opts.size]  - 'sm' | 'base' | 'lg'  (default: 'base')
+ * @param {string}  [opts.class] - Extra classes on the wrapper
+ */
+
+export function prose({
+  content    = '',
+  size       = 'base',
+  class: cls = '',
+} = {}) {
+  const classes = [
+    'ui-prose',
+    size !== 'base' ? `ui-prose--${size}` : '',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  return `<div class="${classes}">${content}</div>`
+}

package/src/ui/pullquote.js

@@ -0,0 +1,34 @@
+/**
+ * Pulse UI — Pullquote
+ *
+ * Styled blockquote with accent left border and optional attribution.
+ *
+ * @param {object} opts
+ * @param {string} opts.quote  - The quote text
+ * @param {string} opts.cite   - Attribution (name, role, etc.)
+ * @param {'md'|'lg'} opts.size - Size variant (default: 'md')
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function pullquote({
+  quote      = '',
+  cite       = '',
+  size       = 'md',
+  class: cls = '',
+} = {}) {
+  const sizeClass   = size === 'lg' ? 'ui-pullquote--lg' : ''
+  const figClasses  = ['ui-pullquote', sizeClass, cls].filter(Boolean).join(' ')
+
+  const citeHtml = cite
+    ? `<figcaption class="ui-pullquote-cite">${e(cite)}</figcaption>`
+    : ''
+
+  return `<figure class="${e(figClasses)}">
+  <blockquote>
+    <p class="ui-pullquote-text">${e(quote)}</p>
+  </blockquote>
+  ${citeHtml}
+</figure>`
+}

package/src/ui/radio.js

@@ -0,0 +1,102 @@
+/**
+ * Pulse UI — Radio & RadioGroup
+ *
+ * radio()      — single radio button with label
+ * radioGroup() — semantic fieldset of radio options
+ *
+ * @param {object}   opts                    (radio)
+ * @param {string}   opts.name               - Field name
+ * @param {string}   opts.value              - Submitted value
+ * @param {string}   opts.label              - Visible label
+ * @param {boolean}  opts.checked
+ * @param {boolean}  opts.disabled
+ * @param {string}   opts.id                 - Override generated id
+ * @param {string}   opts.class
+ *
+ * @param {object}   opts                    (radioGroup)
+ * @param {string}   opts.name               - Shared field name
+ * @param {string}   opts.legend             - Group label (renders as <legend>)
+ * @param {Array}    opts.options             - [{ value, label, hint?, disabled? }]
+ * @param {string}   opts.value              - Currently selected value
+ * @param {string}   opts.hint               - Helper text below the group
+ * @param {string}   opts.error              - Validation error message
+ * @param {'sm'|'md'|'lg'} opts.gap          - Gap between options (default: 'md')
+ * @param {string}   opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function radio({
+  name       = '',
+  value      = '',
+  label      = '',
+  checked    = false,
+  disabled   = false,
+  id         = '',
+  event      = '',
+  class: cls = '',
+} = {}) {
+  const fieldId = e(id || `radio-${name}-${value}`)
+  const classes = ['ui-radio', cls].filter(Boolean).join(' ')
+
+  return `<label class="${e(classes)}${disabled ? ' ui-radio--disabled' : ''}">
+  <input
+    type="radio"
+    id="${fieldId}"
+    name="${e(name)}"
+    value="${e(value)}"
+    class="ui-radio-input"
+    ${checked  ? 'checked'  : ''}
+    ${disabled ? 'disabled' : ''}
+    ${event    ? `data-event="${e(event)}"` : ''}
+  >
+  <span class="ui-radio-dot" aria-hidden="true"></span>
+  ${label ? `<span class="ui-radio-label">${e(label)}</span>` : ''}
+</label>`
+}
+
+const GAPS = { sm: '.375rem', md: '.75rem', lg: '1.25rem' }
+
+export function radioGroup({
+  name       = '',
+  legend     = '',
+  options    = [],
+  value      = '',
+  hint       = '',
+  error      = '',
+  gap        = 'md',
+  event      = '',
+  class: cls = '',
+} = {}) {
+  const groupId  = `radiogroup-${name}`
+  const errorId  = `${groupId}-error`
+  const hintId   = `${groupId}-hint`
+  const gapValue = GAPS[gap] ?? GAPS.md
+
+  const described = [error ? errorId : '', hint ? hintId : ''].filter(Boolean).join(' ')
+
+  const items = options.map(opt =>
+    radio({
+      name,
+      value:    opt.value,
+      label:    opt.label,
+      checked:  String(opt.value) === String(value),
+      disabled: opt.disabled ?? false,
+      event,
+    }) + (opt.hint ? `<p class="ui-hint" style="margin:-.25rem 0 0 2rem">${e(opt.hint)}</p>` : '')
+  ).join('')
+
+  const hintHtml  = hint  ? `<p id="${hintId}"  class="ui-hint">${e(hint)}</p>`                   : ''
+  const errorHtml = error ? `<p id="${errorId}" class="ui-error" role="alert">${e(error)}</p>`     : ''
+
+  const classes = ['ui-radio-group', error ? 'ui-radio-group--error' : '', cls].filter(Boolean).join(' ')
+
+  return `<fieldset class="${e(classes)}"${described ? ` aria-describedby="${described}"` : ''}>
+  ${legend ? `<legend class="ui-fieldset-legend">${e(legend)}</legend>` : ''}
+  <div class="ui-radio-group-body" style="--radio-gap:${gapValue}">
+    ${items}
+    ${hintHtml}
+    ${errorHtml}
+  </div>
+</fieldset>`
+}