@invisibleloop/pulse 0.1.21

package/docs/src/pages/components/pullquote.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 { pullquote } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/pullquote')
+
+export default {
+  route: '/components/pullquote',
+  meta: {
+    title: 'Pullquote — Pulse Docs',
+    description: 'Styled blockquote component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/pullquote',
+    prev,
+    next,
+    name: 'pullquote',
+    description: 'Styled blockquote with an accent left border and optional attribution. Use it to highlight key quotes or testimonials within body content.',
+    content: `
+
+      <h2 class="doc-h2" id="basic">Basic</h2>
+      ${demo(
+        pullquote({
+          quote: 'Design is not just what it looks like and feels like. Design is how it works.',
+          cite:  'Steve Jobs, co-founder of Apple',
+        }),
+        `pullquote({
+  quote: 'Design is not just what it looks like and feels like. Design is how it works.',
+  cite:  'Steve Jobs, co-founder of Apple',
+})`
+      )}
+
+      <h2 class="doc-h2" id="large">Large</h2>
+      ${demo(
+        pullquote({
+          quote: 'Simplicity is the ultimate sophistication.',
+          cite:  'Leonardo da Vinci',
+          size:  'lg',
+        }),
+        `pullquote({
+  quote: 'Simplicity is the ultimate sophistication.',
+  cite:  'Leonardo da Vinci',
+  size:  'lg',
+})`
+      )}
+
+      <h2 class="doc-h2" id="no-cite">Without attribution</h2>
+      ${demo(
+        pullquote({
+          quote: 'Good design makes a product understandable.',
+        }),
+        `pullquote({
+  quote: 'Good design makes a product understandable.',
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>quote</code>', 'string',            '—',           'The quote text — escaped automatically'],
+          ['<code>cite</code>',  'string',            '—',           'Attribution text — rendered in a <code>&lt;figcaption&gt;</code>'],
+          ['<code>size</code>',  '<code>md | lg</code>', '<code>md</code>', 'Controls the font size of the quote text'],
+          ['<code>class</code>', 'string',            '—',           ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,194 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout } from '../../lib/layout.js'
+import { radio, radioGroup, fieldset } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/radio')
+
+export default {
+  route: '/components/radio',
+  meta: {
+    title: 'Radio — Pulse Docs',
+    description: 'Radio button and radio group components for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/radio',
+    prev,
+    next,
+    name: 'radio',
+    description: 'Custom-styled radio buttons with full keyboard and screen-reader support. Use <code>radio()</code> for a single option or <code>radioGroup()</code> for a semantic group inside a form.',
+    content: `
+
+      <h2 class="doc-h2" id="group">Radio group</h2>
+      <p>The standard usage. <code>radioGroup()</code> renders a <code>&lt;fieldset&gt;</code> with a <code>&lt;legend&gt;</code> and marks the currently selected option via the <code>value</code> prop.</p>
+      ${demo(
+        radioGroup({
+          name:    'plan',
+          legend:  'Plan',
+          value:   'pro',
+          options: [
+            { value: 'starter', label: 'Starter' },
+            { value: 'pro',     label: 'Pro'     },
+            { value: 'team',    label: 'Team'    },
+          ],
+        }),
+        `radioGroup({
+  name:    'plan',
+  legend:  'Plan',
+  value:   state.plan,   // marks the selected option
+  options: [
+    { value: 'starter', label: 'Starter' },
+    { value: 'pro',     label: 'Pro'     },
+    { value: 'team',    label: 'Team'    },
+  ],
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="hints">Per-option hints</h2>
+      <p>Each option accepts a <code>hint</code> string for supporting copy below the label.</p>
+      ${demo(
+        radioGroup({
+          name:    'billing',
+          legend:  'Billing cycle',
+          value:   'annual',
+          options: [
+            { value: 'monthly', label: 'Monthly',  hint: 'Billed every month. Cancel any time.' },
+            { value: 'annual',  label: 'Annual',   hint: 'Billed once a year. Save 20%.'        },
+          ],
+        }),
+        `radioGroup({
+  name:    'billing',
+  legend:  'Billing cycle',
+  value:   state.billing,
+  options: [
+    { value: 'monthly', label: 'Monthly', hint: 'Billed every month. Cancel any time.' },
+    { value: 'annual',  label: 'Annual',  hint: 'Billed once a year. Save 20%.'        },
+  ],
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="error">Error state</h2>
+      <p>Pass <code>error</code> to show a validation message below the group. The message is linked via <code>aria-describedby</code>.</p>
+      ${demo(
+        radioGroup({
+          name:    'size',
+          legend:  'Size',
+          error:   'Please select a size.',
+          options: [
+            { value: 'sm', label: 'Small'  },
+            { value: 'md', label: 'Medium' },
+            { value: 'lg', label: 'Large'  },
+          ],
+        }),
+        `radioGroup({
+  name:    'size',
+  legend:  'Size',
+  error:   server.errors.size,
+  options: [
+    { value: 'sm', label: 'Small'  },
+    { value: 'md', label: 'Medium' },
+    { value: 'lg', label: 'Large'  },
+  ],
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="disabled">Disabled options</h2>
+      <p>Set <code>disabled: true</code> on individual options, or pass <code>disabled</code> at the group level to disable all.</p>
+      ${demo(
+        radioGroup({
+          name:    'tier',
+          legend:  'Tier',
+          value:   'basic',
+          options: [
+            { value: 'basic',       label: 'Basic'      },
+            { value: 'pro',         label: 'Pro'        },
+            { value: 'enterprise',  label: 'Enterprise', disabled: true },
+          ],
+        }),
+        `radioGroup({
+  name:    'tier',
+  legend:  'Tier',
+  value:   state.tier,
+  options: [
+    { value: 'basic',      label: 'Basic'      },
+    { value: 'pro',        label: 'Pro'        },
+    { value: 'enterprise', label: 'Enterprise', disabled: true },
+  ],
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="gap">Gap</h2>
+      <p>Control spacing between options with <code>gap</code>: <code>'sm'</code> · <code>'md'</code> (default) · <code>'lg'</code>.</p>
+      ${demo(
+        radioGroup({
+          name:    'color',
+          legend:  'Colour',
+          gap:     'lg',
+          value:   'blue',
+          options: [
+            { value: 'red',  label: 'Red'  },
+            { value: 'blue', label: 'Blue' },
+            { value: 'green',label: 'Green'},
+          ],
+        }),
+        `radioGroup({ ..., gap: 'lg' })`
+      )}
+
+      <h2 class="doc-h2" id="single">Single radio</h2>
+      <p>Use <code>radio()</code> directly when you need to compose your own group layout — for example inside a <a href="/components/fieldset">fieldset</a> alongside other controls.</p>
+      ${demo(
+        fieldset({
+          legend: 'Preferred contact',
+          content:
+            radio({ name: 'contact', value: 'email', label: 'Email', checked: true }) +
+            radio({ name: 'contact', value: 'phone', label: 'Phone' }),
+        }),
+        `fieldset({
+  legend:  'Preferred contact',
+  content:
+    radio({ name: 'contact', value: 'email', label: 'Email', checked: true }) +
+    radio({ name: 'contact', value: 'phone', label: 'Phone' }),
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="in-forms">In forms</h2>
+      ${callout('note', 'Radio groups submit the selected <code>value</code> string under <code>name</code> in FormData. If nothing is selected, the field is absent from FormData. Read it in <code>action.onStart</code> or <code>action.run</code> via <code>formData.get(\'plan\')</code>.')}
+
+      <h2 class="doc-h2" id="props-group">radioGroup() props</h2>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',    'string',  '—',       'Shared <code>name</code> attribute for all inputs in the group'],
+          ['<code>legend</code>',  'string',  '—',       'Group label — renders as a <code>&lt;legend&gt;</code>'],
+          ['<code>options</code>', 'array',   '<code>[]</code>', 'Array of <code>{ value, label, hint?, disabled? }</code>'],
+          ['<code>value</code>',   'string',  '—',       'The currently selected value — marks the matching option as <code>checked</code>'],
+          ['<code>hint</code>',    'string',  '—',       'Helper text below the group'],
+          ['<code>error</code>',   'string',  '—',       'Validation error — linked via <code>aria-describedby</code>'],
+          ['<code>gap</code>',     '<code>sm | md | lg</code>', '<code>md</code>', 'Spacing between options'],
+          ['<code>class</code>',   'string',  '—',       ''],
+        ]
+      )}
+
+      <h2 class="doc-h2" id="props-radio">radio() props</h2>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',     'string',  '—',      'Field name'],
+          ['<code>value</code>',    'string',  '—',      'Submitted value when this option is selected'],
+          ['<code>label</code>',    'string',  '—',      'Visible label'],
+          ['<code>checked</code>',  'boolean', 'false',  ''],
+          ['<code>disabled</code>', 'boolean', 'false',  ''],
+          ['<code>id</code>',       'string',  '—',      'Override the generated <code>id</code>'],
+          ['<code>class</code>',    'string',  '—',      ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,106 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout } from '../../lib/layout.js'
+import { rating, card } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/rating')
+
+export default {
+  route: '/components/rating',
+  meta: {
+    title: 'Rating — Pulse Docs',
+    description: 'Star rating display and interactive input component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/rating',
+    prev,
+    next,
+    name: 'rating',
+    description: 'Star rating component with two modes. Without <code>name</code>: a read-only display that supports half-star values. With <code>name</code>: an interactive radio group that submits the selected value in FormData — no JavaScript required.',
+    content: `
+
+      <h2 class="doc-h2" id="display">Display (read-only)</h2>
+      <p>Omit <code>name</code> to render a read-only display. Pass <code>value</code> as a number — halves are supported.</p>
+      ${demo(
+        `<div style="display:flex;flex-direction:column;gap:1rem;align-items:flex-start">` +
+          rating({ value: 5 }) +
+          rating({ value: 3.5 }) +
+          rating({ value: 2 }) +
+          rating({ value: 0 }) +
+        `</div>`,
+        `rating({ value: 5   })   // 5 stars
+rating({ value: 3.5 })   // 3½ stars
+rating({ value: 2   })   // 2 stars
+rating({ value: 0   })   // empty`
+      )}
+
+      <h2 class="doc-h2" id="sizes">Sizes</h2>
+      <p><code>'sm'</code> · <code>'md'</code> (default) · <code>'lg'</code></p>
+      ${demo(
+        `<div style="display:flex;flex-direction:column;gap:1rem;align-items:flex-start">` +
+          rating({ value: 4, size: 'sm' }) +
+          rating({ value: 4, size: 'md' }) +
+          rating({ value: 4, size: 'lg' }) +
+        `</div>`,
+        `rating({ value: 4, size: 'sm' })
+rating({ value: 4, size: 'md' })
+rating({ value: 4, size: 'lg' })`
+      )}
+
+      <h2 class="doc-h2" id="interactive">Interactive</h2>
+      <p>Add <code>name</code> to render radio inputs. Hovering a star previews the selection; clicking locks it. The selected value is submitted in FormData.</p>
+      ${demo(
+        rating({ name: 'score', label: 'Your rating', value: 3, size: 'lg' }),
+        `rating({ name: 'score', label: 'Your rating', value: state.score, size: 'lg' })`
+      )}
+
+      <h2 class="doc-h2" id="in-card">In a card</h2>
+      ${demo(
+        `<div style="max-width:320px">` +
+          card({
+            title: 'Noise-Cancelling Headphones',
+            content:
+              `<div style="display:flex;align-items:center;gap:.75rem;margin-bottom:.75rem">` +
+                rating({ value: 4.5 }) +
+                `<span style="color:var(--ui-muted);font-size:.85rem">4.5 · 1,284 reviews</span>` +
+              `</div>` +
+              `<p style="color:var(--ui-muted);margin:0;font-size:.9rem">Crystal-clear audio with 40-hour battery life and adaptive noise cancellation.</p>`,
+          }) +
+        `</div>`,
+        `card({
+  title:   'Noise-Cancelling Headphones',
+  content:
+    '<div style="display:flex;align-items:center;gap:.75rem">' +
+      rating({ value: 4.5 }) +
+      '<span>4.5 · 1,284 reviews</span>' +
+    '</div>' +
+    '<p>Crystal-clear audio...</p>',
+})`
+      )}
+
+      <h2 class="doc-h2" id="disabled">Disabled</h2>
+      ${demo(
+        rating({ name: 'locked', value: 4, disabled: true }),
+        `rating({ name: 'locked', value: 4, disabled: true })`
+      )}
+
+      <h2 class="doc-h2" id="in-forms">In forms</h2>
+      ${callout('note', 'The interactive rating submits the selected star count as a number string under <code>name</code> in FormData. Read it with <code>Number(formData.get(\'score\'))</code>. If nothing is selected, the field is absent from FormData.')}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>value</code>',    'number',  '0',       'Current rating. Supports 0.5 steps in display mode.'],
+          ['<code>max</code>',      'number',  '5',       'Total number of stars'],
+          ['<code>name</code>',     'string',  '—',       'Field name — enables interactive radio mode'],
+          ['<code>label</code>',    'string',  '—',       'Accessible group label (interactive mode only)'],
+          ['<code>size</code>',     '<code>sm | md | lg</code>', '<code>md</code>', '1rem / 1.5rem / 2rem'],
+          ['<code>disabled</code>', 'boolean', 'false',   'Interactive mode only'],
+          ['<code>class</code>',    'string',  '—',       ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,61 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { search } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/search')
+
+export default {
+  route: '/components/search',
+  meta: {
+    title: 'Search — Pulse Docs',
+    description: 'Search input component with icon, debounce binding, and clear button.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/search',
+    prev,
+    next,
+    name: 'search',
+    description: 'A search input with a built-in icon and optional clear button. Handles the native browser cancel button, <code>data-event</code> binding, and debounce in one component. Use this instead of <code>input({ type: \'search\' })</code>.',
+    content: `
+      ${demo(
+        search({ name: 'q', label: 'Search', placeholder: 'Search products…' }) +
+        search({ name: 'q2', label: 'Search', placeholder: 'Search…', value: 'lamp', clearEvent: 'clearSearch', labelHidden: true }),
+        `search({ name: 'q', label: 'Search', placeholder: 'Search products…' })
+
+// With value, clear button, and hidden label:
+search({
+  name:        'q',
+  label:       'Search',
+  labelHidden: true,
+  placeholder: 'Search…',
+  value:       state.search,
+  event:       'input:setSearch',
+  debounce:    200,
+  clearEvent:  'clearSearch',
+})`,
+        { col: true }
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',        'string',  '—',     'Field name and id base'],
+          ['<code>label</code>',       'string',  '—',     'Label text — always provide for accessibility'],
+          ['<code>labelHidden</code>', 'boolean', 'false', 'Hides label visually; still read by screen readers'],
+          ['<code>placeholder</code>', 'string',  '—',     ''],
+          ['<code>value</code>',       'string',  '—',     'Current value — controls clear button visibility'],
+          ['<code>event</code>',       'string',  '—',     '<code>data-event</code> binding, e.g. <code>\'input:setSearch\'</code>'],
+          ['<code>debounce</code>',    'number',  '200',   'Debounce delay in ms — only applied when <code>event</code> is set'],
+          ['<code>clearEvent</code>',  'string',  '—',     'Click event for the × button — only shown when <code>value</code> is non-empty'],
+          ['<code>disabled</code>',    'boolean', 'false', ''],
+          ['<code>id</code>',          'string',  '—',     'Override generated id'],
+          ['<code>class</code>',       'string',  '—',     'Extra classes on the wrapper'],
+          ['<code>attrs</code>',       'object',  '{}',    'Extra attributes on the <code>&lt;input&gt;</code>'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,59 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { container, section as uiSection } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/section')
+
+export default {
+  route: '/components/section',
+  meta: {
+    title: 'Section — Pulse Docs',
+    description: 'Vertical padding wrapper with optional background. Compose with container() for full-width background with constrained content.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/section',
+    prev,
+    next,
+    name: 'section',
+    description: 'Vertical padding wrapper with optional background. Compose with <code>container()</code> for full-width background with constrained content.',
+    content: `
+      ${demo(
+        uiSection({
+          eyebrow: 'Why Pulse',
+          title: 'Built for speed.',
+          subtitle: 'Every page scores 100 on Lighthouse by design, not by optimisation.',
+          align: 'center',
+          variant: 'alt',
+          content: container({ size: 'md', content: '<p style="text-align:center;color:var(--ui-muted)">Content goes here</p>' }),
+        }) +
+        uiSection({ variant: 'dark', content: container({ size: 'md', content: '<p style="text-align:center;color:var(--ui-muted)">Dark background · no header</p>' }) }),
+        `section({
+  eyebrow:  'Why Pulse',
+  title:    'Built for speed.',
+  subtitle: 'Every page scores 100 on Lighthouse by design.',
+  align:    'center',
+  variant:  'alt',
+  content:  container({ size: 'lg', content: featureGrid }),
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>',  'string (HTML)', '—',         'Raw HTML slot'],
+          ['<code>variant</code>',  'string',        "'default'", "'default' · 'alt' · 'dark'"],
+          ['<code>padding</code>',  'string',        "'md'",      "'sm' · 'md' · 'lg'"],
+          ['<code>id</code>',       'string',        '—',         'Anchor id for nav links'],
+          ['<code>eyebrow</code>',  'string',        '—',    'Small label above the title'],
+          ['<code>title</code>',    'string',        '—',    'Section heading'],
+          ['<code>level</code>',    'number',        '2',    'Heading tag for the title (1–6). Visual style is unchanged.'],
+          ['<code>subtitle</code>', 'string',        '—',    'Supporting text beneath the heading'],
+          ['<code>align</code>',    'string',        "'left'",    "'left' · 'center'"],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,121 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout, section } from '../../lib/layout.js'
+import { segmented, stack } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/segmented')
+
+export default {
+  route: '/components/segmented',
+  meta: {
+    title: 'Segmented — Pulse Docs',
+    description: 'iOS-style segmented control component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/segmented',
+    prev,
+    next,
+    name: 'segmented',
+    description: 'iOS-style segmented control built from hidden radio inputs. The selected segment is highlighted via CSS — no JavaScript required.',
+    content: `
+
+      <h2 class="doc-h2" id="basic">Basic</h2>
+      ${demo(
+        segmented({
+          name:  'period',
+          value: 'week',
+          options: [
+            { value: 'day',   label: 'Day'   },
+            { value: 'week',  label: 'Week'  },
+            { value: 'month', label: 'Month' },
+          ],
+        }),
+        `segmented({
+  name:  'period',
+  value: state.period,
+  options: [
+    { value: 'day',   label: 'Day'   },
+    { value: 'week',  label: 'Week'  },
+    { value: 'month', label: 'Month' },
+  ],
+})`
+      )}
+
+      <h2 class="doc-h2" id="sizes">Sizes</h2>
+      ${demo(
+        stack({ gap: 'md', content:
+          segmented({
+            name:  'size-sm',
+            value: 'b',
+            size:  'sm',
+            options: [
+              { value: 'a', label: 'Small' },
+              { value: 'b', label: 'Sizes' },
+              { value: 'c', label: 'Here'  },
+            ],
+          }) +
+          segmented({
+            name:  'size-md',
+            value: 'b',
+            size:  'md',
+            options: [
+              { value: 'a', label: 'Medium' },
+              { value: 'b', label: 'Default' },
+              { value: 'c', label: 'Size'    },
+            ],
+          }) +
+          segmented({
+            name:  'size-lg',
+            value: 'b',
+            size:  'lg',
+            options: [
+              { value: 'a', label: 'Large' },
+              { value: 'b', label: 'Size'  },
+              { value: 'c', label: 'Here'  },
+            ],
+          }),
+        }),
+        `segmented({ name: 'view', value: 'b', size: 'sm', options: [...] })
+segmented({ name: 'view', value: 'b', size: 'md', options: [...] })
+segmented({ name: 'view', value: 'b', size: 'lg', options: [...] })`
+      )}
+
+      <h2 class="doc-h2" id="ui-context">View toggle</h2>
+      <p>A common use case — toggling between Grid and List views.</p>
+      ${demo(
+        segmented({
+          name:  'layout',
+          value: 'grid',
+          options: [
+            { value: 'grid', label: 'Grid' },
+            { value: 'list', label: 'List' },
+          ],
+        }),
+        `segmented({
+  name:    'layout',
+  value:   state.layout,
+  options: [
+    { value: 'grid', label: 'Grid' },
+    { value: 'list', label: 'List' },
+  ],
+})`
+      )}
+
+      ${callout('note', 'The segmented control submits the selected <code>value</code> string under <code>name</code> in FormData. Read it via <code>formData.get(\'period\')</code> in <code>action.onStart</code> or <code>action.run</code>.')}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',     'string',  '—',    'Field name — submitted in FormData'],
+          ['<code>options</code>',  'array',   '[]',   'Array of <code>{ value, label }</code>'],
+          ['<code>value</code>',    'string',  '—',    'The currently selected value'],
+          ['<code>size</code>',     '<code>sm | md | lg</code>', '<code>md</code>', ''],
+          ['<code>disabled</code>', 'boolean', 'false', 'Disables all options'],
+          ['<code>class</code>',    'string',  '—',    ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,45 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { select } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/select')
+
+export default {
+  route: '/components/select',
+  meta: {
+    title: 'Select — Pulse Docs',
+    description: 'Select component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/select',
+    prev,
+    next,
+    name: 'select',
+    description: 'Options can be plain strings or <code>{ value, label }</code> objects. Pass <code>value</code> to mark the current selection.',
+    content: `
+      ${demo(
+        select({
+          name: 'role', label: 'Role',
+          options: ['Admin', 'Editor', 'Viewer'],
+          value: 'Editor',
+        }) +
+        select({
+          name: 'status', label: 'Status',
+          options: [{ value: 'active', label: 'Active' }, { value: 'paused', label: 'Paused' }],
+          error: 'Please select a status',
+        }),
+        `select({ name: 'role', label: 'Role', options: ['Admin', 'Editor', 'Viewer'], value: state.role })
+select({
+  name:    'country',
+  label:   'Country',
+  options: [{ value: 'gb', label: 'United Kingdom' }, { value: 'us', label: 'United States' }],
+  value:   state.country,
+  required: true,
+})`,
+        { col: true }
+      )}
+    `,
+  }),
+}