@invisibleloop/pulse 0.1.21

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

@@ -0,0 +1,72 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { carousel } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/carousel')
+
+function slide(bg, label) {
+  return `<div style="height:220px;display:flex;align-items:center;justify-content:center;background:${bg};border-radius:10px;font-size:1.1rem;font-weight:700;color:var(--ui-text)">${label}</div>`
+}
+
+export default {
+  route: '/components/carousel',
+  meta: {
+    title: 'Carousel — Pulse Docs',
+    description: 'Carousel / slider component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/carousel',
+    prev,
+    next,
+    name: 'carousel',
+    description: 'CSS scroll-snap carousel with optional prev/next arrows and dot navigation. Touch / swipe friendly out of the box. Requires <code>pulse-ui.js</code> for button and dot interactivity.',
+    content: `
+      ${demo(
+        carousel({
+          slides: [
+            slide('var(--ui-surface-2)', 'Slide 1'),
+            slide('var(--ui-surface)',   'Slide 2'),
+            slide('var(--ui-surface-2)', 'Slide 3'),
+          ],
+        }),
+        `carousel({
+  slides: [
+    \`<div class="slide">Slide 1</div>\`,
+    \`<div class="slide">Slide 2</div>\`,
+    \`<div class="slide">Slide 3</div>\`,
+  ],
+})`
+      )}
+
+      <h3 class="doc-h3" id="arrows-dots"><a href="#arrows-dots" class="heading-anchor">Arrows and dots</a></h3>
+      ${demo(
+        carousel({
+          arrows: true,
+          dots:   false,
+          slides: [
+            slide('var(--ui-surface-2)', 'Arrows only — Slide 1'),
+            slide('var(--ui-surface)',   'Arrows only — Slide 2'),
+          ],
+        }),
+        `carousel({
+  slides: [ /* ... */ ],
+  arrows: true,
+  dots:   false,   // hide dot navigation
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>slides</code>', 'string[] (HTML)',  '[]',             'Array of raw HTML strings — one per slide'],
+          ['<code>arrows</code>', 'boolean',           '<code>true</code>',  'Show prev/next arrow buttons'],
+          ['<code>dots</code>',   'boolean',           '<code>true</code>',  'Show dot navigation (hidden when only one slide)'],
+          ['<code>class</code>',  'string',            '—',              ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,278 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { barChart, lineChart, donutChart, sparkline, stat, card, grid } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/charts')
+
+// Shared sample data
+const monthly = [
+  { label: 'Jan', value: 42 },
+  { label: 'Feb', value: 78 },
+  { label: 'Mar', value: 55 },
+  { label: 'Apr', value: 91 },
+  { label: 'May', value: 63 },
+  { label: 'Jun', value: 84 },
+]
+
+const traffic = [
+  { label: 'Mon', value: 1200 },
+  { label: 'Tue', value: 1850 },
+  { label: 'Wed', value: 1540 },
+  { label: 'Thu', value: 2100 },
+  { label: 'Fri', value: 1760 },
+  { label: 'Sat', value: 890  },
+  { label: 'Sun', value: 720  },
+]
+
+export default {
+  route: '/components/charts',
+  meta: {
+    title: 'Charts — Pulse Docs',
+    description: 'Server-rendered SVG charts for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/charts',
+    prev,
+    next,
+    name: 'charts',
+    description: 'Server-rendered SVG charts — no JavaScript, no external library. Pure functions that return SVG strings, composable with any layout component. All colours use design tokens and respond to light/dark theme.',
+    content: `
+
+      <h2 class="doc-h2" id="bar">Bar chart</h2>
+      <p>Vertical bars with optional grid, value labels, and a zero baseline. All colour variants available.</p>
+      ${demo(
+        barChart({ data: monthly, color: 'accent' }),
+        `barChart({
+  data: [
+    { label: 'Jan', value: 42 },
+    { label: 'Feb', value: 78 },
+    { label: 'Mar', value: 55 },
+    { label: 'Apr', value: 91 },
+    { label: 'May', value: 63 },
+    { label: 'Jun', value: 84 },
+  ],
+  color: 'accent',
+})`
+      )}
+
+      <h3 class="doc-h3">With value labels</h3>
+      ${demo(
+        barChart({ data: monthly, color: 'success', showValues: true }),
+        `barChart({ data, color: 'success', showValues: true })`
+      )}
+
+      <h3 class="doc-h3">Large dataset with tight gap</h3>
+      ${demo(
+        barChart({ data: traffic, color: 'blue', gap: 0.15 }),
+        `barChart({ data: traffic, color: 'blue', gap: 0.15 })`
+      )}
+
+      <h3 class="doc-h3">Negative values</h3>
+      ${demo(
+        barChart({
+          data: [
+            { label: 'Q1', value:  24 },
+            { label: 'Q2', value: -8  },
+            { label: 'Q3', value:  41 },
+            { label: 'Q4', value: -15 },
+          ],
+          color: 'warning',
+          showValues: true,
+        }),
+        `barChart({
+  data: [
+    { label: 'Q1', value:  24 },
+    { label: 'Q2', value: -8  },
+    { label: 'Q3', value:  41 },
+    { label: 'Q4', value: -15 },
+  ],
+  color: 'warning',
+  showValues: true,
+})`
+      )}
+
+      <h2 class="doc-h2" id="line">Line chart</h2>
+      <p>Connected data points with optional dots, area fill, and grid lines.</p>
+      ${demo(
+        lineChart({ data: monthly, color: 'accent' }),
+        `lineChart({
+  data: [
+    { label: 'Jan', value: 42 },
+    ...
+  ],
+  color: 'accent',
+})`
+      )}
+
+      <h3 class="doc-h3">With area fill</h3>
+      ${demo(
+        lineChart({ data: monthly, color: 'accent', area: true }),
+        `lineChart({ data, color: 'accent', area: true })`
+      )}
+
+      <h3 class="doc-h3">No dots, area fill, success colour</h3>
+      ${demo(
+        lineChart({ data: traffic, color: 'success', area: true, showDots: false }),
+        `lineChart({ data, color: 'success', area: true, showDots: false })`
+      )}
+
+      <h2 class="doc-h2" id="donut">Donut chart</h2>
+      <p>Ring chart with multiple segments. Each item can override its colour. Pass <code>label</code> and <code>sublabel</code> for a centred annotation.</p>
+      ${demo(
+        `<div style="display:flex;justify-content:center">` +
+        donutChart({
+          label: '73%',
+          sublabel: 'satisfied',
+          data: [
+            { label: 'Satisfied',   value: 73, color: 'success' },
+            { label: 'Neutral',     value: 18, color: 'muted'   },
+            { label: 'Unsatisfied', value: 9,  color: 'error'   },
+          ],
+        }) + `</div>`,
+        `donutChart({
+  label:    '73%',
+  sublabel: 'satisfied',
+  data: [
+    { label: 'Satisfied',   value: 73, color: 'success' },
+    { label: 'Neutral',     value: 18, color: 'muted'   },
+    { label: 'Unsatisfied', value: 9,  color: 'error'   },
+  ],
+})`
+      )}
+
+      <h3 class="doc-h3">Thinner ring</h3>
+      ${demo(
+        `<div style="display:flex;justify-content:center">` +
+        donutChart({
+          size: 180,
+          thickness: 22,
+          label: '4',
+          sublabel: 'segments',
+          data: [
+            { label: 'A', value: 40, color: 'accent'  },
+            { label: 'B', value: 30, color: 'blue'    },
+            { label: 'C', value: 20, color: 'success' },
+            { label: 'D', value: 10, color: 'warning' },
+          ],
+        }) + `</div>`,
+        `donutChart({
+  size: 180, thickness: 22,
+  label: '4', sublabel: 'segments',
+  data: [
+    { label: 'A', value: 40, color: 'accent'  },
+    { label: 'B', value: 30, color: 'blue'    },
+    { label: 'C', value: 20, color: 'success' },
+    { label: 'D', value: 10, color: 'warning' },
+  ],
+})`
+      )}
+
+      <h2 class="doc-h2" id="sparkline">Sparkline</h2>
+      <p>Minimal inline trend line — pass a plain array of numbers. Designed to sit alongside <code>stat()</code> tiles or inside table cells.</p>
+      ${demo(
+        `<div style="display:flex;gap:.75rem;align-items:center;flex-wrap:wrap">` +
+          sparkline({ data: [12,18,14,22,19,28,24,31], color: 'accent',  area: true  }) +
+          sparkline({ data: [31,24,28,19,22,14,18,12], color: 'error',   area: true  }) +
+          sparkline({ data: [12,18,14,22,19,28,24,31], color: 'success', area: false }) +
+        `</div>`,
+        `sparkline({ data: [12,18,14,22,19,28,24,31], color: 'accent', area: true })
+sparkline({ data: [31,24,28,19,22,14,18,12], color: 'error',  area: true })`
+      )}
+
+      <h2 class="doc-h2" id="composition">Composition</h2>
+      <p>Charts compose with <code>card()</code>, <code>stat()</code>, <code>grid()</code> — drop any chart into any content slot.</p>
+      ${demo(
+        grid({
+          cols: 2,
+          gap: 'md',
+          content:
+            card({
+              title: 'Monthly signups',
+              content: barChart({ data: monthly, color: 'accent', height: 180 }),
+            }) +
+            card({
+              title: 'Daily traffic',
+              content: lineChart({ data: traffic, color: 'blue', area: true, height: 180 }),
+            }),
+        }),
+        `grid({
+  cols: 2,
+  content:
+    card({ title: 'Monthly signups', content: barChart({ data, height: 180 }) }) +
+    card({ title: 'Daily traffic',   content: lineChart({ data, color: 'blue', area: true, height: 180 }) }),
+})`
+      )}
+
+      <h3 class="doc-h3">Sparkline in stat tiles</h3>
+      ${demo(
+        grid({
+          cols: 3,
+          gap: 'md',
+          content:
+            card({ content: stat({ label: 'Revenue', value: '$18.2k', change: '+12%', trend: 'up' }) + `<div style="margin-top:.75rem">${sparkline({ data: [8,11,9,14,12,16,15,18], width: '100%', color: 'success', area: true })}</div>` }) +
+            card({ content: stat({ label: 'Users', value: '4,821', change: '+8.4%', trend: 'up' }) + `<div style="margin-top:.75rem">${sparkline({ data: [22,28,24,31,27,34,30,38], width: '100%', color: 'accent', area: true })}</div>` }) +
+            card({ content: stat({ label: 'Churn', value: '2.1%', change: '−0.3%', trend: 'down' }) + `<div style="margin-top:.75rem">${sparkline({ data: [8,6,7,5,6,4,5,3], width: '100%', color: 'error', area: true })}</div>` }),
+        }),
+        `card({
+  content: stat({ label: 'Revenue', value: '$18.2k', change: '+12%', trend: 'up' }) +
+    \`<div style="margin-top:.75rem">\${sparkline({ data, color: 'success', area: true })}</div>\`,
+})`
+      )}
+
+      <h2 class="doc-h2" id="props">Props</h2>
+
+      <h3 class="doc-h3">barChart()</h3>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>data</code>',       'array',   '—',       '<code>{ label, value }[]</code>'],
+          ['<code>height</code>',     'number',  '220',     'SVG height in px'],
+          ['<code>color</code>',      'string',  "'accent'", 'accent · success · warning · error · blue · muted'],
+          ['<code>showValues</code>', 'boolean', 'false',   'Value labels above each bar'],
+          ['<code>showGrid</code>',   'boolean', 'true',    'Horizontal grid lines'],
+          ['<code>gap</code>',        'number',  '0.25',    'Gap between bars as fraction 0–0.9'],
+        ]
+      )}
+
+      <h3 class="doc-h3" style="margin-top:2rem">lineChart()</h3>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>data</code>',      'array',   '—',        '<code>{ label, value }[]</code>'],
+          ['<code>height</code>',    'number',  '220',      'SVG height in px'],
+          ['<code>color</code>',     'string',  "'accent'", 'accent · success · warning · error · blue · muted'],
+          ['<code>area</code>',      'boolean', 'false',    'Fill area under the line'],
+          ['<code>showDots</code>',  'boolean', 'true',     'Dots at each data point'],
+          ['<code>showGrid</code>',  'boolean', 'true',     'Horizontal grid lines'],
+        ]
+      )}
+
+      <h3 class="doc-h3" style="margin-top:2rem">donutChart()</h3>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>data</code>',      'array',  '—',    '<code>{ label, value, color? }[]</code> — color per segment'],
+          ['<code>size</code>',      'number', '200',  'Diameter in px'],
+          ['<code>thickness</code>', 'number', '40',   'Ring thickness in px'],
+          ['<code>label</code>',     'string', '—',    'Large centre text'],
+          ['<code>sublabel</code>',  'string', '—',    'Smaller text below centre label'],
+        ]
+      )}
+
+      <h3 class="doc-h3" style="margin-top:2rem">sparkline()</h3>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>data</code>',   'number[]', '—',        'Plain array of numbers'],
+          ['<code>width</code>',  'number',   '80',       'SVG width in px'],
+          ['<code>height</code>', 'number',   '32',       'SVG height in px'],
+          ['<code>color</code>',  'string',   "'accent'", 'accent · success · warning · error · blue · muted'],
+          ['<code>area</code>',   'boolean',  'false',    'Fill area under the line'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,129 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext }                   from '../../lib/nav.js'
+import { table, callout }             from '../../lib/layout.js'
+import { checkbox, fieldset }         from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/checkbox')
+
+export default {
+  route: '/components/checkbox',
+  meta: {
+    title:       'Checkbox — Pulse Docs',
+    description: 'Custom-styled checkbox component for Pulse UI.',
+    styles:      ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/checkbox',
+    prev,
+    next,
+    name: 'checkbox',
+    description: 'Custom-styled checkbox with animated check mark, full keyboard and screen-reader support. Pairs with <a href="/components/fieldset">fieldset</a> for labelled groups.',
+    content: `
+
+      <h2 class="doc-h2" id="basic">Basic</h2>
+      <p>Pass <code>label</code> for the visible text. The <code>id</code> is auto-generated from <code>name</code> and <code>value</code>.</p>
+      ${demo(
+        checkbox({ name: 'agree', label: 'I agree to the terms' }),
+        `checkbox({ name: 'agree', label: 'I agree to the terms' })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="checked">Checked</h2>
+      ${demo(
+        checkbox({ name: 'newsletter', label: 'Send me updates', checked: true }),
+        `checkbox({ name: 'newsletter', label: 'Send me updates', checked: state.newsletter })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="hint">Hint</h2>
+      <p>A <code>hint</code> string renders below the label as supporting copy.</p>
+      ${demo(
+        checkbox({ name: 'marketing', label: 'Marketing emails', hint: 'Product news and tips. Unsubscribe any time.', checked: true }),
+        `checkbox({
+  name:    'marketing',
+  label:   'Marketing emails',
+  hint:    'Product news and tips. Unsubscribe any time.',
+  checked: state.marketing,
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="error">Error state</h2>
+      <p>Pass <code>error</code> to show a validation message. The error is announced via <code>role="alert"</code>.</p>
+      ${demo(
+        checkbox({ name: 'terms', label: 'I accept the terms and conditions', error: 'You must accept the terms to continue.' }),
+        `checkbox({
+  name:  'terms',
+  label: 'I accept the terms and conditions',
+  error: server.errors.terms,
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="disabled">Disabled</h2>
+      ${demo(
+        checkbox({ name: 'feature', label: 'Enable beta features', disabled: true }) +
+        ' ' +
+        checkbox({ name: 'feature2', label: 'Beta feature (on)', disabled: true, checked: true }),
+        `checkbox({ name: 'feature', label: 'Enable beta features', disabled: true })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="group">Group in a fieldset</h2>
+      <p>Compose multiple checkboxes inside a <a href="/components/fieldset">fieldset</a> for a semantic group.</p>
+      ${demo(
+        fieldset({
+          legend: 'Notifications',
+          content:
+            checkbox({ name: 'notif', value: 'email',   label: 'Email',            checked: true  }) +
+            checkbox({ name: 'notif', value: 'sms',     label: 'SMS'                              }) +
+            checkbox({ name: 'notif', value: 'browser', label: 'Browser push',     checked: true  }) +
+            checkbox({ name: 'notif', value: 'weekly',  label: 'Weekly digest',    disabled: true }),
+        }),
+        `fieldset({
+  legend:  'Notifications',
+  content:
+    checkbox({ name: 'notif', value: 'email',   label: 'Email',         checked: true }) +
+    checkbox({ name: 'notif', value: 'sms',     label: 'SMS'                          }) +
+    checkbox({ name: 'notif', value: 'browser', label: 'Browser push',  checked: true }) +
+    checkbox({ name: 'notif', value: 'weekly',  label: 'Weekly digest', disabled: true }),
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="in-forms">In forms</h2>
+      ${callout('note', 'Checkboxes submit their <code>value</code> string (defaulting to <code>"on"</code>) under <code>name</code> in FormData only when checked. Unchecked checkboxes are absent from FormData. Read them in <code>action.onStart</code> via <code>formData.get(\'agree\')</code> — a <code>null</code> result means unchecked.')}
+
+      <h2 class="doc-h2" id="labelhtml">Custom label HTML</h2>
+      <p>When the label needs inline styling — for example a strikethrough on a completed todo — use <code>labelHtml</code> instead of <code>label</code>. The value is inserted as raw HTML so you are responsible for escaping any user content.</p>
+      ${demo(
+        checkbox({ name: 'task', labelHtml: '<span style="text-decoration:line-through;opacity:.5">Buy milk</span>', checked: true }),
+        `checkbox({
+  name:      'task',
+  checked:   todo.done,
+  labelHtml: \`<span class="\${todo.done ? 'u-text-muted' : ''}">\${esc(todo.text)}</span>\`,
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="props">Props</h2>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',      'string',  '—',     'Field name'],
+          ['<code>value</code>',     'string',  '—',     'Submitted value when checked (defaults to browser default <code>"on"</code>)'],
+          ['<code>label</code>',     'string',  '—',     'Visible label text — escaped'],
+          ['<code>labelHtml</code>', 'string',  '—',     'Raw HTML label slot — not escaped, use for styled spans'],
+          ['<code>checked</code>',   'boolean', 'false', ''],
+          ['<code>disabled</code>',  'boolean', 'false', ''],
+          ['<code>id</code>',        'string',  '—',     'Override the auto-generated <code>id</code>'],
+          ['<code>event</code>',     'string',  '—',     '<code>data-event</code> binding, e.g. <code>"change:toggle"</code>'],
+          ['<code>hint</code>',      'string',  '—',     'Helper text below the label'],
+          ['<code>error</code>',     'string',  '—',     'Validation error — announced via <code>role="alert"</code>'],
+          ['<code>class</code>',     'string',  '—',     ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,47 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { badge, cluster } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/cluster')
+
+export default {
+  route: '/components/cluster',
+  meta: {
+    title: 'Cluster — Pulse Docs',
+    description: 'Cluster component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/cluster',
+    prev,
+    next,
+    name: 'cluster',
+    description: 'Flex row with wrapping. Groups inline elements horizontally — action buttons, badges, app store badges, stat rows.',
+    content: `
+      ${demo(
+        cluster({
+          gap: 'sm',
+          content: badge({ label: 'Performance' }) + badge({ label: 'Accessibility' }) + badge({ label: 'Zero JS', variant: 'success' }) + badge({ label: 'SSR', variant: 'info' }),
+        }),
+        `cluster({ gap: 'sm', justify: 'center', content:
+  badge({ label: 'Performance' }) +
+  badge({ label: 'Zero JS', variant: 'success' }) +
+  appBadge({ store: 'apple', href: url })
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>', 'string (HTML)', '—',       'Raw HTML slot'],
+          ['<code>gap</code>',     'string',        "'md'",    "'xs' · 'sm' · 'md' · 'lg'"],
+          ['<code>justify</code>', 'string',        "'start'", "'start' · 'center' · 'end' · 'between'"],
+          ['<code>align</code>',   'string',        "'center'","'start' · 'center' · 'end'"],
+          ['<code>wrap</code>',    'boolean',       'true',    'Set false to prevent wrapping'],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/code-window.js

@@ -0,0 +1,57 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { codeWindow } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/code-window')
+
+export default {
+  route: '/components/code-window',
+  meta: {
+    title: 'Code Window — Pulse Docs',
+    description: 'macOS-style window chrome around a code block. Accepts pre-highlighted HTML as the content slot.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/code-window',
+    prev,
+    next,
+    name: 'codeWindow',
+    description: 'macOS-style window chrome around a code block. Accepts pre-highlighted HTML as the content slot — the component handles all the chrome, layout, scrolling, and monospace typography.',
+    content: `
+      ${demo(
+        codeWindow({
+          filename: 'home.js',
+          lang:     'JavaScript',
+          content:  `<span style="color:var(--ui-accent)">export default</span> {
+  <span style="color:var(--ui-text)">state</span>: { count: <span style="color:var(--ui-green)">0</span> },
+
+  <span style="color:var(--ui-text)">view</span>: (state) =&gt; \`
+    &lt;h1&gt;\${state.count}&lt;/h1&gt;
+    &lt;button data-event=<span style="color:var(--ui-yellow)">"inc"</span>&gt;+&lt;/button&gt;
+  \`,
+
+  <span style="color:var(--ui-text)">mutations</span>: {
+    inc: (state) =&gt; ({ count: state.count + <span style="color:var(--ui-green)">1</span> }),
+  },
+}`,
+        }),
+        `codeWindow({
+  filename: 'home.js',
+  lang:     'JavaScript',
+  content:  highlightedHtml, // pre-rendered HTML with syntax token spans
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>',  'string (HTML)', '—', 'Raw HTML slot — pre-highlighted code HTML or plain text'],
+          ['<code>filename</code>', 'string',        '—', "Filename shown in the chrome bar (e.g. 'home.js')"],
+          ['<code>lang</code>',     'string',        '—', "Language label shown on the right of the chrome (e.g. 'JavaScript')"],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,40 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { container } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/container')
+
+export default {
+  route: '/components/container',
+  meta: {
+    title: 'Container — Pulse Docs',
+    description: 'Container component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/container',
+    prev,
+    next,
+    name: 'container',
+    description: 'Max-width wrapper with horizontal padding. The four size presets cover the most common layout widths.',
+    content: `
+      ${demo(
+        container({ content: '<p style="background:var(--surface-2);border:1px dashed var(--border);padding:1rem;border-radius:6px;text-align:center;color:var(--muted)">Content constrained to 768px</p>', size: 'md' }),
+        `container({ size: 'md', content: \`
+  \${hero({ title: 'Hello' })}
+  \${grid({ cols: 3, content: features })}
+\` })`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>', 'string (HTML)', '—',    'Raw HTML slot'],
+          ['<code>size</code>',    'string',        "'lg'", "'sm' (640px) · 'md' (768px) · 'lg' (1100px) · 'xl' (1280px)"],
+        ]
+      )}
+    `,
+  }),
+}