@invisibleloop/pulse 0.20.11 → 0.20.20

package/docs/src/pages/caching.js

@@ -1,95 +0,0 @@
-import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/caching')
-
-export default {
-  route: '/caching',
-  meta: {
-    theme:       'light',
-    title: 'Caching — Pulse Docs',
-    description: 'HTTP cache headers, in-process server data caching, and asset caching in Pulse.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/caching',
-    prev,
-    next,
-    content: `
-      ${h1('Caching')}
-      ${lead('Pulse handles asset caching automatically — production bundles are content-hashed and served with immutable cache headers. Page caching is controlled declaratively in the spec: <code>serverTtl</code> for in-process data, <code>cache</code> for HTTP headers. Nothing is cached by default unless you declare it.')}
-
-      ${section('server-ttl', 'serverTtl — in-process data cache')}
-      <p><code>serverTtl</code> is a number of seconds to cache the result of <code>server.data()</code> in memory. Subsequent requests within the TTL window skip the async data fetch entirely and serve the cached result.</p>
-      ${codeBlock(highlight(`export default {
-  route: '/homepage',
-  serverTtl: 60,   // cache server data for 60 seconds
-  server: {
-    data: async () => ({
-      featured: await db.products.getFeatured(),
-      stats:    await analytics.getGlobalStats(),
-    }),
-  },
-}`, 'js'))}
-      ${table(
-        ['Value', 'Behaviour'],
-        [
-          ['<code>undefined</code> (default)', 'No caching — <code>server.data()</code> runs on every request'],
-          ['<code>0</code>', 'No caching (same as undefined)'],
-          ['<code>60</code>', 'Cache for 60 seconds — at most one database hit per minute'],
-          ['<code>3600</code>', 'Cache for 1 hour'],
-        ]
-      )}
-      ${callout('note', 'The in-process cache is per-process and per-route. It is not shared across multiple server instances. Use a distributed cache (Redis, etc.) for cross-instance consistency.')}
-      ${callout('warning', 'In development, setting a long <code>serverTtl</code> can mask stale data. Set it to <code>0</code> or omit it during development, and add it when deploying to production.')}
-
-      ${section('http-cache', 'cache — HTTP response headers')}
-      <p>The <code>cache</code> field controls the <code>Cache-Control</code> header sent with the page HTML response. This tells browsers and CDNs how to cache the response.</p>
-      ${codeBlock(highlight(`export default {
-  route: '/blog/:slug',
-  cache: {
-    public:               true,    // allow CDN/proxy caching
-    maxAge:               300,     // cache for 5 minutes
-    staleWhileRevalidate: 86400,   // serve stale for up to 24 hours while revalidating
-  },
-  // ...
-}`, 'js'))}
-
-      ${section('cache-fields', 'Cache field reference')}
-      ${table(
-        ['Field', 'Type', 'Description'],
-        [
-          ['<code>public</code>', '<code>boolean</code>', 'If true, emits <code>public</code> — allows CDN/proxy caching. Default: <code>private</code>.'],
-          ['<code>maxAge</code>', '<code>number</code>', 'Seconds before the response is considered stale. Emits <code>max-age=N</code>.'],
-          ['<code>staleWhileRevalidate</code>', '<code>number</code>', 'Seconds to serve stale content while revalidating in the background. Emits <code>stale-while-revalidate=N</code>.'],
-        ]
-      )}
-      ${codeBlock(highlight(`// private page — user-specific content
-cache: { public: false, maxAge: 0 }
-// → Cache-Control: private, no-store
-
-// public marketing page — cached at CDN
-cache: { public: true, maxAge: 3600, staleWhileRevalidate: 86400 }
-// → Cache-Control: public, max-age=3600, stale-while-revalidate=86400`, 'js'))}
-
-      ${section('html-default', 'Default HTML caching')}
-      <p>By default, Pulse sends <code>Cache-Control: no-store</code> for all HTML responses. Users always see fresh content — stale HTML is never served from browser or proxy caches unless you explicitly declare a <code>cache</code> policy in the spec.</p>
-
-      ${section('asset-caching', 'Asset caching')}
-      <p>Static assets in <code>public/</code> receive <code>Cache-Control: max-age=3600</code> (one hour).</p>
-      <p>Production bundles in <code>public/dist/</code> receive <code>Cache-Control: public, max-age=31536000, immutable</code> (one year, immutable). This is guaranteed safe because bundle filenames include a content hash — code changes produce a new hash, and browsers fetch the updated file automatically. There is nothing to configure.</p>
-
-      ${section('dev-vs-prod', 'Development vs production')}
-      ${table(
-        ['Resource', 'Development', 'Production'],
-        [
-          ['HTML pages', '<code>no-store</code>', '<code>no-store</code> (or your <code>cache</code> config)'],
-          ['Static assets (<code>/public/*</code>)', '<code>max-age=3600</code>', '<code>max-age=3600</code>'],
-          ['JS bundles (<code>/dist/*</code>)', 'N/A (source files served directly)', '<code>immutable, max-age=31536000</code>'],
-        ]
-      )}
-      ${callout('tip', 'For maximum performance, combine <code>serverTtl</code> for expensive database queries with a short <code>cache.maxAge</code> and a generous <code>cache.staleWhileRevalidate</code>. Users get fast responses; data stays reasonably fresh.')}
-    `,
-  }),
-}

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

@@ -1,48 +0,0 @@
-import { renderComponentPage, demo } from '../../lib/component-page.js'
-import { prevNext } from '../../lib/nav.js'
-import { table } from '../../lib/layout.js'
-import { accordion } from '../../../../src/ui/index.js'
-
-const { prev, next } = prevNext('/components/accordion')
-
-export default {
-  route: '/components/accordion',
-  meta: {
-    theme:       'light',
-    title: 'Accordion — Pulse Docs',
-    description: 'Accordion component for Pulse UI.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/accordion',
-    prev,
-    next,
-    name: 'accordion',
-    description: 'Collapsible FAQ items built on native <code>&lt;details&gt;</code>/<code>&lt;summary&gt;</code> — no JavaScript required. The open/close animation is handled entirely by the browser.',
-    content: `
-      ${demo(
-        accordion({
-          items: [
-            { question: 'Is there a free plan?', answer: 'Yes — the free plan includes up to 3 pages and community support, with no credit card required.' },
-            { question: 'Can I cancel anytime?', answer: 'Absolutely. There are no contracts or lock-in periods. Cancel from your account settings at any time.' },
-            { question: 'Does it work on older devices?', answer: 'The app supports iOS 14+ and Android 8+, covering over 97% of active devices.' },
-          ],
-        }),
-        `accordion({
-  items: [
-    { question: 'Is there a free plan?',     answer: 'Yes — up to 3 pages, no card required.' },
-    { question: 'Can I cancel anytime?',     answer: 'No contracts. Cancel from your account.' },
-    { question: 'Works on older devices?',   answer: 'iOS 14+ and Android 8+.' },
-  ],
-})`
-      )}
-
-      ${table(
-        ['Prop', 'Type', 'Default', 'Description'],
-        [
-          ['<code>items</code>', 'array', '[]', '<code>{ question: string, answer: string }[]</code>'],
-        ]
-      )}
-    `,
-  }),
-}

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

@@ -1,35 +0,0 @@
-import { renderComponentPage, demo } from '../../lib/component-page.js'
-import { prevNext } from '../../lib/nav.js'
-import { alert } from '../../../../src/ui/index.js'
-
-const { prev, next } = prevNext('/components/alert')
-
-export default {
-  route: '/components/alert',
-  meta: {
-    theme:       'light',
-    title: 'Alert — Pulse Docs',
-    description: 'Alert component for Pulse UI.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/alert',
-    prev,
-    next,
-    name: 'alert',
-    description: '<code>error</code> and <code>warning</code> use <code>role="alert"</code> — screen readers announce them immediately. <code>info</code> and <code>success</code> use <code>role="status"</code> for a polite announcement.',
-    content: `
-      ${demo(
-        alert({ variant: 'info',    content: 'Your account is pending email verification.' }) +
-        alert({ variant: 'success', title: 'Saved',   content: 'Your changes have been saved.' }) +
-        alert({ variant: 'warning', title: 'Heads up', content: 'This action cannot be undone.' }) +
-        alert({ variant: 'error',   title: 'Failed',   content: 'Something went wrong. Please try again.' }),
-        `alert({ variant: 'info',    content: 'Your account is pending email verification.' })
-alert({ variant: 'success', title: 'Saved',    content: 'Your changes have been saved.' })
-alert({ variant: 'warning', title: 'Heads up', content: 'This action cannot be undone.' })
-alert({ variant: 'error',   title: 'Failed',   content: escHtml(server.error) })`,
-        { col: true }
-      )}
-    `,
-  }),
-}

package/docs/src/pages/components/app-badge.js

@@ -1,41 +0,0 @@
-import { renderComponentPage, demo } from '../../lib/component-page.js'
-import { prevNext } from '../../lib/nav.js'
-import { table } from '../../lib/layout.js'
-import { appBadge } from '../../../../src/ui/index.js'
-
-const { prev, next } = prevNext('/components/app-badge')
-
-export default {
-  route: '/components/app-badge',
-  meta: {
-    theme:       'light',
-    title: 'App Badge — Pulse Docs',
-    description: 'App Badge component for Pulse UI.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/app-badge',
-    prev,
-    next,
-    name: 'appBadge',
-    description: 'App Store and Google Play download buttons. Designed to sit in a <code>hero()</code> actions slot, or anywhere a download CTA is needed.',
-    content: `
-      ${demo(
-        `<div style="display:flex;gap:.75rem;flex-wrap:wrap">` +
-          appBadge({ store: 'apple',  href: '#' }) +
-          appBadge({ store: 'google', href: '#' }) +
-        `</div>`,
-        `appBadge({ store: 'apple',  href: appStoreUrl })
-appBadge({ store: 'google', href: playStoreUrl })`
-      )}
-
-      ${table(
-        ['Prop', 'Type', 'Default', 'Description'],
-        [
-          ['<code>store</code>', 'string', "'apple'", "'apple' or 'google'"],
-          ['<code>href</code>',  'string', "'#'",     'Link to the app store listing'],
-        ]
-      )}
-    `,
-  }),
-}

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

@@ -1,35 +0,0 @@
-import { renderComponentPage, demo } from '../../lib/component-page.js'
-import { prevNext } from '../../lib/nav.js'
-import { avatar } from '../../../../src/ui/index.js'
-
-const { prev, next } = prevNext('/components/avatar')
-
-export default {
-  route: '/components/avatar',
-  meta: {
-    theme:       'light',
-    title: 'Avatar — Pulse Docs',
-    description: 'Avatar component for Pulse UI.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/avatar',
-    prev,
-    next,
-    name: 'avatar',
-    description: 'When <code>src</code> is set, renders an <code>&lt;img&gt;</code> with <code>loading="lazy"</code>. Without <code>src</code>, shows initials derived from <code>alt</code>.',
-    content: `
-      ${demo(
-        `<div style="display:flex;gap:1rem;align-items:center">` +
-          avatar({ alt: 'Alice Smith', size: 'sm' }) +
-          avatar({ alt: 'Bob Jones',   size: 'md' }) +
-          avatar({ alt: 'Carol White', size: 'lg' }) +
-          avatar({ alt: 'Dan Brown',   size: 'xl' }) +
-        `</div>`,
-        `avatar({ src: user.avatarUrl, alt: user.name, size: 'md' })
-avatar({ alt: 'Alice Smith' })          // renders initials "AS"
-avatar({ alt: 'Alice', initials: 'A' }) // explicit initials`
-      )}
-    `,
-  }),
-}

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

@@ -1,36 +0,0 @@
-import { renderComponentPage, demo } from '../../lib/component-page.js'
-import { prevNext } from '../../lib/nav.js'
-import { badge } from '../../../../src/ui/index.js'
-
-const { prev, next } = prevNext('/components/badge')
-
-export default {
-  route: '/components/badge',
-  meta: {
-    theme:       'light',
-    title: 'Badge — Pulse Docs',
-    description: 'Badge component for Pulse UI.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/badge',
-    prev,
-    next,
-    name: 'badge',
-    description: 'Inline status and label indicator. Five semantic variants cover the most common states.',
-    content: `
-      ${demo(
-        badge({ label: 'Default', variant: 'default' }) + ' ' +
-        badge({ label: 'Info',    variant: 'info'    }) + ' ' +
-        badge({ label: 'Success', variant: 'success' }) + ' ' +
-        badge({ label: 'Warning', variant: 'warning' }) + ' ' +
-        badge({ label: 'Error',   variant: 'error'   }),
-        `badge({ label: 'Default', variant: 'default' })
-badge({ label: 'Info',    variant: 'info'    })
-badge({ label: 'Success', variant: 'success' })
-badge({ label: 'Warning', variant: 'warning' })
-badge({ label: 'Error',   variant: 'error'   })`
-      )}
-    `,
-  }),
-}

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

@@ -1,94 +0,0 @@
-import { renderComponentPage, demo } from '../../lib/component-page.js'
-import { prevNext } from '../../lib/nav.js'
-import { table } from '../../lib/layout.js'
-import { breadcrumbs } from '../../../../src/ui/index.js'
-
-const { prev, next } = prevNext('/components/breadcrumbs')
-
-export default {
-  route: '/components/breadcrumbs',
-  meta: {
-    theme:       'light',
-    title: 'Breadcrumbs — Pulse Docs',
-    description: 'Accessible breadcrumb navigation component for Pulse UI.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/breadcrumbs',
-    prev,
-    next,
-    name: 'breadcrumbs',
-    description: 'Accessible breadcrumb navigation. The current page item renders as a <code>&lt;span&gt;</code> with <code>aria-current="page"</code>; all preceding items render as links.',
-    content: `
-
-      <h2 class="doc-h2" id="basic">Basic</h2>
-      ${demo(
-        breadcrumbs({
-          items: [
-            { label: 'Home',     href: '/' },
-            { label: 'Products', href: '/products' },
-            { label: 'Sneakers' },
-          ],
-        }),
-        `breadcrumbs({
-  items: [
-    { label: 'Home',     href: '/' },
-    { label: 'Products', href: '/products' },
-    { label: 'Sneakers' },
-  ],
-})`
-      )}
-
-      <h2 class="doc-h2" id="longer">Longer trail</h2>
-      ${demo(
-        breadcrumbs({
-          items: [
-            { label: 'Home',       href: '/' },
-            { label: 'Shop',       href: '/shop' },
-            { label: 'Footwear',   href: '/shop/footwear' },
-            { label: 'Sneakers',   href: '/shop/footwear/sneakers' },
-            { label: 'Air Max 90' },
-          ],
-        }),
-        `breadcrumbs({
-  items: [
-    { label: 'Home',     href: '/' },
-    { label: 'Shop',     href: '/shop' },
-    { label: 'Footwear', href: '/shop/footwear' },
-    { label: 'Sneakers', href: '/shop/footwear/sneakers' },
-    { label: 'Air Max 90' },
-  ],
-})`
-      )}
-
-      <h2 class="doc-h2" id="separator">Custom separator</h2>
-      ${demo(
-        breadcrumbs({
-          separator: '›',
-          items: [
-            { label: 'Docs',      href: '/docs' },
-            { label: 'Components', href: '/docs/components' },
-            { label: 'Breadcrumbs' },
-          ],
-        }),
-        `breadcrumbs({
-  separator: '›',
-  items: [
-    { label: 'Docs',       href: '/docs' },
-    { label: 'Components', href: '/docs/components' },
-    { label: 'Breadcrumbs' },
-  ],
-})`
-      )}
-
-      ${table(
-        ['Prop', 'Type', 'Default', 'Description'],
-        [
-          ['<code>items</code>',     'array',  '[]',  'Array of <code>{ label, href }</code>. The last item should have no <code>href</code> — it becomes the current page.'],
-          ['<code>separator</code>', 'string', "'/'", 'Character rendered between items'],
-          ['<code>class</code>',     'string', '—',   ''],
-        ]
-      )}
-    `,
-  }),
-}

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

@@ -1,84 +0,0 @@
-import { renderComponentPage, demo } from '../../lib/component-page.js'
-import { prevNext } from '../../lib/nav.js'
-import { table } from '../../lib/layout.js'
-import { button } from '../../../../src/ui/index.js'
-import { iconArrowRight, iconDownload, iconPlus, iconSend } from '../../../../src/ui/icons.js'
-
-const { prev, next } = prevNext('/components/button')
-
-export default {
-  route: '/components/button',
-  meta: {
-    theme:       'light',
-    title: 'Button — Pulse Docs',
-    description: 'Button component for Pulse UI.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/button',
-    prev,
-    next,
-    name: 'button',
-    description: 'Renders as <code>&lt;button&gt;</code> by default. Pass <code>href</code> to get an <code>&lt;a&gt;</code> that looks identical. All four variants are shown below.',
-    content: `
-      ${demo(
-        button({ label: 'Primary',   variant: 'primary'   }) +
-        button({ label: 'Secondary', variant: 'secondary' }) +
-        button({ label: 'Ghost',     variant: 'ghost'     }) +
-        button({ label: 'Danger',    variant: 'danger'    }),
-        `button({ label: 'Primary',   variant: 'primary'   })
-button({ label: 'Secondary', variant: 'secondary' })
-button({ label: 'Ghost',     variant: 'ghost'     })
-button({ label: 'Danger',    variant: 'danger'    })`
-      )}
-
-      ${demo(
-        button({ label: 'Small',  size: 'sm' }) +
-        button({ label: 'Medium', size: 'md' }) +
-        button({ label: 'Large',  size: 'lg' }),
-        `button({ label: 'Small',  size: 'sm' })
-button({ label: 'Medium', size: 'md' })
-button({ label: 'Large',  size: 'lg' })`
-      )}
-
-      ${demo(
-        button({ label: 'Download', icon: iconDownload({ size: 14 }) }) +
-        button({ label: 'New item', icon: iconPlus({ size: 14 }), variant: 'secondary' }) +
-        button({ label: 'Continue', iconAfter: iconArrowRight({ size: 14 }) }) +
-        button({ label: 'Send',     iconAfter: iconSend({ size: 14 }), variant: 'ghost' }),
-        `import { iconDownload, iconPlus, iconArrowRight, iconSend } from '@invisibleloop/pulse/ui'
-
-button({ label: 'Download', icon: iconDownload({ size: 14 }) })
-button({ label: 'New item', icon: iconPlus({ size: 14 }),           variant: 'secondary' })
-button({ label: 'Continue', iconAfter: iconArrowRight({ size: 14 }) })
-button({ label: 'Send',     iconAfter: iconSend({ size: 14 }),      variant: 'ghost' })`
-      )}
-
-      ${demo(
-        button({ label: 'Disabled', disabled: true }) +
-        button({ label: 'Link', href: '/docs' }) +
-        button({ label: 'Submit', type: 'submit', variant: 'primary' }),
-        `button({ label: 'Disabled', disabled: true })
-button({ label: 'Link',    href: '/docs'   })
-button({ label: 'Submit',  type: 'submit', variant: 'primary' })`
-      )}
-
-      ${table(
-        ['Prop', 'Type', 'Default', 'Description'],
-        [
-          ['<code>label</code>',    'string',  '—',         'Visible text'],
-          ['<code>variant</code>',  'string',  'primary',   'primary · secondary · ghost · danger'],
-          ['<code>size</code>',     'string',  'md',        'sm · md · lg'],
-          ['<code>href</code>',     'string',  '—',         'Renders <code>&lt;a&gt;</code> instead of <code>&lt;button&gt;</code>'],
-          ['<code>disabled</code>', 'boolean', 'false',     ''],
-          ['<code>type</code>',     'string',  'button',    'button · submit · reset'],
-          ['<code>icon</code>',     'string',  '—',         'SVG HTML prepended inside'],
-          ['<code>iconAfter</code>','string',  '—',         'SVG HTML appended inside'],
-          ['<code>fullWidth</code>','boolean', 'false',     ''],
-          ['<code>class</code>',    'string',  '—',         'Extra classes appended to the element'],
-          ['<code>attrs</code>',    'object',  '{}',        'Extra HTML attributes (button only)'],
-        ]
-      )}
-    `,
-  }),
-}