@invisibleloop/pulse 0.1.21

package/docs/src/pages/components/list.js

@@ -0,0 +1,112 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { list } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/list')
+
+export default {
+  route: '/components/list',
+  meta: {
+    title: 'List — Pulse Docs',
+    description: 'Styled ordered and unordered list component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/list',
+    prev,
+    next,
+    name: 'list',
+    description: 'Styled unordered or ordered list with consistent spacing and colour tokens. Use this instead of raw <code>&lt;ul&gt;</code> / <code>&lt;ol&gt;</code>. Items are HTML strings — other components can be passed as items.',
+    content: `
+
+      <h2 class="doc-h2" id="unordered">Unordered</h2>
+      ${demo(
+        list({ items: ['Streaming SSR on every page', 'Security headers by default', 'Zero client-side dependencies', 'Lighthouse 100 out of the box'] }),
+        `list({
+  items: [
+    'Streaming SSR on every page',
+    'Security headers by default',
+    'Zero client-side dependencies',
+    'Lighthouse 100 out of the box',
+  ],
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="ordered">Ordered</h2>
+      ${demo(
+        list({
+          ordered: true,
+          items: ['Create a new Pulse project', 'Add your pages to <code>src/pages/</code>', 'Run <code>pulse dev</code> to start the server', 'Deploy when ready'],
+        }),
+        `list({
+  ordered: true,
+  items: [
+    'Create a new Pulse project',
+    'Add your pages to src/pages/',
+    'Run pulse dev to start the server',
+    'Deploy when ready',
+  ],
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="gap">Gap</h2>
+      <p>Control vertical spacing between items with the <code>gap</code> prop.</p>
+      ${demo(
+        `<div class="u-flex u-gap-8">
+          <div>
+            <p class="u-text-muted u-text-sm u-mb-2">xs</p>
+            ${list({ gap: 'xs', items: ['Design', 'Build', 'Ship'] })}
+          </div>
+          <div>
+            <p class="u-text-muted u-text-sm u-mb-2">sm (default)</p>
+            ${list({ gap: 'sm', items: ['Design', 'Build', 'Ship'] })}
+          </div>
+          <div>
+            <p class="u-text-muted u-text-sm u-mb-2">md</p>
+            ${list({ gap: 'md', items: ['Design', 'Build', 'Ship'] })}
+          </div>
+        </div>`,
+        `list({ gap: 'xs', items: [...] })
+list({ gap: 'sm', items: [...] })  // default
+list({ gap: 'md', items: [...] })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="rich-items">Items with markup</h2>
+      <p>Items are HTML strings — pass any markup including other components. Always escape user data before including it in item strings.</p>
+      ${demo(
+        list({
+          items: [
+            `<strong>spec.state</strong> — initial client state, deep-cloned on mount`,
+            `<strong>spec.mutations</strong> — synchronous state updates`,
+            `<strong>spec.actions</strong> — async operations with lifecycle hooks`,
+            `<strong>spec.server</strong> — server-side data fetchers`,
+          ],
+        }),
+        `list({
+  items: [
+    '<strong>spec.state</strong> — initial client state',
+    '<strong>spec.mutations</strong> — synchronous state updates',
+    '<strong>spec.actions</strong> — async operations with lifecycle hooks',
+    '<strong>spec.server</strong> — server-side data fetchers',
+  ],
+})`,
+        { col: true }
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>items</code>',   'string[]',                         '—',             'Array of HTML strings for each list item — escape user data before passing'],
+          ['<code>ordered</code>', 'boolean',                          '<code>false</code>', '<code>false</code> renders <code>&lt;ul&gt;</code>, <code>true</code> renders <code>&lt;ol&gt;</code>'],
+          ['<code>gap</code>',     '<code>xs | sm | md</code>',        '<code>sm</code>',    'Vertical spacing between items'],
+          ['<code>class</code>',   'string',                           '—',             'Extra classes on the list element'],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/media.js

@@ -0,0 +1,51 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { button, stack, media } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/media')
+
+export default {
+  route: '/components/media',
+  meta: {
+    title: 'Media — Pulse Docs',
+    description: 'Media component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/media',
+    prev,
+    next,
+    name: 'media',
+    description: 'Two-column image + text layout. Stacks vertically on mobile. Set <code>reverse</code> to alternate image position for multi-block feature sections.',
+    content: `
+      ${demo(
+        media({
+          image:   `<div style="background:var(--ui-surface-2);border:1px solid var(--ui-border);border-radius:8px;aspect-ratio:16/9;display:flex;align-items:center;justify-content:center;color:var(--ui-muted);font-size:.875rem">Screenshot</div>`,
+          content: stack({ gap: 'md', content: '<h3 style="font-size:1.25rem;font-weight:700;color:var(--ui-text);margin:0">One-tap controls</h3><p style="color:var(--ui-muted);margin:0">Tap to flap. Chippy Bird takes seconds to learn and a lifetime to conquer.</p>' + button({ label: 'Download', href: '#' }) }),
+        }),
+        `media({
+  image:   \`<img src="\${screenshot}" alt="App screenshot">\`,
+  content: stack({ gap: 'md', content:
+    '<h3>One-tap controls</h3>' +
+    '<p>Tap to flap.</p>' +
+    button({ label: 'Download', href: appStoreUrl })
+  }),
+  reverse: false,
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>image</code>',   'string (HTML)', '—',         'Raw HTML slot — img, figure, SVG, or styled div'],
+          ['<code>content</code>', 'string (HTML)', '—',         'Raw HTML slot'],
+          ['<code>reverse</code>', 'boolean',       'false',     'Puts text left, image right'],
+          ['<code>align</code>',   'string',        "'center'",  "'center' · 'start'"],
+          ['<code>gap</code>',     'string',        "'md'",      "'sm' · 'md' · 'lg'"],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/modal.js

@@ -0,0 +1,111 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout } from '../../lib/layout.js'
+import { modal, modalTrigger, button, cluster } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/modal')
+
+export default {
+  route: '/components/modal',
+  meta: {
+    title: 'Modal — Pulse Docs',
+    description: 'Modal dialog component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/modal',
+    prev,
+    next,
+    name: 'modal / modalTrigger',
+    description: 'A <code>&lt;dialog&gt;</code>-based modal with backdrop, animated open/close, and keyboard dismiss. The Pulse runtime handles open and close natively — no extra script needed.',
+    content: `
+      ${demo(
+        cluster({ justify: 'center', content:
+          modalTrigger({ target: 'demo-modal', label: 'Open modal' }) +
+          modal({
+            id:      'demo-modal',
+            title:   'Confirm action',
+            content: '<p style="color:var(--ui-muted);margin:0">Are you sure you want to delete this item? This action cannot be undone.</p>',
+            footer:
+              button({ label: 'Cancel', variant: 'secondary', type: 'submit' }) +
+              button({ label: 'Delete', variant: 'danger' }),
+          }),
+        }),
+        `// Render the dialog somewhere on the page
+modal({
+  id:      'confirm-delete',
+  title:   'Confirm action',
+  content: '<p>Are you sure? This cannot be undone.</p>',
+  footer:
+    button({ label: 'Cancel', variant: 'secondary' }) +
+    button({ label: 'Delete', variant: 'danger' }),
+})
+
+// Open it with a trigger button (or any element with data-dialog-open)
+modalTrigger({ target: 'confirm-delete', label: 'Delete item', variant: 'danger' })`
+      )}
+
+      <h3 class="doc-h3" id="sizes"><a href="#sizes" class="heading-anchor">Sizes</a></h3>
+      ${demo(
+        cluster({ gap: 'sm', justify: 'center', content:
+          modalTrigger({ target: 'demo-sm', label: 'Small',  variant: 'secondary', size: 'sm' }) +
+          modalTrigger({ target: 'demo-lg', label: 'Large',  variant: 'secondary', size: 'sm' }) +
+          modal({ id: 'demo-sm', title: 'Small modal',  size: 'sm',  content: '<p style="color:var(--ui-muted);margin:0">A compact dialog for quick confirmations.</p>' }) +
+          modal({ id: 'demo-lg', title: 'Large modal',  size: 'lg',  content: '<p style="color:var(--ui-muted);margin:0">Use large modals for forms, rich content, or detail views that need more space.</p>' }),
+        }),
+        `modal({ id: 'my-modal', title: 'Large modal', size: 'lg', content: '...' })`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>id</code>',      'string',                        '—',              'Unique ID — required for triggers to target this dialog'],
+          ['<code>title</code>',   'string',                        '—',              ''],
+          ['<code>level</code>',   'number',                        '2',              'Heading tag for the title (1–6). Visual style is unchanged.'],
+          ['<code>content</code>', 'string (HTML)',                  '—',              'Body HTML'],
+          ['<code>footer</code>',  'string (HTML)',                  '—',              'Footer HTML — typically button() calls'],
+          ['<code>size</code>',    '<code>sm | md | lg | xl</code>', '<code>md</code>', ''],
+          ['<code>class</code>',   'string',                        '—',              ''],
+        ]
+      )}
+
+      <h3 class="doc-h3" id="trigger-props"><a href="#trigger-props" class="heading-anchor">modalTrigger props</a></h3>
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>target</code>',  'string',                                          '—',                 "The modal's <code>id</code>"],
+          ['<code>label</code>',   'string',                                          '<code>Open</code>', ''],
+          ['<code>variant</code>', '<code>primary | secondary | ghost | danger</code>', '<code>primary</code>', ''],
+          ['<code>size</code>',    '<code>sm | md | lg</code>',                        '<code>md</code>',   ''],
+          ['<code>class</code>',   'string',                                          '—',                 ''],
+        ]
+      )}
+
+      <h3 class="doc-h3" id="custom-trigger"><a href="#custom-trigger" class="heading-anchor">Custom triggers</a></h3>
+      <p class="doc-body">Any element with <code>data-dialog-open="&lt;id&gt;"</code> opens the dialog when clicked. Use <code>data-dialog-close</code> on any element inside or outside the dialog to close it programmatically:</p>
+      <pre class="code-block"><code>&lt;button data-dialog-open="my-modal"&gt;Open&lt;/button&gt;
+&lt;button data-dialog-close&gt;Cancel&lt;/button&gt;</code></pre>
+      ${callout('tip', 'The dialog also closes on ESC, backdrop click, and <code>&lt;form method="dialog"&gt;</code> submit — all native browser behaviour, no JavaScript needed.')}
+
+      <h3 class="doc-h3" id="forms-inside"><a href="#forms-inside" class="heading-anchor">Forms inside a modal</a></h3>
+      <p class="doc-body"><code>modal()</code> wraps all content in <code>&lt;form method="dialog"&gt;</code> for native close behaviour. You <strong>cannot nest a <code>&lt;form data-action="..."&gt;</code> inside it</strong> — browsers silently discard nested forms, so the action will never fire.</p>
+      <p class="doc-body">When a modal button needs to trigger a Pulse action, place the form <em>outside</em> the modal and use the HTML <code>form</code> attribute to associate the button with it:</p>
+      <pre class="code-block"><code>// The action form lives outside the modal — hidden, no visible fields needed
+&lt;form id="delete-form" data-action="deleteAccount" style="display:none"&gt;&lt;/form&gt;
+
+\${modal({
+  id:      'confirm-delete',
+  title:   'Delete account?',
+  content: '&lt;p&gt;This cannot be undone.&lt;/p&gt;',
+  footer:
+    // type="submit" with no form= closes the modal natively (submits &lt;form method="dialog"&gt;)
+    button({ label: 'Cancel',         variant: 'secondary', type: 'submit' }) +
+    // form="delete-form" associates this button with the external form → fires the action
+    button({ label: 'Confirm delete', variant: 'danger', attrs: { form: 'delete-form', type: 'submit' } }),
+})}</code></pre>
+      ${callout('note', 'The hidden form needs no visible fields. <code>onStart</code> receives <code>state</code> and <code>formData</code> — read anything you need from state directly.')}
+    `,
+  }),
+}

package/docs/src/pages/components/nav.js

@@ -0,0 +1,86 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { button, nav as uiNav } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/nav')
+
+export default {
+  route: '/components/nav',
+  meta: {
+    title: 'Nav — Pulse Docs',
+    description: 'Nav component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/nav',
+    prev,
+    next,
+    name: 'nav',
+    description: 'Sticky-capable site header with logo, navigation links, and an optional CTA button. On mobile (&lt; 640px) links collapse behind a burger button — clicking it reveals an overlay panel that sits on top of page content without pushing it down. Wired automatically by <code>pulse-ui.js</code>.',
+    content: `
+      ${demo(
+        uiNav({
+          logo:     '<strong>MyApp</strong>',
+          logoHref: '/',
+          links:    [{ label: 'Features', href: '#features' }, { label: 'Pricing', href: '#pricing' }, { label: 'FAQ', href: '#faq' }],
+          action:   button({ label: 'Download', size: 'sm' }),
+          sticky:   false,
+        }),
+        `nav({
+  logo:     '<strong>MyApp</strong>',
+  logoHref: '/',
+  links: [
+    { label: 'Features', href: '#features' },
+    { label: 'Pricing',  href: '#pricing'  },
+    { label: 'FAQ',      href: '#faq'      },
+  ],
+  action: button({ label: 'Download', size: 'sm' }),
+  sticky: true,
+})`
+      )}
+
+      <h2 class="doc-h2" id="mobile">Mobile view</h2>
+      <p>At &lt; 640px the links and action are hidden and replaced with a burger button. The panel opens as an overlay — no layout shift.</p>
+
+      <div class="demo-phone demo-mobile-nav">
+        <div class="demo-phone-statusbar"><div class="demo-phone-pill"></div></div>
+        ${uiNav({
+          logo:     '<strong>MyApp</strong>',
+          logoHref: '/',
+          links:    [{ label: 'Features', href: '#features' }, { label: 'Pricing', href: '#pricing' }, { label: 'FAQ', href: '#faq' }],
+          action:   button({ label: 'Download', size: 'sm' }),
+        })}
+        <div class="demo-phone-content"><p>Tap the burger to open the overlay</p></div>
+      </div>
+
+      <h2 class="doc-h2" id="burger-left">Burger on the left</h2>
+      <p>Set <code>burgerAlign: 'left'</code> to place the burger before the logo — common in app-style layouts.</p>
+
+      <div class="demo-phone demo-mobile-nav">
+        <div class="demo-phone-statusbar"><div class="demo-phone-pill"></div></div>
+        ${uiNav({
+          logo:        '<strong>MyApp</strong>',
+          logoHref:    '/',
+          links:       [{ label: 'Features', href: '#features' }, { label: 'Pricing', href: '#pricing' }, { label: 'FAQ', href: '#faq' }],
+          action:      button({ label: 'Download', size: 'sm' }),
+          burgerAlign: 'left',
+        })}
+        <div class="demo-phone-content"><p>Burger on the left — logo stays right</p></div>
+      </div>
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>logo</code>',     'string (HTML)', '—',     'Raw HTML slot — SVG, img, or text'],
+          ['<code>logoHref</code>', 'string',        "'/'",   ''],
+          ['<code>links</code>',   'array',          '[]',    '<code>{ label, href }[]</code>'],
+          ['<code>action</code>',  'string (HTML)',  '—',     'Raw HTML slot — shown in desktop bar and mobile menu'],
+          ['<code>sticky</code>',      'boolean', 'false',   'position: sticky with backdrop blur'],
+          ['<code>burgerAlign</code>', 'string',  "'right'", "'right' or 'left' — mobile burger position"],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/pricing.js

@@ -0,0 +1,68 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, section } from '../../lib/layout.js'
+import { button, pricing } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/pricing')
+
+export default {
+  route: '/components/pricing',
+  meta: {
+    title: 'Pricing — Pulse Docs',
+    description: 'Pricing component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/pricing',
+    prev,
+    next,
+    name: 'pricing',
+    description: 'Single plan card with a feature list and CTA. Set <code>highlighted: true</code> on the recommended plan — it gets an accent border and a floating <code>badge</code> label.',
+    content: `
+      ${demo(
+        pricing({ name: 'Pro', price: '$9', period: '/month', description: 'For growing teams', features: ['Unlimited pages', 'Priority support', 'Custom domain'], highlighted: true, badge: 'Most popular', action: button({ label: 'Get started', fullWidth: true }) }),
+        `pricing({
+  name:        'Pro',
+  price:       '$9',
+  period:      '/month',
+  description: 'For growing teams',
+  features:    ['Unlimited pages', 'Priority support', 'Custom domain'],
+  highlighted: true,
+  badge:       'Most popular',
+  action:      button({ label: 'Get started', fullWidth: true }),
+})`,
+        { col: true }
+      )}
+
+      ${section('multi-plan', 'Multi-plan layout')}
+      ${demo(
+        `<div class="ui-pricing-grid ui-pricing-grid--cols-3">` +
+          pricing({ name: 'Free', price: '$0', period: '/month', description: 'For personal projects', features: ['3 pages', 'Community support'], action: button({ label: 'Get started', variant: 'secondary', fullWidth: true }) }) +
+          pricing({ name: 'Pro', price: '$9', period: '/month', description: 'For growing teams', features: ['Unlimited pages', 'Priority support', 'Custom domain'], highlighted: true, badge: 'Most popular', action: button({ label: 'Get started', fullWidth: true }) }) +
+          pricing({ name: 'Team', price: '$29', period: '/month', description: 'For large organisations', features: ['Everything in Pro', 'SSO', 'SLA'], action: button({ label: 'Get started', variant: 'secondary', fullWidth: true }) }) +
+        `</div>`,
+        `<div class="ui-pricing-grid ui-pricing-grid--cols-3">
+  \${pricing({ name: 'Free',  price: '$0',  ... })}
+  \${pricing({ name: 'Pro',   price: '$9',  highlighted: true, badge: 'Most popular', ... })}
+  \${pricing({ name: 'Team',  price: '$29', ... })}
+</div>`,
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',        'string',        '—',     ''],
+          ['<code>level</code>',       'number',        '3',     'Heading tag for the plan name (1–6). Visual style is unchanged.'],
+          ['<code>price</code>',       'string',        '—',     'Formatted string — e.g. "$9", "Free"'],
+          ['<code>period</code>',      'string',        '—',     'e.g. "/month", "/year"'],
+          ['<code>description</code>', 'string',        '—',     ''],
+          ['<code>features</code>',    'string[]',      '[]',    'List of feature strings'],
+          ['<code>action</code>',      'string (HTML)', '—',     'Raw HTML slot — typically a button()'],
+          ['<code>highlighted</code>', 'boolean',       'false', 'Accent border + elevated appearance'],
+          ['<code>badge</code>',       'string',        '—',     'Floating label above the card'],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/progress.js

@@ -0,0 +1,102 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { progress, stack } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/progress')
+
+export default {
+  route: '/components/progress',
+  meta: {
+    title: 'Progress — Pulse Docs',
+    description: 'Progress bar component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/progress',
+    prev,
+    next,
+    name: 'progress',
+    description: 'Horizontal progress bar with determinate and indeterminate states. Correct <code>role="progressbar"</code> and ARIA attributes are set automatically.',
+    content: `
+
+      <h2 class="doc-h2" id="default">Default</h2>
+      ${demo(
+        stack({ gap: 'md', content:
+          progress({ value: 25  }) +
+          progress({ value: 50  }) +
+          progress({ value: 75  }) +
+          progress({ value: 100 }),
+        }),
+        `progress({ value: 25  })
+progress({ value: 50  })
+progress({ value: 75  })
+progress({ value: 100 })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="label">With label and value</h2>
+      <p>Set <code>showLabel</code> and <code>showValue</code> to render text above the bar.</p>
+      ${demo(
+        stack({ gap: 'lg', content:
+          progress({ value: 68, label: 'Storage used', showLabel: true, showValue: true }) +
+          progress({ value: 32, label: 'Upload complete', showLabel: true, showValue: true }),
+        }),
+        `progress({ value: 68, label: 'Storage used',    showLabel: true, showValue: true })
+progress({ value: 32, label: 'Upload complete', showLabel: true, showValue: true })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="variants">Variants</h2>
+      ${demo(
+        stack({ gap: 'md', content:
+          progress({ value: 80, variant: 'accent'  }) +
+          progress({ value: 80, variant: 'success' }) +
+          progress({ value: 80, variant: 'warning' }) +
+          progress({ value: 80, variant: 'error'   }),
+        }),
+        `progress({ value: 80, variant: 'accent'  })
+progress({ value: 80, variant: 'success' })
+progress({ value: 80, variant: 'warning' })
+progress({ value: 80, variant: 'error'   })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="sizes">Sizes</h2>
+      ${demo(
+        stack({ gap: 'md', content:
+          progress({ value: 60, size: 'sm' }) +
+          progress({ value: 60, size: 'md' }) +
+          progress({ value: 60, size: 'lg' }),
+        }),
+        `progress({ value: 60, size: 'sm' })
+progress({ value: 60, size: 'md' })
+progress({ value: 60, size: 'lg' })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="indeterminate">Indeterminate</h2>
+      <p>Omit <code>value</code> when the total duration is unknown — the bar animates continuously.</p>
+      ${demo(
+        progress({ label: 'Loading…' }),
+        `progress({ label: 'Loading…' })   // no value = indeterminate`,
+        { col: true }
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>value</code>',      'number',  '—',          'Current value. Omit for indeterminate.'],
+          ['<code>max</code>',        'number',  '100',        ''],
+          ['<code>label</code>',      'string',  '—',          'Sets <code>aria-label</code> and the visible label when <code>showLabel</code> is true'],
+          ['<code>showLabel</code>',  'boolean', 'false',      'Render label text above the bar'],
+          ['<code>showValue</code>',  'boolean', 'false',      'Render percentage above the bar (right-aligned)'],
+          ['<code>variant</code>',    '<code>accent | success | warning | error</code>', '<code>accent</code>', ''],
+          ['<code>size</code>',       '<code>sm | md | lg</code>', '<code>md</code>', '.25rem / .5rem / 1rem'],
+          ['<code>class</code>',      'string',  '—',          ''],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/prose.js

@@ -0,0 +1,111 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout } from '../../lib/layout.js'
+import { prose } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/prose')
+
+const SAMPLE_HTML = `<h2>Why great coffee starts with water</h2>
+<p>Most home baristas obsess over beans and grinders, but water quality is the single biggest variable in your cup. Tap water that is too hard leaves bitter, chalky espresso. Too soft and your shots taste flat and lifeless.</p>
+<h3>The ideal mineral balance</h3>
+<p>Speciality roasters recommend water with a total dissolved solids (TDS) between <strong>75–150 mg/L</strong> and a magnesium content of at least 10 mg/L. Magnesium is the mineral most responsible for extracting the fruity, floral notes from light roasts.</p>
+<h3>What to do if your tap water is off</h3>
+<ul>
+  <li>Use a filter jug — Brita Maxtra+ reduces hardness and chlorine</li>
+  <li>Try third-wave water sachets — add to distilled water for precise control</li>
+  <li>Blend tap with still mineral water to hit the right TDS range</li>
+</ul>
+<blockquote>Water is the ingredient you can control most precisely, yet almost nobody does.</blockquote>
+<p>Once your water is dialled in, even a modest grinder will produce noticeably better results. <a href="#">Read our water guide</a> for a full breakdown by region.</p>`
+
+export default {
+  route: '/components/prose',
+  meta: {
+    title: 'Prose — Pulse Docs',
+    description: 'Typography wrapper for CMS output and rich text content in Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/prose',
+    prev,
+    next,
+    name: 'prose',
+    description: 'Typography wrapper for rich text you don\'t control: CMS output, markdown-rendered HTML, database content, blog posts. Styles all descendant elements — headings, paragraphs, lists, blockquotes, code, tables — using <code>--ui-*</code> tokens. No classes needed on individual elements.',
+    content: `
+
+      <h2 class="doc-h2" id="basic">Basic</h2>
+      <p>Pass any HTML string to <code>content</code>. All elements inside are styled automatically.</p>
+      ${demo(
+        prose({ content: SAMPLE_HTML }),
+        `import { prose } from '@invisibleloop/pulse/ui'
+
+// CMS rich text field — output directly, fully styled
+prose({ content: server.article.bodyHtml })
+
+// Markdown rendered to HTML
+prose({ content: renderMarkdown(server.post.body) })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="size">Size</h2>
+      <p>Scale the base font size for different contexts.</p>
+      ${demo(
+        `<div class="u-flex u-flex-col u-gap-8">
+          <div>
+            <p class="u-text-muted u-text-sm u-mb-3">sm — footnotes, sidebars</p>
+            ${prose({ content: '<p>The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs.</p><ul><li>Smaller text</li><li>Tighter line height</li></ul>', size: 'sm' })}
+          </div>
+          <div>
+            <p class="u-text-muted u-text-sm u-mb-3">base (default)</p>
+            ${prose({ content: '<p>The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs.</p><ul><li>Default size</li><li>Standard line height</li></ul>' })}
+          </div>
+          <div>
+            <p class="u-text-muted u-text-sm u-mb-3">lg — hero intro, feature descriptions</p>
+            ${prose({ content: '<p>The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs.</p><ul><li>Larger text</li><li>More generous spacing</li></ul>', size: 'lg' })}
+          </div>
+        </div>`,
+        `prose({ content: cms.body, size: 'sm' })   // footnotes, sidebars
+prose({ content: cms.body })               // default
+prose({ content: cms.intro, size: 'lg' }) // hero intro`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="elements">Styled elements</h2>
+      <p>Every common HTML element rendered inside <code>prose()</code> is styled using <code>--ui-*</code> tokens:</p>
+      ${demo(
+        prose({ content: `
+          <h2>h2 heading</h2>
+          <h3>h3 heading</h3>
+          <p>A paragraph with <strong>bold</strong>, <em>italic</em>, and <a href="#">a link</a>. Also <code>inline code</code>.</p>
+          <ul><li>Unordered item one</li><li>Unordered item two</li></ul>
+          <ol><li>Ordered item one</li><li>Ordered item two</li></ol>
+          <blockquote>A blockquote with an accent left border.</blockquote>
+          <pre><code>// A code block
+const x = 1 + 2</code></pre>
+          <hr>
+          <p class="u-text-sm u-text-muted">End of content.</p>
+        ` }),
+        `prose({ content: \`
+  <h2>Section heading</h2>
+  <p>Paragraph with <strong>bold</strong> and <a href="#">a link</a>.</p>
+  <ul><li>List item</li></ul>
+  <blockquote>A quote.</blockquote>
+  <pre><code>const x = 1</code></pre>
+\` })`,
+        { col: true }
+      )}
+
+      ${callout('warning', '<strong>Do not escape the content prop.</strong> <code>prose()</code> renders raw HTML — it is designed for trusted server-side content only. Never pass unescaped user input directly. Sanitise CMS output before rendering if your CMS allows arbitrary HTML.')}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>', 'string', '—',                        'Raw HTML string — rendered as-is, not escaped. Use for server-side content only.'],
+          ['<code>size</code>',    '<code>sm | base | lg</code>', '<code>base</code>', 'Base font size scale. <code>sm</code>=0.875rem, <code>base</code>=1rem, <code>lg</code>=1.125rem'],
+          ['<code>class</code>',   'string', '—',                        'Extra classes on the wrapper <code>&lt;div&gt;</code>'],
+        ]
+      )}
+    `,
+  }),
+}