@invisibleloop/pulse 0.1.21

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

@@ -0,0 +1,107 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { heading, card } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/heading')
+
+export default {
+  route: '/components/heading',
+  meta: {
+    title: 'Heading — Pulse Docs',
+    description: 'Styled semantic heading component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/heading',
+    prev,
+    next,
+    name: 'heading',
+    description: 'Styled semantic heading. Renders the correct HTML tag (<code>h1</code>–<code>h6</code>) with consistent typography tokens. Use this instead of raw heading tags so you get the right visual style without remembering utility classes.',
+    content: `
+
+      <h2 class="doc-h2" id="levels">All levels</h2>
+      <p>Each level has a default visual size. The semantic tag and visual size are independent — see <a href="#size-override">size override</a> below.</p>
+      ${demo(
+        [1, 2, 3, 4, 5, 6].map(l => heading({ level: l, text: `Heading level ${l}` })).join(''),
+        `heading({ level: 1, text: 'Page title' })
+heading({ level: 2, text: 'Section title' })
+heading({ level: 3, text: 'Subsection' })
+heading({ level: 4, text: 'Card heading' })
+heading({ level: 5, text: 'Label' })
+heading({ level: 6, text: 'Caption' })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="size-override">Size override</h2>
+      <p>The <code>size</code> prop lets you use a different visual scale than the default for that level. Useful when you need the correct semantic structure for SEO or accessibility but want a different visual weight.</p>
+      ${demo(
+        [
+          heading({ level: 2, text: 'Semantic h2, looks like h4', size: 'xl' }),
+          heading({ level: 3, text: 'Semantic h3, extra large', size: '4xl' }),
+        ].join(''),
+        `// h2 for structure, but visually smaller
+heading({ level: 2, text: 'Related articles', size: 'xl' })
+
+// h3 that needs to be visually prominent
+heading({ level: 3, text: 'Featured', size: '4xl' })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="color">Color</h2>
+      ${demo(
+        [
+          heading({ level: 3, text: 'Default colour' }),
+          heading({ level: 3, text: 'Muted — for secondary labels', color: 'muted' }),
+          heading({ level: 3, text: 'Accent — for highlights', color: 'accent' }),
+        ].join(''),
+        `heading({ level: 3, text: 'Default colour' })
+heading({ level: 3, text: 'Muted — for secondary labels', color: 'muted' })
+heading({ level: 3, text: 'Accent — for highlights', color: 'accent' })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="spacing">Spacing</h2>
+      <p><code>heading()</code> adds no margin. Use <code>u-mt-*</code> and <code>u-mb-*</code> utility classes to control spacing in context.</p>
+      ${demo(
+        card({ content: `
+          ${heading({ level: 2, text: 'Account settings', class: 'u-mb-2' })}
+          <p class="u-text-muted u-text-sm">Manage your profile and preferences.</p>
+        `}),
+        `card({ content: \`
+  \${heading({ level: 2, text: 'Account settings', class: 'u-mb-2' })}
+  <p class="u-text-muted u-text-sm">Manage your profile and preferences.</p>
+\`})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="balance">Preventing orphans</h2>
+      <p>When a heading wraps across lines, the last line can be left with a single short word — an orphan. The <code>balance</code> prop adds <code>text-wrap: balance</code>, which distributes text evenly across all lines so no word is stranded.</p>
+      ${demo(
+        [
+          heading({ level: 2, text: 'The quick brown fox jumps over the lazy dog tonight' }),
+          heading({ level: 2, text: 'The quick brown fox jumps over the lazy dog tonight', balance: true }),
+        ].join('<p class="u-text-muted u-text-sm u-mt-2 u-mb-4">↑ without balance — ↓ with balance: true</p>'),
+        `// Without — last line may have a single word
+heading({ level: 2, text: 'The quick brown fox jumps over the lazy dog tonight' })
+
+// With — text distributed evenly across lines
+heading({ level: 2, text: 'The quick brown fox jumps over the lazy dog tonight', balance: true })`,
+        { col: true }
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>level</code>',   'number (1–6)', '2',               'Controls both the HTML tag and the default visual size'],
+          ['<code>text</code>',    'string',       '—',               'Heading text — escaped automatically'],
+          ['<code>size</code>',    '<code>xs | sm | base | lg | xl | 2xl | 3xl | 4xl</code>', '—', 'Override the visual font size independently of the semantic level. Defaults: h1=4xl, h2=3xl, h3=2xl, h4=xl, h5=base, h6=sm'],
+          ['<code>color</code>',   '<code>default | muted | accent</code>', '<code>default</code>', 'Text colour token'],
+          ['<code>balance</code>', 'boolean', '<code>false</code>', 'Adds <code>text-wrap: balance</code> — prevents orphaned words on the last line when the heading wraps'],
+          ['<code>class</code>',   'string', '—', 'Extra classes — use for spacing utilities such as <code>u-mb-4</code>'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,65 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { hero, appBadge } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/hero')
+
+export default {
+  route: '/components/hero',
+  meta: {
+    title: 'Hero — Pulse Docs',
+    description: 'Hero component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/hero',
+    prev,
+    next,
+    name: 'hero',
+    description: 'Full-width hero section. The <code>actions</code> slot accepts any combination of <code>button()</code> and <code>appBadge()</code> calls. Set <code>align: \'left\'</code> for a split-layout hero. Use <code>size: \'sm\'</code> for inner-page headers that don\'t need the full vertical padding.',
+    content: `
+      ${demo(
+        hero({
+          eyebrow:  'Now available',
+          title:    'The app your phone deserves',
+          subtitle: 'Beautifully simple. Ridiculously fast. Available on iOS and Android.',
+          actions:  appBadge({ store: 'apple', href: '#' }) + ' ' + appBadge({ store: 'google', href: '#' }),
+        }),
+        `hero({
+  eyebrow:  'Now available',
+  title:    'The app your phone deserves',
+  subtitle: 'Beautifully simple. Ridiculously fast.',
+  actions:  appBadge({ store: 'apple',  href: appStoreUrl }) +
+            appBadge({ store: 'google', href: playStoreUrl }),
+})`
+      )}
+
+      ${demo(
+        hero({
+          title:    'Blog',
+          subtitle: 'Thoughts on building for the web.',
+          size:     'sm',
+        }),
+        `hero({
+  title:    'Blog',
+  subtitle: 'Thoughts on building for the web.',
+  size:     'sm',
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>eyebrow</code>',  'string',        '—',         'Small label above the title'],
+          ['<code>title</code>',    'string',        '—',         ''],
+          ['<code>subtitle</code>', 'string',        '—',         ''],
+          ['<code>actions</code>',  'string (HTML)', '—',         'Raw HTML slot'],
+          ['<code>align</code>',    'string',        "'center'",  "'center' or 'left'"],
+          ['<code>size</code>',     'string',        "'md'",      "'md' (5rem padding) or 'sm' (2.5rem top, no bottom) — use sm for inner-page headers"],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,285 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import {
+  button, feature,
+  iconArrowLeft, iconArrowRight, iconArrowUp, iconArrowDown,
+  iconChevronLeft, iconChevronRight, iconChevronUp, iconChevronDown,
+  iconExternalLink, iconMenu, iconX, iconMoreHorizontal, iconMoreVertical,
+  iconCheck, iconCheckCircle, iconXCircle, iconAlertCircle, iconAlertTriangle, iconInfo,
+  iconPlus, iconMinus, iconEdit, iconTrash, iconCopy, iconSearch, iconFilter,
+  iconDownload, iconUpload, iconRefresh, iconSend,
+  iconEye, iconEyeOff, iconLock, iconUnlock, iconSettings, iconBell,
+  iconUser, iconUsers, iconMail, iconMessageSquare,
+  iconHome, iconLogOut, iconLogIn,
+  iconFile, iconImage, iconLink, iconCode, iconCalendar, iconClock, iconBookmark, iconTag,
+  iconPlay, iconPause, iconVolume, iconStar, iconHeart,
+  iconPhone, iconGamepad,
+  iconHandPointUp, iconHandPointDown, iconHandPointLeft, iconHandPointRight,
+  iconGlobe, iconShield, iconZap, iconTrendingUp, iconTrendingDown, iconLoader, iconGrid, iconBug,
+  iconMapPin,
+  iconSun, iconMoon,
+} from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/icons')
+
+// All icons grouped for the visual grid
+const ICONS = [
+  { group: 'Navigation & Direction', icons: [
+    { name: 'iconArrowLeft',      fn: iconArrowLeft      },
+    { name: 'iconArrowRight',     fn: iconArrowRight     },
+    { name: 'iconArrowUp',        fn: iconArrowUp        },
+    { name: 'iconArrowDown',      fn: iconArrowDown      },
+    { name: 'iconChevronLeft',    fn: iconChevronLeft    },
+    { name: 'iconChevronRight',   fn: iconChevronRight   },
+    { name: 'iconChevronUp',      fn: iconChevronUp      },
+    { name: 'iconChevronDown',    fn: iconChevronDown    },
+    { name: 'iconExternalLink',   fn: iconExternalLink   },
+    { name: 'iconMenu',           fn: iconMenu           },
+    { name: 'iconX',              fn: iconX              },
+    { name: 'iconMoreHorizontal', fn: iconMoreHorizontal },
+    { name: 'iconMoreVertical',   fn: iconMoreVertical   },
+  ]},
+  { group: 'Status', icons: [
+    { name: 'iconCheck',         fn: iconCheck         },
+    { name: 'iconCheckCircle',   fn: iconCheckCircle   },
+    { name: 'iconXCircle',       fn: iconXCircle       },
+    { name: 'iconAlertCircle',   fn: iconAlertCircle   },
+    { name: 'iconAlertTriangle', fn: iconAlertTriangle },
+    { name: 'iconInfo',          fn: iconInfo          },
+  ]},
+  { group: 'Actions', icons: [
+    { name: 'iconPlus',     fn: iconPlus     },
+    { name: 'iconMinus',    fn: iconMinus    },
+    { name: 'iconEdit',     fn: iconEdit     },
+    { name: 'iconTrash',    fn: iconTrash    },
+    { name: 'iconCopy',     fn: iconCopy     },
+    { name: 'iconSearch',   fn: iconSearch   },
+    { name: 'iconFilter',   fn: iconFilter   },
+    { name: 'iconDownload', fn: iconDownload },
+    { name: 'iconUpload',   fn: iconUpload   },
+    { name: 'iconRefresh',  fn: iconRefresh  },
+    { name: 'iconSend',     fn: iconSend     },
+  ]},
+  { group: 'UI Controls', icons: [
+    { name: 'iconEye',      fn: iconEye      },
+    { name: 'iconEyeOff',   fn: iconEyeOff   },
+    { name: 'iconLock',     fn: iconLock     },
+    { name: 'iconUnlock',   fn: iconUnlock   },
+    { name: 'iconSettings', fn: iconSettings },
+    { name: 'iconBell',     fn: iconBell     },
+  ]},
+  { group: 'People & Communication', icons: [
+    { name: 'iconUser',          fn: iconUser          },
+    { name: 'iconUsers',         fn: iconUsers         },
+    { name: 'iconMail',          fn: iconMail          },
+    { name: 'iconMessageSquare', fn: iconMessageSquare },
+  ]},
+  { group: 'Navigation & Pages', icons: [
+    { name: 'iconHome',   fn: iconHome   },
+    { name: 'iconMapPin', fn: iconMapPin },
+    { name: 'iconLogOut', fn: iconLogOut },
+    { name: 'iconLogIn',  fn: iconLogIn  },
+  ]},
+  { group: 'Content & Files', icons: [
+    { name: 'iconFile',     fn: iconFile     },
+    { name: 'iconImage',    fn: iconImage    },
+    { name: 'iconLink',     fn: iconLink     },
+    { name: 'iconCode',     fn: iconCode     },
+    { name: 'iconCalendar', fn: iconCalendar },
+    { name: 'iconClock',    fn: iconClock    },
+    { name: 'iconBookmark', fn: iconBookmark },
+    { name: 'iconTag',      fn: iconTag      },
+  ]},
+  { group: 'Media & Rating', icons: [
+    { name: 'iconPlay',  fn: iconPlay  },
+    { name: 'iconPause', fn: iconPause },
+    { name: 'iconVolume', fn: iconVolume },
+    { name: 'iconStar',  fn: iconStar  },
+    { name: 'iconHeart', fn: iconHeart },
+  ]},
+  { group: 'Devices', icons: [
+    { name: 'iconPhone',   fn: iconPhone   },
+    { name: 'iconGamepad', fn: iconGamepad },
+  ]},
+  { group: 'Hand Pointers', icons: [
+    { name: 'iconHandPointUp',    fn: iconHandPointUp    },
+    { name: 'iconHandPointDown',  fn: iconHandPointDown  },
+    { name: 'iconHandPointLeft',  fn: iconHandPointLeft  },
+    { name: 'iconHandPointRight', fn: iconHandPointRight },
+  ]},
+  { group: 'Misc', icons: [
+    { name: 'iconGlobe',        fn: iconGlobe        },
+    { name: 'iconShield',       fn: iconShield       },
+    { name: 'iconZap',          fn: iconZap          },
+    { name: 'iconTrendingUp',   fn: iconTrendingUp   },
+    { name: 'iconTrendingDown', fn: iconTrendingDown },
+    { name: 'iconLoader',       fn: iconLoader       },
+    { name: 'iconGrid',         fn: iconGrid         },
+    { name: 'iconBug',          fn: iconBug          },
+  ]},
+  { group: 'Theme', icons: [
+    { name: 'iconSun',  fn: iconSun  },
+    { name: 'iconMoon', fn: iconMoon },
+  ]},
+]
+
+function iconGrid_() {
+  return ICONS.map(({ group, icons }) => `
+    <h3 class="doc-h3" style="margin-top:2rem">${group}</h3>
+    <div class="icon-grid">
+      ${icons.map(({ name, fn }) => `
+        <div class="icon-grid-item">
+          <div class="icon-grid-preview">${fn({ size: 20 })}</div>
+          <span class="icon-grid-name">${name}</span>
+        </div>
+      `).join('')}
+    </div>
+  `).join('')
+}
+
+export default {
+  route: '/components/icons',
+  meta: {
+    title: 'Icons — Pulse Docs',
+    description: 'Built-in icon set for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/icons',
+    prev,
+    next,
+    name: 'icons',
+    description: '55 curated icons. All are pure functions returning an SVG string — no external library, no DOM dependency, tree-shakeable. Style: 24×24 viewBox, <code>stroke="currentColor"</code>, compatible with any colour token.',
+    content: `
+
+      <h2 class="doc-h2" id="usage">Usage</h2>
+      <p>Import the icon functions you need alongside other components. Call each as a function — optionally pass <code>size</code> and <code>class</code>.</p>
+      ${demo(
+        `<div style="display:flex;gap:1rem;align-items:center;flex-wrap:wrap">` +
+          iconCheck({ size: 20 }) +
+          iconSearch({ size: 20 }) +
+          iconUser({ size: 20 }) +
+          iconStar({ size: 20 }) +
+          iconZap({ size: 20 }) +
+          iconSettings({ size: 20 }) +
+        `</div>`,
+        `import { iconCheck, iconSearch, iconUser } from '@invisibleloop/pulse/ui'
+
+// Default size (16px)
+iconCheck()
+
+// Custom size
+iconSearch({ size: 20 })
+
+// With extra class
+iconUser({ size: 20, class: 'u-text-accent' })`
+      )}
+
+      <h2 class="doc-h2" id="with-button">With button</h2>
+      <p>Pass an icon into the <code>icon</code> prop of <code>button()</code>.</p>
+      ${demo(
+        `<div style="display:flex;gap:.75rem;flex-wrap:wrap;align-items:center">` +
+          button({ label: 'Download', variant: 'primary',   icon: iconDownload({ size: 14 }) }) +
+          button({ label: 'Edit',     variant: 'secondary', icon: iconEdit({ size: 14 }) }) +
+          button({ label: 'Delete',   variant: 'danger',    icon: iconTrash({ size: 14 }) }) +
+          button({ label: 'Search',   variant: 'ghost',     icon: iconSearch({ size: 14 }) }) +
+        `</div>`,
+        `button({ label: 'Download', variant: 'primary',   icon: iconDownload({ size: 14 }) })
+button({ label: 'Edit',     variant: 'secondary', icon: iconEdit({ size: 14 }) })
+button({ label: 'Delete',   variant: 'danger',    icon: iconTrash({ size: 14 }) })
+button({ label: 'Search',   variant: 'ghost',     icon: iconSearch({ size: 14 }) })`
+      )}
+
+      <h2 class="doc-h2" id="with-feature">With feature</h2>
+      <p>Icons compose naturally into the <code>feature()</code> icon slot.</p>
+      ${demo(
+        `<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:1rem">` +
+          feature({ icon: iconZap({ size: 20 }),    title: 'Fast',    description: 'Streaming SSR. No build step.' }) +
+          feature({ icon: iconShield({ size: 20 }), title: 'Secure',  description: 'Security headers on every response.' }) +
+          feature({ icon: iconCode({ size: 20 }),   title: 'Simple',  description: 'Plain JS objects, no JSX.' }) +
+        `</div>`,
+        `feature({ icon: iconZap({ size: 20 }),    title: 'Fast',   description: '...' })
+feature({ icon: iconShield({ size: 20 }), title: 'Secure', description: '...' })
+feature({ icon: iconCode({ size: 20 }),   title: 'Simple', description: '...' })`
+      )}
+
+      <h2 class="doc-h2" id="background">Background</h2>
+      <p>Add <code>bg: 'circle'</code> or <code>bg: 'square'</code> to wrap the icon in a tinted background. Use <code>bgColor</code> to pick the colour — defaults to <code>'accent'</code>.</p>
+
+      <h3 class="doc-h3">Circle</h3>
+      ${demo(
+        `<div style="display:flex;gap:1rem;align-items:center;flex-wrap:wrap">` +
+          iconZap({     size: 20, bg: 'circle', bgColor: 'accent'  }) +
+          iconCheck({   size: 20, bg: 'circle', bgColor: 'success' }) +
+          iconAlertTriangle({ size: 20, bg: 'circle', bgColor: 'warning' }) +
+          iconXCircle({ size: 20, bg: 'circle', bgColor: 'error'   }) +
+          iconSettings({size: 20, bg: 'circle', bgColor: 'muted'   }) +
+        `</div>`,
+        `iconZap({          size: 20, bg: 'circle', bgColor: 'accent'  })
+iconCheck({        size: 20, bg: 'circle', bgColor: 'success' })
+iconAlertTriangle({ size: 20, bg: 'circle', bgColor: 'warning' })
+iconXCircle({      size: 20, bg: 'circle', bgColor: 'error'   })
+iconSettings({     size: 20, bg: 'circle', bgColor: 'muted'   })`
+      )}
+
+      <h3 class="doc-h3">Square (rounded)</h3>
+      ${demo(
+        `<div style="display:flex;gap:1rem;align-items:center;flex-wrap:wrap">` +
+          iconZap({     size: 20, bg: 'square', bgColor: 'accent'  }) +
+          iconCheck({   size: 20, bg: 'square', bgColor: 'success' }) +
+          iconAlertTriangle({ size: 20, bg: 'square', bgColor: 'warning' }) +
+          iconXCircle({ size: 20, bg: 'square', bgColor: 'error'   }) +
+          iconSettings({size: 20, bg: 'square', bgColor: 'muted'   }) +
+        `</div>`,
+        `iconZap({ size: 20, bg: 'square', bgColor: 'accent' })`
+      )}
+
+      <h3 class="doc-h3">With feature()</h3>
+      <p>Pairs naturally with the <code>feature()</code> icon slot at larger sizes.</p>
+      ${demo(
+        `<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:1rem">` +
+          feature({ icon: iconZap({    size: 22, bg: 'square', bgColor: 'accent'  }), title: 'Fast',    description: 'Streaming SSR, zero config.' }) +
+          feature({ icon: iconShield({ size: 22, bg: 'square', bgColor: 'success' }), title: 'Secure',  description: 'Security headers by default.' }) +
+          feature({ icon: iconCode({   size: 22, bg: 'square', bgColor: 'muted'   }), title: 'Simple',  description: 'Plain JS objects, no JSX.' }) +
+        `</div>`,
+        `feature({ icon: iconZap({    size: 22, bg: 'square', bgColor: 'accent'  }), title: 'Fast',   description: '...' })
+feature({ icon: iconShield({ size: 22, bg: 'square', bgColor: 'success' }), title: 'Secure', description: '...' })
+feature({ icon: iconCode({   size: 22, bg: 'square', bgColor: 'muted'   }), title: 'Simple', description: '...' })`
+      )}
+
+      <h2 class="doc-h2" id="colour">Colour</h2>
+      <p>Icons inherit <code>color</code> from their parent — use utility classes or CSS tokens to tint them.</p>
+      ${demo(
+        `<div style="display:flex;gap:1.25rem;align-items:center">` +
+          `<span class="u-text-accent">${iconStar({ size: 20 })}</span>` +
+          `<span class="u-text-green">${iconCheckCircle({ size: 20 })}</span>` +
+          `<span class="u-text-red">${iconXCircle({ size: 20 })}</span>` +
+          `<span class="u-text-yellow">${iconAlertTriangle({ size: 20 })}</span>` +
+          `<span class="u-text-blue">${iconInfo({ size: 20 })}</span>` +
+          `<span class="u-text-muted">${iconClock({ size: 20 })}</span>` +
+        `</div>`,
+        `<span class="u-text-accent">\${iconStar({ size: 20 })}</span>
+<span class="u-text-green">\${iconCheckCircle({ size: 20 })}</span>
+<span class="u-text-red">\${iconXCircle({ size: 20 })}</span>
+<span class="u-text-yellow">\${iconAlertTriangle({ size: 20 })}</span>`
+      )}
+
+      <h2 class="doc-h2" id="all-icons">All icons</h2>
+      <p>Click any icon name to copy the import.</p>
+
+      ${iconGrid_()}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>size</code>',    'number', '16',      'Width and height in px'],
+          ['<code>class</code>',   'string', '—',       'Extra CSS classes (on wrapper when <code>bg</code> is set, otherwise on the SVG)'],
+          ['<code>bg</code>',      'string', '—',       "'circle' · 'square' — wraps the icon in a tinted background"],
+          ['<code>bgColor</code>', 'string', "'accent'", "'accent' · 'success' · 'warning' · 'error' · 'muted'"],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,71 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { uiImage } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/image')
+
+export default {
+  route: '/components/image',
+  meta: {
+    title: 'Image — Pulse Docs',
+    description: 'Responsive image component with optional aspect-ratio crop and caption for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/image',
+    prev,
+    next,
+    name: 'uiImage',
+    description: 'Responsive image component. Supports aspect-ratio cropping with <code>object-fit: cover</code>, optional caption, and rounded corners. Always uses <code>loading="lazy"</code> and <code>decoding="async"</code>.',
+    content: `
+
+      <h2 class="doc-h2" id="ratio">With aspect ratio</h2>
+      <p>Set <code>ratio</code> to constrain the image to a fixed aspect ratio. The image fills the crop area with <code>object-fit: cover</code>.</p>
+      ${demo(
+        uiImage({ src: 'https://picsum.photos/seed/pulse1/800/450', alt: 'Mountain landscape at dusk', ratio: '16/9' }),
+        `uiImage({ src: '/img/photo.jpg', alt: 'Mountain landscape at dusk', ratio: '16/9' })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="rounded">Square and rounded</h2>
+      ${demo(
+        `<div style="max-width:200px;margin:0 auto">${uiImage({ src: 'https://picsum.photos/seed/pulse2/400/400', alt: 'Profile photo', ratio: '1/1', rounded: true })}</div>`,
+        `uiImage({ src: '/img/avatar.jpg', alt: 'Profile photo', ratio: '1/1', rounded: true })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="caption">With caption</h2>
+      ${demo(
+        uiImage({
+          src:     'https://picsum.photos/seed/pulse3/800/600',
+          alt:     'Aerial view of a coastal town',
+          ratio:   '4/3',
+          caption: 'Aerial view of Porto, Portugal. Photo by João Silva.',
+        }),
+        `uiImage({
+  src:     '/img/photo.jpg',
+  alt:     'Aerial view of a coastal town',
+  ratio:   '4/3',
+  caption: 'Aerial view of Porto, Portugal. Photo by João Silva.',
+})`,
+        { col: true }
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>src</code>',      'string',  '—',     'Image source URL'],
+          ['<code>alt</code>',      'string',  '—',     'Alt text — required for accessibility'],
+          ['<code>caption</code>',  'string',  '—',     'Renders a <code>&lt;figcaption&gt;</code> below the image'],
+          ['<code>ratio</code>',    'string',  '—',     'CSS aspect-ratio string e.g. <code>\'16/9\'</code>, <code>\'4/3\'</code>, <code>\'1/1\'</code>. When set, the image fills the crop area with <code>object-fit: cover</code>.'],
+          ['<code>rounded</code>',  'boolean', 'false', 'Applies full border-radius to the image wrap'],
+          ['<code>width</code>',    'number',  '—',     'Sets the <code>width</code> attribute on the <code>&lt;img&gt;</code>'],
+          ['<code>height</code>',   'number',  '—',     'Sets the <code>height</code> attribute on the <code>&lt;img&gt;</code>'],
+          ['<code>class</code>',    'string',  '—',     ''],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/input.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 { input } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/input')
+
+export default {
+  route: '/components/input',
+  meta: {
+    title: 'Input — Pulse Docs',
+    description: 'Input component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/input',
+    prev,
+    next,
+    name: 'input',
+    description: 'The label and error are wired up automatically — <code>for</code>/<code>id</code> and <code>aria-describedby</code> are set from <code>name</code>. You don\'t need to manage ids yourself.',
+    content: `
+      ${demo(
+        input({ name: 'email1', label: 'Email address', type: 'email', placeholder: 'you@example.com' }) +
+        input({ name: 'email2', label: 'Email address', type: 'email', value: 'bad@', error: 'Enter a valid email address' }) +
+        input({ name: 'search', label: 'Search', placeholder: 'Filter by name…', hint: 'Results update as you type' }),
+        `input({ name: 'email',  label: 'Email address', type: 'email', placeholder: 'you@example.com' })
+input({ name: 'email',  label: 'Email address', error: 'Enter a valid email address', value: state.email })
+input({ name: 'search', label: 'Search', placeholder: 'Filter by name…', hint: 'Results update as you type' })`,
+        { col: true }
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',        'string',  '—',    'Also used as id base: <code>field-{name}</code>'],
+          ['<code>label</code>',       'string',  '—',    ''],
+          ['<code>type</code>',        'string',  'text', 'Any valid HTML input type'],
+          ['<code>placeholder</code>', 'string',  '—',    ''],
+          ['<code>value</code>',       'string',  '—',    'Pre-filled value — escaped automatically'],
+          ['<code>error</code>',       'string',  '—',    'Triggers <code>aria-invalid</code> and <code>role="alert"</code>'],
+          ['<code>hint</code>',        'string',  '—',    'Helper text below the input'],
+          ['<code>required</code>',    'boolean', 'false','Adds <code>required</code>, <code>aria-required</code>, and a visual asterisk'],
+          ['<code>disabled</code>',    'boolean', 'false',''],
+          ['<code>id</code>',          'string',  '—',    'Override the generated id'],
+          ['<code>attrs</code>',       'object',  '{}',   'Extra attributes on the <code>&lt;input&gt;</code> element'],
+        ]
+      )}
+    `,
+  }),
+}