@invisibleloop/pulse 0.1.21

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

@@ -0,0 +1,114 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout } from '../../lib/layout.js'
+import { slider } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/slider')
+
+export default {
+  route: '/components/slider',
+  meta: {
+    title: 'Slider — Pulse Docs',
+    description: 'Styled range input slider component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: { brightness: 100 },
+  mutations: {
+    setBrightness: (state, e) => ({ brightness: Number(e.target.value) }),
+  },
+  view: (state) => renderComponentPage({
+    currentHref: '/components/slider',
+    prev,
+    next,
+    name: 'slider',
+    description: 'Styled range input with label, hint, and a CSS-driven fill gradient that tracks the thumb live as you drag.',
+    content: `
+
+      <h2 class="doc-h2" id="basic">Basic</h2>
+      ${demo(
+        slider({ name: 'volume', label: 'Volume', showValue: true }),
+        `slider({ name: 'volume', label: 'Volume', showValue: true })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="min-max-step">Min, max, step, and hint</h2>
+      ${demo(
+        slider({
+          name:      'brightness',
+          label:     'Brightness',
+          min:       0,
+          max:       200,
+          step:      10,
+          value:     100,
+          showValue: true,
+          hint:      'Adjust display brightness (0–200)',
+        }),
+        `slider({
+  name:      'brightness',
+  label:     'Brightness',
+  min:       0,
+  max:       200,
+  step:      10,
+  value:     100,
+  showValue: true,
+  hint:      'Adjust display brightness (0–200)',
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="live-value">Live value in state</h2>
+      <p class="u-mb-4 u-text-sm u-color-muted">Use <code>data-event="change:mutationName"</code> to capture the value when the user releases the handle. The fill gradient always updates live — no mutation needed for that.</p>
+      ${demo(
+        `<div>
+          ${slider({ name: 'brightness', label: 'Brightness', value: state.brightness, min: 0, max: 200, step: 10, showValue: true, event: 'change:setBrightness' })}
+        </div>`,
+        `// state
+{ brightness: 100 }
+
+// mutation
+setBrightness: (state, e) => ({ brightness: Number(e.target.value) })
+
+// view
+slider({
+  name:      'brightness',
+  label:     'Brightness',
+  min:       0,
+  max:       200,
+  step:      10,
+  value:     state.brightness,
+  showValue: true,
+  event:     'change:setBrightness',
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="disabled">Disabled</h2>
+      ${demo(
+        slider({ name: 'opacity', label: 'Opacity', value: 30, disabled: true }),
+        `slider({ name: 'opacity', label: 'Opacity', value: 30, disabled: true })`,
+        { col: true }
+      )}
+
+      ${callout('note', 'The fill gradient updates live during drag automatically. To read the final value, either use <code>data-event="change:mutationName"</code> on the slider or submit it as part of a form — the value is available in FormData as a number string under <code>name</code>.')}
+      ${callout('warning', 'Do not use <code>data-event="input:mutationName"</code> on a slider. Pulse replaces <code>innerHTML</code> on every mutation, which interrupts the drag mid-gesture. Use <code>change</code> instead — it fires once when the user releases the handle.')}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',     'string',  '—',     'Field name — submitted in FormData'],
+          ['<code>label</code>',    'string',  '—',     'Visible label text'],
+          ['<code>min</code>',      'number',  '0',     'Minimum value'],
+          ['<code>max</code>',      'number',  '100',   'Maximum value'],
+          ['<code>step</code>',     'number',  '1',     'Step increment'],
+          ['<code>value</code>',    'number',  '50',    'Current value'],
+          ['<code>showValue</code>', 'boolean', 'false', 'Show current value live beside the label as you drag'],
+          ['<code>disabled</code>', 'boolean', 'false', ''],
+          ['<code>hint</code>',     'string',  '—',     'Helper text below the slider'],
+          ['<code>event</code>',    'string',  '—',     '<code>data-event</code> binding, e.g. <code>change:mutationName</code>'],
+          ['<code>id</code>',       'string',  '—',     'Override the generated <code>id</code>'],
+          ['<code>class</code>',    'string',  '—',     ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,73 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { spinner, button, cluster } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/spinner')
+
+export default {
+  route: '/components/spinner',
+  meta: {
+    title: 'Spinner — Pulse Docs',
+    description: 'Loading spinner component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/spinner',
+    prev,
+    next,
+    name: 'spinner',
+    description: 'CSS-animated loading ring. No JavaScript required. Use to indicate background activity — inside buttons, next to labels, or as a full-area overlay.',
+    content: `
+
+      <h2 class="doc-h2" id="sizes">Sizes</h2>
+      ${demo(
+        cluster({ gap: 'lg', align: 'center', content:
+          spinner({ size: 'sm' }) +
+          spinner({ size: 'md' }) +
+          spinner({ size: 'lg' }),
+        }),
+        `spinner({ size: 'sm' })
+spinner({ size: 'md' })
+spinner({ size: 'lg' })`
+      )}
+
+      <h2 class="doc-h2" id="colors">Colours</h2>
+      ${demo(
+        cluster({ gap: 'lg', align: 'center', content:
+          spinner({ color: 'accent' }) +
+          spinner({ color: 'muted'  }) +
+          `<span style="background:var(--ui-accent);padding:.75rem;border-radius:var(--ui-radius);display:inline-flex">` +
+            spinner({ color: 'white' }) +
+          `</span>`,
+        }),
+        `spinner({ color: 'accent' })
+spinner({ color: 'muted'  })
+spinner({ color: 'white'  })`
+      )}
+
+      <h2 class="doc-h2" id="in-button">Inside a button</h2>
+      <p>Pair with a <code>button()</code> to show loading state. Pass the spinner as the button's <code>icon</code> prop.</p>
+      ${demo(
+        button({ label: 'Saving', icon: spinner({ size: 'sm', color: 'white' }), disabled: true }) + ' ' +
+        button({ label: 'Loading', icon: spinner({ size: 'sm' }), variant: 'secondary', disabled: true }),
+        `button({
+  label:    'Saving',
+  icon:     spinner({ size: 'sm', color: 'white' }),
+  disabled: state.loading,
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>size</code>',  '<code>sm | md | lg</code>',           '<code>md</code>',     '1rem / 1.5rem / 2.5rem'],
+          ['<code>color</code>', '<code>accent | muted | white</code>', '<code>accent</code>', ''],
+          ['<code>label</code>', 'string', '<code>Loading…</code>', 'Sets <code>aria-label</code> on the <code>role="status"</code> element'],
+          ['<code>class</code>', 'string', '—', ''],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/stack.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 { button, stack } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/stack')
+
+export default {
+  route: '/components/stack',
+  meta: {
+    title: 'Stack — Pulse Docs',
+    description: 'Stack component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/stack',
+    prev,
+    next,
+    name: 'stack',
+    description: 'Flex column with consistent vertical gap. Replaces the common pattern of adding <code>margin-bottom</code> to every child element.',
+    content: `
+      ${demo(
+        stack({
+          gap: 'sm',
+          content:
+            button({ label: 'Primary action' }) +
+            button({ label: 'Secondary action', variant: 'secondary' }) +
+            button({ label: 'Ghost action', variant: 'ghost' }),
+        }),
+        `stack({ gap: 'sm', align: 'start', content:
+  button({ label: 'Primary action' }) +
+  button({ label: 'Secondary action', variant: 'secondary' }) +
+  button({ label: 'Ghost', variant: 'ghost' })
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>', 'string (HTML)', '—',         'Raw HTML slot'],
+          ['<code>gap</code>',     'string',        "'md'",      "'xs' · 'sm' · 'md' · 'lg' · 'xl'"],
+          ['<code>align</code>',   'string',        "'stretch'", "'stretch' · 'start' · 'center' · 'end'"],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,55 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { stat } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/stat')
+
+export default {
+  route: '/components/stat',
+  meta: {
+    title: 'Stat — Pulse Docs',
+    description: 'Stat component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/stat',
+    prev,
+    next,
+    name: 'stat',
+    description: 'Numeric metric display with optional trend indicator. Use inside a <code>card()</code> or a flex/grid container for dashboard layouts.',
+    content: `
+      ${demo(
+        `<div style="display:flex;gap:2rem;flex-wrap:wrap">` +
+          stat({ label: 'Total users',  value: '12,483', change: '+8.2%', trend: 'up'      }) +
+          stat({ label: 'Bounce rate',  value: '24%',    change: '−3.1%', trend: 'down'    }) +
+          stat({ label: 'Avg. session', value: '4m 12s'                                    }) +
+        `</div>`,
+        `stat({ label: 'Total users',  value: '12,483', change: '+8.2%', trend: 'up'   })
+stat({ label: 'Bounce rate',  value: '24%',    change: '−3.1%', trend: 'down' })
+stat({ label: 'Avg. session', value: '4m 12s' })`
+      )}
+      <p>The <code>center</code> prop centre-aligns the value, label, and change — useful in grids or dashboard cards.</p>
+      ${demo(
+        `<div style="display:flex;gap:2rem;flex-wrap:wrap">` +
+          stat({ label: 'Total users',  value: '12,483', change: '+8.2%', trend: 'up',   center: true }) +
+          stat({ label: 'Bounce rate',  value: '24%',    change: '−3.1%', trend: 'down', center: true }) +
+          stat({ label: 'Avg. session', value: '4m 12s',                                 center: true }) +
+        `</div>`,
+        `stat({ label: 'Total users', value: '12,483', change: '+8.2%', trend: 'up', center: true })`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>label</code>',  'string',  '—',       ''],
+          ['<code>value</code>',  'string',  '—',       'Formatted value string — e.g. "2.4k", "98%"'],
+          ['<code>change</code>', 'string',  '—',       'Change label — e.g. "+12%", "−3"'],
+          ['<code>trend</code>',  'string',  'neutral', 'up · down · neutral'],
+          ['<code>center</code>', 'boolean', 'false',   'Centre-aligns value, label, and change'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,66 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { stepper } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/stepper')
+
+const STEPS = ['Account', 'Details', 'Payment', 'Review']
+
+export default {
+  route: '/components/stepper',
+  meta: {
+    title: 'Stepper — Pulse Docs',
+    description: 'Horizontal step progress indicator component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/stepper',
+    prev,
+    next,
+    name: 'stepper',
+    description: 'Horizontal step progress indicator. Completed steps show a check icon; the active step has an accent border; upcoming steps are muted. A connector line between steps fills with accent colour as progress advances.',
+    content: `
+
+      <h2 class="doc-h2" id="step1">Step 1 active</h2>
+      ${demo(
+        stepper({ steps: STEPS, current: 0 }),
+        `stepper({
+  steps:   ['Account', 'Details', 'Payment', 'Review'],
+  current: 0,
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="step2">Step 2 active</h2>
+      ${demo(
+        stepper({ steps: STEPS, current: 1 }),
+        `stepper({
+  steps:   ['Account', 'Details', 'Payment', 'Review'],
+  current: 1,
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="complete">All complete</h2>
+      ${demo(
+        stepper({ steps: STEPS, current: STEPS.length }),
+        `stepper({
+  steps:   ['Account', 'Details', 'Payment', 'Review'],
+  current: steps.length,   // past the last index = all complete
+})`,
+        { col: true }
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>steps</code>',   'string[]', '[]',  'Array of step label strings'],
+          ['<code>current</code>', 'number',   '0',   '0-based index of the active step. Pass <code>steps.length</code> to mark all steps complete.'],
+          ['<code>class</code>',   'string',   '—',   ''],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,45 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { badge, table as uiTable } from '../../../../src/ui/index.js'
+import { escHtml } from '../../../../src/html.js'
+
+const { prev, next } = prevNext('/components/table')
+
+export default {
+  route: '/components/table',
+  meta: {
+    title: 'Table — Pulse Docs',
+    description: 'Table component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/table',
+    prev,
+    next,
+    name: 'table',
+    description: 'The scroll wrapper has <code>role="region"</code> and <code>tabindex="0"</code> so keyboard users can scroll horizontally on narrow screens. Row cells are raw HTML slots — wrap user-supplied values in <code>escHtml()</code> when building them.',
+    content: `
+      ${demo(
+        uiTable({
+          caption: 'Team members',
+          headers: ['Name', 'Role', 'Status'],
+          rows: [
+            [escHtml('Alice Smith'), badge({ label: 'Admin',  variant: 'info'    }), badge({ label: 'Active',   variant: 'success' })],
+            [escHtml('Bob Jones'),   badge({ label: 'Editor', variant: 'default' }), badge({ label: 'Active',   variant: 'success' })],
+            [escHtml('Carol White'), badge({ label: 'Viewer', variant: 'default' }), badge({ label: 'Inactive', variant: 'default' })],
+          ],
+        }),
+        `table({
+  caption: 'Team members',
+  headers: ['Name', 'Role', 'Status'],
+  rows: server.users.map(u => [
+    escHtml(u.name),
+    badge({ label: u.role,   variant: u.role === 'admin' ? 'info' : 'default' }),
+    badge({ label: u.status, variant: u.active ? 'success' : 'default'        }),
+  ]),
+})`
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,49 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { testimonial } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/testimonial')
+
+export default {
+  route: '/components/testimonial',
+  meta: {
+    title: 'Testimonial — Pulse Docs',
+    description: 'Testimonial component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/testimonial',
+    prev,
+    next,
+    name: 'testimonial',
+    description: 'Customer quote card with star rating, avatar, and attribution. When <code>src</code> is omitted the avatar shows initials derived from <code>name</code>.',
+    content: `
+      ${demo(
+        `<div style="display:grid;grid-template-columns:1fr 1fr;gap:1.5rem">` +
+          testimonial({ quote: 'This is the fastest app I have ever used. It replaced three tools I was paying for.', name: 'Alice Marsh', role: 'Head of Product, Stride', rating: 5 }) +
+          testimonial({ quote: 'Switched from the competition six months ago and have not looked back once.', name: 'Ben Carter', role: 'Founder, Loopback', rating: 5 }) +
+        `</div>`,
+        `testimonial({
+  quote:  'This is the fastest app I have ever used.',
+  name:   'Alice Marsh',
+  role:   'Head of Product, Stride',
+  rating: 5,
+  src:    user.avatarUrl,  // optional — falls back to initials
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>quote</code>',  'string', '—', ''],
+          ['<code>name</code>',   'string', '—', 'Author name — also used for avatar initials'],
+          ['<code>role</code>',   'string', '—', ''],
+          ['<code>src</code>',    'string', '—', 'Avatar image URL; omit to show initials'],
+          ['<code>rating</code>', 'number', '0', '1–5 stars; omit or set 0 to hide'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,31 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { textarea } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/textarea')
+
+export default {
+  route: '/components/textarea',
+  meta: {
+    title: 'Textarea — Pulse Docs',
+    description: 'Textarea component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/textarea',
+    prev,
+    next,
+    name: 'textarea',
+    description: 'Multi-line text input with label, hint, and error support. Wired up identically to <code>input</code> — <code>for</code>/<code>id</code> and <code>aria-describedby</code> are derived from <code>name</code>.',
+    content: `
+      ${demo(
+        textarea({ name: 'bio', label: 'Bio', placeholder: 'Tell us about yourself…', hint: 'Max 500 characters', rows: 3 }) +
+        textarea({ name: 'note', label: 'Note', value: 'hello world', error: 'Note is too long', rows: 3 }),
+        `textarea({ name: 'bio',  label: 'Bio',  placeholder: 'Tell us about yourself…', hint: 'Max 500 characters' })
+textarea({ name: 'note', label: 'Note', value: state.note, error: server.errors.note, rows: 6 })`,
+        { col: true }
+      )}
+    `,
+  }),
+}