@invisibleloop/pulse 0.1.21

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

@@ -0,0 +1,48 @@
+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: {
+    title: 'Accordion — Pulse Docs',
+    description: 'Accordion component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  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', ''],
+        [
+          ['<code>items</code>', 'array', '[]', '<code>{ question: string, answer: string }[]</code>'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,35 @@
+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: {
+    title: 'Alert — Pulse Docs',
+    description: 'Alert component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  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

@@ -0,0 +1,41 @@
+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: {
+    title: 'App Badge — Pulse Docs',
+    description: 'App Badge component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  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', ''],
+        [
+          ['<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

@@ -0,0 +1,35 @@
+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: {
+    title: 'Avatar — Pulse Docs',
+    description: 'Avatar component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  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

@@ -0,0 +1,36 @@
+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: {
+    title: 'Badge — Pulse Docs',
+    description: 'Badge component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  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/banner.js

@@ -0,0 +1,45 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { banner, stack } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/banner')
+
+export default {
+  route: '/components/banner',
+  meta: {
+    title: 'Banner — Pulse Docs',
+    description: 'Banner component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/banner',
+    prev,
+    next,
+    name: 'banner',
+    description: 'Full-width announcement bar. Sits above the nav for promotions and launch announcements. The content slot accepts links and formatted text.',
+    content: `
+      ${demo(
+        stack({
+          gap: 'sm',
+          content:
+            banner({ variant: 'promo',   content: '🎉 Chippy Bird v2.0 is out — <a href="#" style="color:inherit;text-decoration:underline">see what\'s new</a>' }) +
+            banner({ variant: 'info',    content: 'Android support is coming soon. <a href="#" style="color:inherit;text-decoration:underline">Join the waitlist</a>' }) +
+            banner({ variant: 'warning', content: 'Scheduled maintenance Sunday 2–4am UTC.' }),
+        }),
+        `banner({ variant: 'promo', content:
+  '🎉 v2.0 is out — ' + button({ label: "See what's new", variant: 'ghost', size: 'sm', href: '/changelog' })
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>', 'string (HTML)', '—',      'Raw HTML slot'],
+          ['<code>variant</code>', 'string',        "'info'", "'info' · 'promo' · 'warning'"],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,94 @@
+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: {
+    title: 'Breadcrumbs — Pulse Docs',
+    description: 'Accessible breadcrumb navigation component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  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', ''],
+        [
+          ['<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

@@ -0,0 +1,84 @@
+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: {
+    title: 'Button — Pulse Docs',
+    description: 'Button component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  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', ''],
+        [
+          ['<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)'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,225 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { button, card, badge, grid } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/card')
+
+export default {
+  route: '/components/card',
+  meta: {
+    title: 'Card — Pulse Docs',
+    description: 'Card component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/card',
+    prev,
+    next,
+    name: 'card',
+    description: '<code>content</code> and <code>footer</code> are raw HTML slots — they pass through as-is. Wrap user-supplied values in <code>escHtml()</code> before composing them into the string.',
+    content: `
+      ${demo(
+        card({
+          title:   'Recent activity',
+          content: '<p class="u-text-muted u-text-sm" style="margin:0">No activity in the last 7 days.</p>',
+          footer:  button({ label: 'View all', href: '#', variant: 'ghost', size: 'sm' }),
+        }),
+        `card({
+  title:   'Recent activity',
+  content: \`<p class="u-text-muted u-text-sm">No activity in the last 7 days.</p>\`,
+  footer:  button({ label: 'View all', href: '/activity', variant: 'ghost', size: 'sm' }),
+})`
+      )}
+
+      <h2 class="doc-h2" id="image">With image</h2>
+      <p>Use <code>flush</code> to remove body padding, then add an image at the top and restore padding on the text content below it.</p>
+
+      ${demo(
+        card({
+          flush:   true,
+          content: `
+            <div class="u-rounded-md u-overflow-hidden" style="height:180px;background:linear-gradient(135deg,#667eea,#764ba2);display:flex;align-items:center;justify-content:center;">
+              <span style="font-size:3rem">🌄</span>
+            </div>
+            <div class="u-p-5">
+              <p class="u-font-semibold u-mb-2" style="margin-top:0">Mountain retreat</p>
+              <p class="u-text-muted u-text-sm" style="margin:0">A peaceful escape in the highlands. Three nights, all-inclusive.</p>
+            </div>
+          `,
+          footer: button({ label: 'Book now', href: '#', variant: 'primary', size: 'sm' }),
+        }),
+        `card({
+  flush: true,
+  content: \`
+    <div class="u-rounded-md u-overflow-hidden" style="height:180px;background:...">
+      <img src="/img/retreat.jpg" alt="Mountain retreat" style="width:100%;height:100%;object-fit:cover">
+    </div>
+    <div class="u-p-5">
+      <p class="u-font-semibold u-mb-2">Mountain retreat</p>
+      <p class="u-text-muted u-text-sm">A peaceful escape in the highlands.</p>
+    </div>
+  \`,
+  footer: button({ label: 'Book now', href: '/book', variant: 'primary', size: 'sm' }),
+})`
+      )}
+
+      <h2 class="doc-h2" id="badges">With badges</h2>
+      <p>Compose <code>badge()</code> inside <code>content</code> to show status labels or category tags.</p>
+
+      ${demo(
+        card({
+          title:   'API rate limits',
+          content: `
+            <div class="u-flex u-gap-2 u-mb-4">
+              ${badge({ label: 'Production', variant: 'success' })}
+              ${badge({ label: 'v2.1', variant: 'info' })}
+            </div>
+            <p class="u-text-muted u-text-sm" style="margin:0">Requests are capped at 1,000/min per API key. Contact support to increase your limit.</p>
+          `,
+          footer: `
+            <div class="u-flex u-gap-2">
+              ${button({ label: 'View docs', href: '#', variant: 'ghost', size: 'sm' })}
+              ${button({ label: 'Request increase', href: '#', variant: 'secondary', size: 'sm' })}
+            </div>
+          `,
+        }),
+        `card({
+  title:   'API rate limits',
+  content: \`
+    <div class="u-flex u-gap-2 u-mb-4">
+      \${badge({ label: 'Production', variant: 'success' })}
+      \${badge({ label: 'v2.1',       variant: 'info' })}
+    </div>
+    <p class="u-text-muted u-text-sm">Requests are capped at 1,000/min per API key.</p>
+  \`,
+  footer: \`
+    \${button({ label: 'View docs',        href: '/docs',    variant: 'ghost',     size: 'sm' })}
+    \${button({ label: 'Request increase', href: '/contact', variant: 'secondary', size: 'sm' })}
+  \`,
+})`
+      )}
+
+      <h2 class="doc-h2" id="metadata">With metadata row</h2>
+      <p>A flex row inside <code>content</code> works well for author, date, read-time and similar metadata.</p>
+
+      ${demo(
+        card({
+          title:   'Building with Pulse',
+          content: `
+            <p class="u-text-muted u-text-sm u-mb-4">Learn how to scaffold a new project and ship your first spec-driven page in under ten minutes.</p>
+            <div class="u-flex u-gap-3" style="align-items:center;flex-wrap:wrap">
+              <div style="width:28px;height:28px;border-radius:50%;background:linear-gradient(135deg,#667eea,#764ba2);flex-shrink:0"></div>
+              <span class="u-text-sm u-text-muted">Jane Smith</span>
+              <span class="u-text-sm u-text-muted">·</span>
+              <span class="u-text-sm u-text-muted">Mar 15, 2024</span>
+              <span class="u-text-sm u-text-muted u-ml-auto">5 min read</span>
+            </div>
+          `,
+          footer: button({ label: 'Read article →', href: '#', variant: 'ghost', size: 'sm' }),
+        }),
+        `card({
+  title:   'Building with Pulse',
+  content: \`
+    <p class="u-text-muted u-text-sm u-mb-4">Learn how to scaffold a new project...</p>
+    <div class="u-flex u-gap-3" style="align-items:center;flex-wrap:wrap">
+      <img src="/img/avatar.jpg" class="u-rounded-full" style="width:28px;height:28px" alt="">
+      <span class="u-text-sm u-text-muted">Jane Smith</span>
+      <span class="u-text-sm u-text-muted">·</span>
+      <span class="u-text-sm u-text-muted">Mar 15, 2024</span>
+      <span class="u-text-sm u-text-muted u-ml-auto">5 min read</span>
+    </div>
+  \`,
+  footer: button({ label: 'Read article →', href: '/blog/pulse', variant: 'ghost', size: 'sm' }),
+})`
+      )}
+
+      <h2 class="doc-h2" id="stat">Stat / metric card</h2>
+      <p>Cards without a title work well as simple metric tiles. Use <code>grid()</code> to lay multiple cards out side by side.</p>
+
+      ${demo(
+        grid({
+          cols: 3,
+          gap: 'sm',
+          content: [
+            card({ content: `<p class="u-text-muted u-text-sm u-mb-1" style="margin-top:0">Total revenue</p><p class="u-text-3xl u-font-bold" style="margin:0">£48,295</p><p class="u-text-sm u-text-green u-mb-0" style="margin-top:.25rem">↑ 12% this month</p>` }),
+            card({ content: `<p class="u-text-muted u-text-sm u-mb-1" style="margin-top:0">Active users</p><p class="u-text-3xl u-font-bold" style="margin:0">3,842</p><p class="u-text-sm u-text-muted u-mb-0" style="margin-top:.25rem">Across all plans</p>` }),
+            card({ content: `<p class="u-text-muted u-text-sm u-mb-1" style="margin-top:0">Churn rate</p><p class="u-text-3xl u-font-bold" style="margin:0">1.4%</p><p class="u-text-sm u-text-red u-mb-0" style="margin-top:.25rem">↑ 0.2% vs last month</p>` }),
+          ].join(''),
+        }),
+        `grid({
+  cols: 3,
+  gap: 'sm',
+  content: [
+    card({
+      content: \`
+        <p class="u-text-muted u-text-sm u-mb-1">Total revenue</p>
+        <p class="u-text-3xl u-font-bold">£48,295</p>
+        <p class="u-text-sm u-text-green">↑ 12% this month</p>
+      \`,
+    }),
+    card({ ... }),
+    card({ ... }),
+  ].join(''),
+})`
+      )}
+
+      <h2 class="doc-h2" id="grid-inside">Grid inside a card</h2>
+      <p>Components compose freely — pass a <code>grid()</code> into a card's <code>content</code> slot for structured layouts inside a surface.</p>
+
+      ${demo(
+        card({
+          title: 'Plan comparison',
+          content: grid({
+            cols: 3,
+            gap: 'sm',
+            content: [
+              `<div class="u-text-center u-p-2">
+                <p class="u-font-semibold u-mb-1" style="margin-top:0">Starter</p>
+                <p class="u-text-2xl u-font-bold u-mb-1" style="margin:0">£0</p>
+                <p class="u-text-muted u-text-sm" style="margin:0">Up to 3 projects</p>
+              </div>`,
+              `<div class="u-text-center u-p-2" style="border-left:1px solid var(--ui-border);border-right:1px solid var(--ui-border)">
+                <p class="u-font-semibold u-mb-1" style="margin-top:0;color:var(--ui-accent)">Pro</p>
+                <p class="u-text-2xl u-font-bold u-mb-1" style="margin:0">£12</p>
+                <p class="u-text-muted u-text-sm" style="margin:0">Unlimited projects</p>
+              </div>`,
+              `<div class="u-text-center u-p-2">
+                <p class="u-font-semibold u-mb-1" style="margin-top:0">Enterprise</p>
+                <p class="u-text-2xl u-font-bold u-mb-1" style="margin:0">Custom</p>
+                <p class="u-text-muted u-text-sm" style="margin:0">SLA + support</p>
+              </div>`,
+            ].join(''),
+          }),
+          footer: button({ label: 'View full pricing', href: '#', variant: 'ghost', size: 'sm' }),
+        }),
+        `card({
+  title:   'Plan comparison',
+  content: grid({
+    cols: 3,
+    gap: 'sm',
+    content: [
+      \`<div class="u-text-center u-p-2">...</div>\`,
+      \`<div class="u-text-center u-p-2">...</div>\`,
+      \`<div class="u-text-center u-p-2">...</div>\`,
+    ].join(''),
+  }),
+  footer: button({ label: 'View full pricing', href: '/pricing', variant: 'ghost', size: 'sm' }),
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>title</code>',   'string',  '—',     'Escaped automatically'],
+          ['<code>level</code>',   'number',  '3',     'Heading tag for the title (1–6). Visual style is unchanged — use this to keep the document outline correct when the surrounding context already has an h2 or h3.'],
+          ['<code>content</code>', 'string',  '—',     'HTML string — not escaped'],
+          ['<code>footer</code>',  'string',  '—',     'HTML string — not escaped'],
+          ['<code>flush</code>',   'boolean', 'false', 'Removes body padding — useful for full-bleed images or tables'],
+          ['<code>class</code>',   'string',  '—',     ''],
+        ]
+      )}
+    `,
+  }),
+}