@invisibleloop/pulse 0.1.21

package/src/testing/testing.test.js

@@ -0,0 +1,450 @@
+/**
+ * Pulse — Testing helpers tests
+ * run: node src/testing/testing.test.js
+ */
+
+import { render, renderSync } from './index.js'
+
+// ---------------------------------------------------------------------------
+// Test runner
+// ---------------------------------------------------------------------------
+
+let passed = 0
+let failed = 0
+
+async function test(label, fn) {
+  try {
+    await fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    failed++
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg || 'Assertion failed')
+}
+
+function assertEqual(a, b) {
+  if (a !== b) throw new Error(`Expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}`)
+}
+
+// ---------------------------------------------------------------------------
+// Specs used across tests
+// ---------------------------------------------------------------------------
+
+const counterSpec = {
+  route: '/counter',
+  state: { count: 0 },
+  view:  (state) => `<div class="counter"><span id="count">${state.count}</span></div>`,
+}
+
+const productSpec = {
+  route: '/products/:id',
+  state: {},
+  server: {
+    product: async (ctx) => ({ id: ctx.params?.id ?? '1', name: 'Widget', price: 9.99 })
+  },
+  view: (_s, server) => `
+    <main>
+      <h1 class="title">${server.product.name}</h1>
+      <p class="price">$${server.product.price}</p>
+      <button type="button" data-event="buy" disabled>Buy</button>
+    </main>
+  `,
+}
+
+const formSpec = {
+  route: '/contact',
+  state: { name: '', email: '' },
+  view:  (state) => `
+    <form data-action="submit">
+      <input name="name" type="text" value="${state.name}" required>
+      <input name="email" type="email" value="${state.email}">
+      <button type="submit">Send</button>
+    </form>
+  `,
+}
+
+const segmentedSpec = {
+  route: '/page',
+  state: {},
+  view: {
+    header: () => '<header><h1>Title</h1></header>',
+    body:   () => '<main><p>Content</p></main>',
+  },
+}
+
+const listSpec = {
+  route: '/items',
+  state: {},
+  server: {
+    items: async () => ['Alpha', 'Beta', 'Gamma']
+  },
+  view: (_s, server) => `<ul>${server.items.map(i => `<li>${i}</li>`).join('')}</ul>`,
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('\nrenderSync — basic rendering\n')
+
+await test('renders view with default state', async () => {
+  const result = renderSync(counterSpec)
+  assert(result.html.includes('0'), `Expected 0, got: ${result.html}`)
+})
+
+await test('renders view with state overrides', async () => {
+  const result = renderSync(counterSpec, { state: { count: 42 } })
+  assert(result.html.includes('42'), `Expected 42, got: ${result.html}`)
+})
+
+await test('result.state reflects overrides merged with spec defaults', async () => {
+  const result = renderSync(counterSpec, { state: { count: 7 } })
+  assertEqual(result.state.count, 7)
+})
+
+await test('renders segmented view by concatenating all segments', async () => {
+  const result = renderSync(segmentedSpec)
+  assert(result.html.includes('<header>'), `Missing header: ${result.html}`)
+  assert(result.html.includes('<main>'),   `Missing main: ${result.html}`)
+})
+
+await test('renders view with mock server state', async () => {
+  const result = renderSync(productSpec, { server: { product: { name: 'Gadget', price: 19.99 } } })
+  assert(result.html.includes('Gadget'), `Expected Gadget, got: ${result.html}`)
+})
+
+await test('result.server reflects the server state provided', async () => {
+  const server = { product: { name: 'Gadget', price: 19.99 } }
+  const result = renderSync(productSpec, { server })
+  assertEqual(result.server.product.name, 'Gadget')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nrender — async rendering\n')
+
+await test('resolves spec.server fetchers and passes to view', async () => {
+  const result = await render(productSpec)
+  assert(result.html.includes('Widget'), `Expected Widget, got: ${result.html}`)
+})
+
+await test('passes ctx to server fetchers', async () => {
+  const result = await render(productSpec, { ctx: { params: { id: '99' } } })
+  assert(result.html.includes('Widget'), 'Expected Widget in output')
+  assertEqual(result.server.product.id, '99')
+})
+
+await test('bypasses fetchers when server is provided', async () => {
+  let fetcherCalled = false
+  const spec = {
+    route: '/mock',
+    state: {},
+    server: { data: async () => { fetcherCalled = true; return 'real' } },
+    view:  (_s, server) => `<p>${server.data}</p>`,
+  }
+  const result = await render(spec, { server: { data: 'mocked' } })
+  assert(!fetcherCalled,                    'Fetcher should not be called when server is provided')
+  assert(result.html.includes('mocked'),    `Expected mocked, got: ${result.html}`)
+})
+
+await test('resolves multiple fetchers in parallel', async () => {
+  const result = await render(listSpec)
+  assert(result.html.includes('Alpha'), `Missing Alpha: ${result.html}`)
+  assert(result.html.includes('Beta'),  `Missing Beta: ${result.html}`)
+  assert(result.html.includes('Gamma'), `Missing Gamma: ${result.html}`)
+})
+
+await test('result.server contains resolved fetcher results', async () => {
+  const result = await render(listSpec)
+  assert(Array.isArray(result.server.items),    'Expected items array')
+  assertEqual(result.server.items.length, 3)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nresult.text()\n')
+
+await test('returns all text content with tags stripped', async () => {
+  const result = renderSync(counterSpec, { state: { count: 5 } })
+  const text = result.text()
+  assertEqual(text, '5')
+})
+
+await test('collapses whitespace and joins text from multiple elements', async () => {
+  const result = renderSync(formSpec)
+  // Buttons have text "Send"
+  assert(result.text().includes('Send'), `Expected Send in text: ${result.text()}`)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nresult.has(selector)\n')
+
+await test('returns true when element exists', async () => {
+  const result = renderSync(counterSpec)
+  assert(result.has('div'), 'Expected div to exist')
+})
+
+await test('returns true for class selector', async () => {
+  const result = renderSync(counterSpec)
+  assert(result.has('.counter'), 'Expected .counter to exist')
+})
+
+await test('returns false when element does not exist', async () => {
+  const result = renderSync(counterSpec)
+  assert(!result.has('table'), 'Expected no table')
+})
+
+await test('matches attribute selector [attr]', async () => {
+  const result = renderSync(formSpec)
+  assert(result.has('[required]'), 'Expected [required] to exist')
+})
+
+await test('matches attribute selector [attr="value"]', async () => {
+  const result = renderSync(formSpec)
+  assert(result.has('input[type="email"]'), 'Expected email input')
+})
+
+await test('matches attribute selector [attr="value"] (negative)', async () => {
+  const result = renderSync(formSpec)
+  assert(!result.has('input[type="password"]'), 'Expected no password input')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nresult.find() and result.get()\n')
+
+await test('find() returns the first matching element', async () => {
+  const result = renderSync(counterSpec)
+  const el = result.find('span')
+  assert(el !== null, 'Expected span element')
+  assertEqual(el.tag, 'span')
+})
+
+await test('find() returns null when not found', async () => {
+  const result = renderSync(counterSpec)
+  const el = result.find('table')
+  assertEqual(el, null)
+})
+
+await test('get() returns the element when found', async () => {
+  const result = renderSync(counterSpec)
+  const el = result.get('.counter')
+  assert(el !== null, 'Expected .counter element')
+  assertEqual(el.tag, 'div')
+})
+
+await test('get() throws when element not found', async () => {
+  const result = renderSync(counterSpec)
+  let threw = false
+  try { result.get('table') } catch (e) {
+    threw = true
+    assert(e.message.includes('table'), `Expected selector in error: ${e.message}`)
+  }
+  assert(threw, 'Expected get() to throw')
+})
+
+await test('find() by id selector', async () => {
+  const result = renderSync(counterSpec, { state: { count: 3 } })
+  const el = result.find('#count')
+  assert(el !== null, 'Expected #count element')
+  assertEqual(el.text, '3')
+})
+
+await test('find() by compound selector (tag + class)', async () => {
+  const result = renderSync(counterSpec)
+  const el = result.find('div.counter')
+  assert(el !== null, 'Expected div.counter')
+})
+
+await test('find() by attribute selector', async () => {
+  const result = await render(productSpec, { server: { product: { name: 'W', price: 1 } } })
+  const el = result.find('[disabled]')
+  assert(el !== null, 'Expected disabled button')
+  assertEqual(el.tag, 'button')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nresult.findAll()\n')
+
+await test('findAll() returns all matching elements', async () => {
+  const result = await render(listSpec)
+  const items = result.findAll('li')
+  assertEqual(items.length, 3)
+})
+
+await test('findAll() returns empty array when nothing matches', async () => {
+  const result = renderSync(counterSpec)
+  const items = result.findAll('table')
+  assertEqual(items.length, 0)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nresult.count()\n')
+
+await test('count() returns the number of matching elements', async () => {
+  const result = renderSync(formSpec)
+  assertEqual(result.count('input'), 2)
+})
+
+await test('count() returns 0 when nothing matches', async () => {
+  const result = renderSync(counterSpec)
+  assertEqual(result.count('table'), 0)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nresult.attr()\n')
+
+await test('attr() returns attribute value', async () => {
+  const result = renderSync(formSpec)
+  assertEqual(result.attr('input[name="email"]', 'type'), 'email')
+})
+
+await test('attr() returns empty string for boolean attributes', async () => {
+  const result = await render(productSpec, { server: { product: { name: 'W', price: 1 } } })
+  assertEqual(result.attr('button[disabled]', 'disabled'), '')
+})
+
+await test('attr() returns null when element not found', async () => {
+  const result = renderSync(counterSpec)
+  assertEqual(result.attr('table', 'class'), null)
+})
+
+await test('attr() returns null when attribute not present', async () => {
+  const result = renderSync(counterSpec)
+  assertEqual(result.attr('span', 'data-missing'), null)
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nElement methods\n')
+
+await test('element.find() searches within the element', async () => {
+  const result = renderSync(counterSpec)
+  const container = result.get('.counter')
+  const span = container.find('span')
+  assert(span !== null, 'Expected span inside .counter')
+})
+
+await test('element.find() does not match outside the element', async () => {
+  const spec = {
+    route: '/test',
+    state: {},
+    view: () => `
+      <section id="a"><p class="target">A</p></section>
+      <section id="b"><p class="other">B</p></section>
+    `,
+  }
+  const result = renderSync(spec)
+  const a = result.get('#a')
+  assert(a.has('.target'), 'Expected .target in #a')
+  assert(!a.has('.other'), 'Expected .other to be outside #a')
+})
+
+await test('element.findAll() returns all descendants', async () => {
+  const result = await render(listSpec)
+  const ul = result.get('ul')
+  assertEqual(ul.findAll('li').length, 3)
+})
+
+await test('element.text returns inner text content', async () => {
+  const result = await render(listSpec)
+  const items = result.findAll('li')
+  assertEqual(items[0].text, 'Alpha')
+  assertEqual(items[1].text, 'Beta')
+  assertEqual(items[2].text, 'Gamma')
+})
+
+await test('element.attr() returns attribute value', async () => {
+  const result = renderSync(formSpec)
+  const email = result.get('input[type="email"]')
+  assertEqual(email.attr('name'), 'email')
+})
+
+await test('element.has() checks for descendants', async () => {
+  const result = renderSync(formSpec)
+  const form = result.get('form')
+  assert(form.has('button[type="submit"]'), 'Expected submit button in form')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nHTML entity handling\n')
+
+await test('text() decodes HTML entities', async () => {
+  const spec = {
+    route: '/esc',
+    state: { msg: 'Hello &amp; World' },
+    view:  (state) => `<p>${state.msg}</p>`,
+  }
+  const result = renderSync(spec)
+  assertEqual(result.get('p').text, 'Hello & World')
+})
+
+await test('text() decodes &lt; and &gt;', async () => {
+  const spec = {
+    route: '/esc2',
+    state: {},
+    view:  () => `<p>&lt;code&gt;</p>`,
+  }
+  const result = renderSync(spec)
+  assertEqual(result.get('p').text, '<code>')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nEdge cases\n')
+
+await test('handles void elements without closing tag', async () => {
+  const spec = {
+    route: '/void',
+    state: {},
+    view:  () => `<div><img src="/logo.png" alt="Logo"><input type="text"></div>`,
+  }
+  const result = renderSync(spec)
+  assert(result.has('img'), 'Expected img')
+  assert(result.has('input'), 'Expected input')
+  assertEqual(result.attr('img', 'src'), '/logo.png')
+})
+
+await test('handles nested same-tag elements correctly', async () => {
+  const spec = {
+    route: '/nested',
+    state: {},
+    view:  () => `<div class="outer"><div class="inner"><span>deep</span></div></div>`,
+  }
+  const result = renderSync(spec)
+  const outer = result.get('.outer')
+  const inner = outer.find('.inner')
+  assert(inner !== null, 'Expected .inner')
+  const span = inner.find('span')
+  assert(span !== null, 'Expected span in .inner')
+  assertEqual(span.text, 'deep')
+})
+
+await test('count() handles multiple disjoint elements', async () => {
+  const spec = {
+    route: '/multi',
+    state: {},
+    view:  () => `<ul><li>A</li><li>B</li><li>C</li></ul>`,
+  }
+  const result = renderSync(spec)
+  assertEqual(result.count('li'), 3)
+})
+
+await test('renderSync returns raw html string', async () => {
+  const result = renderSync(counterSpec)
+  assert(typeof result.html === 'string', 'Expected html to be a string')
+})
+
+// ---------------------------------------------------------------------------
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)

package/src/ui/accordion.js

@@ -0,0 +1,28 @@
+/**
+ * Pulse UI — Accordion
+ *
+ * Collapsible FAQ-style items using native <details>/<summary> — no JS required.
+ *
+ * @param {object}   opts
+ * @param {Array<{question: string, answer: string}>} opts.items
+ * @param {string}   opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function accordion({
+  items      = [],
+  class: cls = '',
+} = {}) {
+  const classes = ['ui-accordion', cls].filter(Boolean).join(' ')
+
+  const itemsHtml = items.map(({ question = '', answer = '' }) => `<details class="ui-accordion-item">
+  <summary class="ui-accordion-summary">
+    <span>${e(question)}</span>
+    <span class="ui-accordion-icon" aria-hidden="true"></span>
+  </summary>
+  <div class="ui-accordion-body"><p>${e(answer)}</p></div>
+</details>`).join('\n')
+
+  return `<div class="${e(classes)}">${itemsHtml}</div>`
+}

package/src/ui/alert.js

@@ -0,0 +1,43 @@
+/**
+ * Pulse UI — Alert
+ *
+ * Inline feedback message. error/warning use role="alert" (assertive),
+ * info/success use role="status" (polite).
+ *
+ * @param {object}  opts
+ * @param {'info'|'success'|'warning'|'error'} opts.variant
+ * @param {string}  opts.title   - Bold heading (optional)
+ * @param {string}  opts.content - Message body — HTML string, not escaped
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+import { iconInfo, iconCheckCircle, iconAlertTriangle, iconXCircle } from './icons.js'
+
+const VARIANTS = new Set(['info', 'success', 'warning', 'error'])
+
+const ICONS = {
+  info:    iconInfo({ size: 18 }),
+  success: iconCheckCircle({ size: 18 }),
+  warning: iconAlertTriangle({ size: 18 }),
+  error:   iconXCircle({ size: 18 }),
+}
+
+export function alert({
+  variant    = 'info',
+  title      = '',
+  content    = '',
+  class: cls = '',
+} = {}) {
+  if (!VARIANTS.has(variant)) variant = 'info'
+
+  const role    = (variant === 'error' || variant === 'warning') ? 'alert' : 'status'
+  const classes = ['ui-alert', `ui-alert--${variant}`, cls].filter(Boolean).join(' ')
+
+  const titleHtml = title ? `<strong class="ui-alert-title">${e(title)}</strong> ` : ''
+
+  return `<div class="${e(classes)}" role="${role}">
+  <span class="ui-alert-icon">${ICONS[variant]}</span>
+  <div class="ui-alert-body">${titleHtml}${content}</div>
+</div>`
+}

package/src/ui/app-badge.js

@@ -0,0 +1,48 @@
+/**
+ * Pulse UI — App Badge
+ *
+ * App Store and Google Play download buttons.
+ *
+ * @param {object} opts
+ * @param {'apple'|'google'} opts.store - Which badge to render
+ * @param {string} opts.href            - Link to the app store listing
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const APPLE_ICON = `<svg width="18" height="22" viewBox="0 0 814 1000" fill="currentColor" aria-hidden="true"><path d="M788.1 340.9c-5.8 4.5-108.2 62.2-108.2 190.5 0 148.4 130.3 200.9 134.2 202.2-.6 3.2-20.7 71.9-68.7 141.9-42.8 61.6-87.5 123.1-155.5 123.1s-85.5-39.5-164-39.5c-76 0-103.7 40.8-165.9 40.8s-105-37.2-148.8-97.2C67.6 772.6 20.4 678.3 20.4 588.3c0-154.8 100.9-236.7 199.6-236.7 74.7 0 136.8 47.4 183.1 47.4 44.4 0 113.9-49.9 197-49.9zm-234-181.5c31.1-36.9 53.1-88.1 53.1-139.3 0-7.1-.6-14.3-1.9-20.1-50.6 1.9-110.8 33.7-147.1 75.8-28.5 32.4-55.1 83.6-55.1 135.5 0 7.8 1.3 15.6 1.9 18.1 3.2.6 8.4 1.3 13.6 1.3 45.4 0 102.5-30.4 135.5-71.3z"/></svg>`
+
+const GOOGLE_ICON = `<svg width="18" height="20" viewBox="0 0 512 512" fill="currentColor" aria-hidden="true"><path d="M325.3 234.3L104.6 13l280.8 161.2-60.1 60.1zM47 0C34 6.8 25.3 19.2 25.3 35.3v441.3c0 16.1 8.7 28.5 21.7 35.3l232.6-232.5L47 0zm425.6 225.6l-58.9-34-67.7 68.6 67.7 68.5 60.1-34.3c17.3-9.8 17.3-38.1-.2-48.8zM104.6 499l280.8-161.2-60.1-60.1L104.6 499z"/></svg>`
+
+const CONFIGS = {
+  apple: {
+    icon:  APPLE_ICON,
+    line1: 'Download on the',
+    line2: 'App Store',
+    label: 'Download on the App Store',
+  },
+  google: {
+    icon:  GOOGLE_ICON,
+    line1: 'Get it on',
+    line2: 'Google Play',
+    label: 'Get it on Google Play',
+  },
+}
+
+export function appBadge({
+  store      = 'apple',
+  href       = '#',
+  class: cls = '',
+} = {}) {
+  const cfg = CONFIGS[store] ?? CONFIGS.apple
+  const classes = ['ui-app-badge', cls].filter(Boolean).join(' ')
+
+  return `<a href="${e(href)}" class="${e(classes)}" aria-label="${e(cfg.label)}" target="_blank" rel="noopener noreferrer">
+  ${cfg.icon}
+  <span class="ui-app-badge-text">
+    <span class="ui-app-badge-line1">${cfg.line1}</span>
+    <span class="ui-app-badge-line2">${cfg.line2}</span>
+  </span>
+</a>`
+}

package/src/ui/avatar.js

@@ -0,0 +1,47 @@
+/**
+ * Pulse UI — Avatar
+ *
+ * User image or initials fallback. Renders <img> when src is provided,
+ * <span> with initials otherwise. Initials are derived from alt text if not
+ * explicitly provided.
+ *
+ * @param {object} opts
+ * @param {string} opts.src       - Image URL (optional)
+ * @param {string} opts.alt       - Alt text / name (used to derive initials)
+ * @param {'sm'|'md'|'lg'|'xl'}  opts.size
+ * @param {string} opts.initials  - Override derived initials
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const SIZES = new Set(['sm', 'md', 'lg', 'xl'])
+
+function deriveInitials(alt) {
+  return (alt || '')
+    .trim()
+    .split(/\s+/)
+    .map(w => w[0] || '')
+    .join('')
+    .slice(0, 2)
+    .toUpperCase() || '?'
+}
+
+export function avatar({
+  src        = '',
+  alt        = '',
+  size       = 'md',
+  initials   = '',
+  class: cls = '',
+} = {}) {
+  if (!SIZES.has(size)) size = 'md'
+
+  const classes = ['ui-avatar', `ui-avatar--${size}`, cls].filter(Boolean).join(' ')
+
+  if (src) {
+    return `<img src="${e(src)}" alt="${e(alt)}" class="${e(classes)}" width="40" height="40" loading="lazy" decoding="async">`
+  }
+
+  const display = initials || deriveInitials(alt)
+  return `<span class="${e(classes)}" aria-label="${e(alt || 'Avatar')}" role="img">${e(display)}</span>`
+}

package/src/ui/badge.js

@@ -0,0 +1,24 @@
+/**
+ * Pulse UI — Badge
+ *
+ * Inline label for status, category, or count.
+ *
+ * @param {object} opts
+ * @param {string} opts.label
+ * @param {'default'|'success'|'warning'|'error'|'info'} opts.variant
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const VARIANTS = new Set(['default', 'success', 'warning', 'error', 'info'])
+
+export function badge({
+  label      = '',
+  variant    = 'default',
+  class: cls = '',
+} = {}) {
+  if (!VARIANTS.has(variant)) variant = 'default'
+  const classes = ['ui-badge', `ui-badge--${variant}`, cls].filter(Boolean).join(' ')
+  return `<span class="${e(classes)}">${e(label)}</span>`
+}

package/src/ui/banner.js

@@ -0,0 +1,26 @@
+/**
+ * Pulse UI — Banner
+ *
+ * Full-width announcement bar — sits above the nav for promotions,
+ * notices, or launch announcements.
+ *
+ * @param {object} opts
+ * @param {string} opts.content                     - Raw HTML slot
+ * @param {'info'|'promo'|'warning'} opts.variant   - Visual style (default: 'info')
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const VARIANTS = new Set(['info', 'promo', 'warning'])
+
+export function banner({
+  content    = '',
+  variant    = 'info',
+  class: cls = '',
+} = {}) {
+  if (!VARIANTS.has(variant)) variant = 'info'
+  const classes = ['ui-banner', `ui-banner--${variant}`, cls].filter(Boolean).join(' ')
+
+  return `<div class="${e(classes)}" role="banner">${content}</div>`
+}