@invisibleloop/pulse 0.1.21

package/src/ui/switch.js

@@ -0,0 +1,57 @@
+/**
+ * Pulse UI — Switch
+ *
+ * iOS-style toggle switch. Renders a visually hidden checkbox with a custom
+ * styled track and thumb. Works with FormData — reads as 'on' when checked.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.name      - Field name
+ * @param {string}  opts.label     - Visible label text
+ * @param {boolean} opts.checked   - Initial checked state
+ * @param {boolean} opts.disabled
+ * @param {string}  opts.hint      - Helper text below the switch
+ * @param {string}  opts.id        - Override generated id
+ * @param {string}  opts.event     - data-event binding, e.g. 'change:setEnabled'
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function toggle({
+  name       = '',
+  label      = '',
+  checked    = false,
+  disabled   = false,
+  hint       = '',
+  id         = '',
+  event      = '',
+  class: cls = '',
+} = {}) {
+  const fieldId  = e(id || `field-${name}`)
+  const hintId   = `${fieldId}-hint`
+  const classes  = ['ui-switch', cls].filter(Boolean).join(' ')
+
+  const hintHtml = hint
+    ? `<p id="${hintId}" class="ui-hint">${e(hint)}</p>`
+    : ''
+
+  return `<div class="${e(classes)}">
+  <label class="ui-switch-label${disabled ? ' ui-switch-label--disabled' : ''}">
+    <input
+      type="checkbox"
+      id="${fieldId}"
+      name="${e(name)}"
+      class="ui-switch-input"
+      ${checked  ? 'checked'  : ''}
+      ${disabled ? 'disabled' : ''}
+      ${event    ? `data-event="${e(event)}"` : ''}
+      ${hint     ? `aria-describedby="${hintId}"` : ''}
+    >
+    <span class="ui-switch-track" aria-hidden="true">
+      <span class="ui-switch-thumb"></span>
+    </span>
+    ${label ? `<span class="ui-switch-text">${e(label)}</span>` : ''}
+  </label>
+  ${hintHtml}
+</div>`
+}

package/src/ui/table.js

@@ -0,0 +1,45 @@
+/**
+ * Pulse UI — Table
+ *
+ * Responsive, accessible data table.
+ * The scroll wrapper has role="region" and tabindex="0" so keyboard users can
+ * scroll horizontally. Cells accept HTML strings (not escaped) — escape
+ * user data before passing it in.
+ *
+ * @param {object}   opts
+ * @param {string[]} opts.headers  - Column header labels (escaped automatically)
+ * @param {Array[]}  opts.rows     - 2D array of cell content (HTML strings)
+ * @param {string}   opts.caption  - Accessible caption (also used as aria-label)
+ * @param {string}   opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function table({
+  headers    = [],
+  rows       = [],
+  caption    = '',
+  class: cls = '',
+} = {}) {
+  const wrapClasses = ['ui-table-wrap', cls].filter(Boolean).join(' ')
+
+  const captionHtml = caption
+    ? `<caption class="ui-table-caption">${e(caption)}</caption>`
+    : ''
+
+  const ths = headers
+    .map(h => `<th scope="col">${e(h)}</th>`)
+    .join('')
+
+  const trs = rows
+    .map(row => `<tr>${row.map(cell => `<td>${cell}</td>`).join('')}</tr>`)
+    .join('')
+
+  return `<div class="${e(wrapClasses)}" role="region" aria-label="${e(caption || 'Table')}" tabindex="0">
+  <table class="ui-table">
+    ${captionHtml}
+    <thead><tr>${ths}</tr></thead>
+    <tbody>${trs}</tbody>
+  </table>
+</div>`
+}

package/src/ui/testimonial.js

@@ -0,0 +1,48 @@
+/**
+ * Pulse UI — Testimonial
+ *
+ * A customer quote with optional star rating, avatar, and attribution.
+ *
+ * @param {object} opts
+ * @param {string} opts.quote   - The testimonial text
+ * @param {string} opts.name    - Author full name
+ * @param {string} opts.role    - Author role/company (e.g. "CEO at Acme")
+ * @param {string} opts.src     - Avatar image URL; falls back to initials when omitted
+ * @param {number} opts.rating  - Star rating 1–5; omit to hide stars
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function testimonial({
+  quote      = '',
+  name       = '',
+  role       = '',
+  src        = '',
+  rating     = 0,
+  class: cls = '',
+} = {}) {
+  const classes = ['ui-testimonial', cls].filter(Boolean).join(' ')
+
+  const stars = rating > 0
+    ? `<p class="ui-testimonial-rating" aria-label="${Math.round(rating)} out of 5 stars">${'★'.repeat(Math.min(5, Math.max(1, Math.round(rating))))}</p>`
+    : ''
+
+  const initials = name.split(' ').map(w => w[0]).join('').slice(0, 2).toUpperCase()
+
+  const avatarHtml = src
+    ? `<img src="${e(src)}" alt="${e(name)}" class="ui-testimonial-avatar" loading="lazy" width="40" height="40">`
+    : `<div class="ui-testimonial-avatar ui-testimonial-avatar--initials" aria-hidden="true">${e(initials)}</div>`
+
+  return `<figure class="${e(classes)}">
+  ${stars}
+  <blockquote class="ui-testimonial-quote"><p>${e(quote)}</p></blockquote>
+  <figcaption class="ui-testimonial-author">
+    ${avatarHtml}
+    <div class="ui-testimonial-meta">
+      <p class="ui-testimonial-name">${e(name)}</p>
+      ${role ? `<p class="ui-testimonial-role">${e(role)}</p>` : ''}
+    </div>
+  </figcaption>
+</figure>`
+}

package/src/ui/textarea.js

@@ -0,0 +1,72 @@
+/**
+ * Pulse UI — Textarea
+ *
+ * Multi-line text input with label, hint, and error message.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.name
+ * @param {string}  opts.label
+ * @param {string}  opts.placeholder
+ * @param {string}  opts.value
+ * @param {number}  opts.rows
+ * @param {string}  opts.error
+ * @param {string}  opts.hint
+ * @param {boolean} opts.required
+ * @param {boolean} opts.disabled
+ * @param {string}  opts.id
+ * @param {string}  opts.class
+ * @param {object}  opts.attrs
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function textarea({
+  name        = '',
+  label       = '',
+  placeholder = '',
+  value       = '',
+  rows        = 4,
+  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}
+  <textarea
+    id="${fieldId}"
+    name="${e(name)}"
+    class="ui-textarea"
+    rows="${Number(rows) || 4}"
+    ${placeholder ? `placeholder="${e(placeholder)}"` : ''}
+    ${required    ? 'required aria-required="true"'   : ''}
+    ${disabled    ? 'disabled'                         : ''}
+    ${described   ? `aria-describedby="${described}"`  : ''}
+    ${error       ? 'aria-invalid="true"'              : ''}
+    ${attrsStr}
+  >${e(value)}</textarea>
+  ${hintHtml}
+  ${errorHtml}
+</div>`
+}

package/src/ui/timeline.js

@@ -0,0 +1,72 @@
+/**
+ * Pulse UI — Timeline
+ *
+ * Ordered list of events or steps connected by a line.
+ * Supports vertical (default) and horizontal orientations.
+ * Each item accepts a raw HTML content slot — pass any component output.
+ *
+ * @param {object}   opts
+ * @param {'vertical'|'horizontal'} opts.direction - Orientation (default: 'vertical')
+ * @param {Array}    opts.items   - Array of timelineItem option objects
+ * @param {string}   opts.content - Raw HTML alternative to opts.items (advanced)
+ * @param {string}   opts.class
+ *
+ * timelineItem:
+ * @param {string}   opts.dot      - Raw HTML inside the dot — SVG icon or emoji
+ * @param {'accent'|'success'|'warning'|'error'|'muted'} opts.dotColor
+ * @param {string}   opts.label    - Timestamp or step label (escaped)
+ * @param {string}   opts.content  - Raw HTML body — any component output
+ */
+
+import { escHtml as e } from '../html.js'
+
+const DOT_COLORS = new Set(['accent', 'success', 'warning', 'error', 'muted'])
+
+export function timelineItem({
+  dot        = '',
+  dotColor   = 'accent',
+  label      = '',
+  content    = '',
+  class: cls = '',
+} = {}) {
+  if (!DOT_COLORS.has(dotColor)) dotColor = 'accent'
+
+  const dotClasses = [
+    'ui-timeline-dot',
+    `ui-timeline-dot--${dotColor}`,
+    dot ? 'ui-timeline-dot--icon' : '',
+  ].filter(Boolean).join(' ')
+
+  const labelHtml = label
+    ? `<span class="ui-timeline-label">${e(label)}</span>`
+    : ''
+
+  const itemClasses = ['ui-timeline-item', cls].filter(Boolean).join(' ')
+
+  return `<li class="${itemClasses}">
+  <div class="ui-timeline-side">
+    <div class="ui-timeline-connector ui-timeline-connector--before"></div>
+    <div class="${e(dotClasses)}" aria-hidden="true">${dot}</div>
+    <div class="ui-timeline-connector ui-timeline-connector--after"></div>
+  </div>
+  <div class="ui-timeline-main">
+    ${labelHtml}
+    <div class="ui-timeline-body">${content}</div>
+  </div>
+</li>`
+}
+
+export function timeline({
+  direction  = 'vertical',
+  items      = [],
+  content    = '',
+  class: cls = '',
+} = {}) {
+  if (direction !== 'horizontal') direction = 'vertical'
+
+  const classes = ['ui-timeline', `ui-timeline--${direction}`, cls].filter(Boolean).join(' ')
+
+  const itemsHtml = content || items.map(item => timelineItem(item)).join('')
+
+  return `<ol class="${e(classes)}">${itemsHtml}</ol>`
+}

package/src/ui/tooltip.js

@@ -0,0 +1,28 @@
+/**
+ * Pulse UI — Tooltip
+ *
+ * CSS-powered tooltip. Wraps any trigger element — no JavaScript required.
+ *
+ * @param {object}                          opts
+ * @param {string}                          opts.content   - Tooltip text (plain text; HTML not rendered)
+ * @param {string}                          opts.trigger   - Raw HTML slot — the element the tooltip appears on
+ * @param {'top'|'bottom'|'left'|'right'}   opts.position  - Placement (default: 'top')
+ * @param {string}                          opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const POSITIONS = new Set(['top', 'bottom', 'left', 'right'])
+
+export function tooltip({
+  content    = '',
+  trigger    = '',
+  position   = 'top',
+  class: cls = '',
+} = {}) {
+  if (!POSITIONS.has(position)) position = 'top'
+
+  const classes = ['ui-tooltip', `ui-tooltip--${position}`, cls].filter(Boolean).join(' ')
+
+  return `<span class="${e(classes)}" data-tip="${e(content)}" aria-label="${e(content)}">${trigger}</span>`
+}