@invisibleloop/pulse 0.12.3 → 0.14.2

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

@@ -0,0 +1,76 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { marquee } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/marquee')
+
+const LOGOS = [
+  `<span style="font-weight:600;font-size:.875rem;opacity:.6;white-space:nowrap;letter-spacing:.5px">ACME&nbsp;CORP</span>`,
+  `<span style="font-weight:600;font-size:.875rem;opacity:.6;white-space:nowrap;letter-spacing:.5px">NOVA&nbsp;INC</span>`,
+  `<span style="font-weight:600;font-size:.875rem;opacity:.6;white-space:nowrap;letter-spacing:.5px">STELLAR</span>`,
+  `<span style="font-weight:600;font-size:.875rem;opacity:.6;white-space:nowrap;letter-spacing:.5px">ORBIT&nbsp;CO</span>`,
+  `<span style="font-weight:600;font-size:.875rem;opacity:.6;white-space:nowrap;letter-spacing:.5px">HELIX</span>`,
+  `<span style="font-weight:600;font-size:.875rem;opacity:.6;white-space:nowrap;letter-spacing:.5px">PRISM&nbsp;AI</span>`,
+]
+
+export default {
+  route: '/components/marquee',
+  meta: {
+    title: 'Marquee — Pulse Docs',
+    description: 'CSS-only infinite scrolling strip for logo clouds, trust badges, and tag lists in Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  view: () => renderComponentPage({
+    currentHref: '/components/marquee',
+    prev,
+    next,
+    name: 'marquee',
+    description: 'CSS-only infinite scrolling strip. No JavaScript — pure CSS animation. Use for logo clouds, press mentions, trust badges, or feature tags. <strong>The strip is hidden from screen readers</strong> (<code>aria-hidden="true"</code>) — it is decorative, not content.',
+    content: `
+      <h2 class="doc-h2" id="logos">Logo cloud</h2>
+      <p>A common use-case: a strip of client or partner logos scrolling slowly from right to left.</p>
+      ${demo(
+        marquee({ items: LOGOS }),
+        `marquee({
+  items: ['<img src="/logos/acme.svg" alt="">',
+          '<img src="/logos/nova.svg" alt="">',
+          '<img src="/logos/helix.svg" alt="">'],
+})`
+      )}
+
+      <h2 class="doc-h2" id="slow">Custom speed</h2>
+      <p>The default <code>speed</code> is 30 seconds per loop. Slow it down for fewer items, or speed it up for a more energetic feel.</p>
+      ${demo(
+        marquee({ items: LOGOS, speed: 60 }),
+        `marquee({ items, speed: 60 })  // slow`
+      )}
+
+      <h2 class="doc-h2" id="direction">Direction</h2>
+      <p>Set <code>direction: 'right'</code> to scroll right-to-left instead.</p>
+      ${demo(
+        marquee({ items: LOGOS, direction: 'right' }),
+        `marquee({ items, direction: 'right' })`
+      )}
+
+      <h2 class="doc-h2" id="no-fade">Without fade</h2>
+      <p>Edge fading is on by default. Disable it with <code>fade: false</code>.</p>
+      ${demo(
+        marquee({ items: LOGOS, fade: false }),
+        `marquee({ items, fade: false })`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', 'Description'],
+        [
+          ['<code>items</code>',     'string[]',  '[]',         'Array of raw HTML strings — images, badges, or text'],
+          ['<code>speed</code>',     'number',    '30',         'Duration (seconds) for one full loop. Lower = faster.'],
+          ['<code>gap</code>',       'string',    "'lg'",       "'sm' · 'md' · 'lg'"],
+          ['<code>direction</code>', 'string',    "'left'",     "'left' (right-to-left scroll) or 'right'"],
+          ['<code>pause</code>',     'boolean',   'true',       'Pause animation on hover'],
+          ['<code>fade</code>',      'boolean',   'true',       'Apply gradient mask to fade the left and right edges'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,74 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { photoCard } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/photo-card')
+
+export default {
+  route: '/components/photo-card',
+  meta: {
+    title: 'Photo Card — Pulse Docs',
+    description: 'Polaroid-style photo card with optional tilt and caption for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  view: () => renderComponentPage({
+    currentHref: '/components/photo-card',
+    prev,
+    next,
+    name: 'photoCard',
+    description: 'Polaroid-style photo card with a border, white padding, optional caption, and CSS tilt. Ideal for "meet the team" sections, testimonial portraits, and lifestyle photography.',
+    content: `
+      <h2 class="doc-h2" id="basic">Basic photo card</h2>
+      <p>A framed image with a white polaroid border.</p>
+      ${demo(
+        `<div style="display:flex;gap:2rem;align-items:center;justify-content:center;flex-wrap:wrap;padding:2rem">` +
+        photoCard({ src: '/img/placeholder-square.svg', alt: 'Team member portrait', caption: 'Sarah, Designer' }) +
+        `</div>`,
+        `photoCard({
+  src:     '/img/team/sarah.jpg',
+  alt:     'Sarah, Designer',
+  caption: 'Sarah, Designer',
+})`
+      )}
+
+      <h2 class="doc-h2" id="tilt">With tilt</h2>
+      <p>Pass a <code>tilt</code> value (degrees) to rotate the card. Negative values lean left, positive values lean right. Useful for giving sections a hand-placed, organic feeling.</p>
+      ${demo(
+        `<div style="display:flex;gap:2rem;align-items:center;justify-content:center;flex-wrap:wrap;padding:2rem">` +
+        photoCard({ src: '/img/placeholder-square.svg', alt: 'Team photo',  caption: 'Andy, founder',    tilt: -2 }) +
+        photoCard({ src: '/img/placeholder-tall.svg',   alt: 'Office dog',  caption: 'Biscuit, mascot',  tilt: 1.5 }) +
+        photoCard({ src: '/img/placeholder-square.svg', alt: 'Team photo',  caption: 'Jen, engineering', tilt: -1 }) +
+        `</div>`,
+        `photoCard({ src, alt: 'Andy, founder',    caption: 'Andy, founder',    tilt: -2  })
+photoCard({ src, alt: 'Office dog',   caption: 'Biscuit, mascot', tilt: 1.5 })
+photoCard({ src, alt: 'Jen, engineering', caption: 'Jen, engineering', tilt: -1 })`
+      )}
+
+      <h2 class="doc-h2" id="ratios">Aspect ratios</h2>
+      <p>Set <code>ratio</code> to control the crop. <code>'1/1'</code> for square portraits, <code>'4/3'</code> for landscape shots.</p>
+      ${demo(
+        `<div style="display:flex;gap:2rem;align-items:flex-start;justify-content:center;flex-wrap:wrap;padding:2rem">` +
+        photoCard({ src: '/img/placeholder-square.svg',    alt: 'Square crop',    caption: "ratio: '1/1'",   ratio: '1/1',  tilt: 1 }) +
+        photoCard({ src: '/img/placeholder-landscape.svg', alt: 'Landscape crop', caption: "ratio: '4/3'",   ratio: '4/3',  tilt: -1.5 }) +
+        photoCard({ src: '/img/placeholder-tall.svg',      alt: 'Tall crop',      caption: "ratio: '3/4'",   ratio: '3/4',  tilt: 2 }) +
+        `</div>`,
+        `photoCard({ src, alt: 'Square portrait',    ratio: '1/1', tilt: 1 })
+photoCard({ src, alt: 'Landscape photo',    ratio: '4/3', tilt: -1.5 })
+photoCard({ src, alt: 'Tall portrait',      ratio: '3/4', tilt: 2 })`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', 'Description'],
+        [
+          ['<code>src</code>',     'string',  '—',       'Image source URL'],
+          ['<code>alt</code>',     'string',  '—',       'Alt text — required for accessibility'],
+          ['<code>caption</code>', 'string',  '—',       'Caption text below the photo'],
+          ['<code>tilt</code>',    'number',  '0',       'CSS rotate degrees — negative leans left, positive leans right. 0 = no tilt'],
+          ['<code>ratio</code>',   'string',  "'4/3'",   'CSS aspect-ratio for the image crop'],
+          ['<code>rounded</code>', 'boolean', 'false',   'Rounds the image corners inside the card frame'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -39,11 +39,50 @@ export default {
 })`
       )}
 
+      <h2 class="doc-h2" id="diagonal">Diagonal variant</h2>
+      <p>The <code>diagonal</code> variant clips the bottom edge to a slanted angle, creating a layered stacking effect when multiple sections follow each other. The section after it should start with no top gap.</p>
+      ${demo(
+        uiSection({
+          variant: 'diagonal',
+          eyebrow: 'Diagonal',
+          title: 'Slanted bottom edge.',
+          align: 'center',
+          content: container({ size: 'md', content: '<p style="text-align:center;color:var(--ui-muted)">Content here</p>' }),
+        }),
+        `section({ variant: 'diagonal', title: 'Slanted edge', align: 'center', content })`
+      )}
+
+      <h2 class="doc-h2" id="paper">Paper variant</h2>
+      <p>The <code>paper</code> variant applies a subtle off-white background and slight inset box shadow — useful for content sections that need to feel warmer and tactile.</p>
+      ${demo(
+        uiSection({
+          variant: 'paper',
+          eyebrow: 'Paper',
+          title: 'Warm and tactile.',
+          align: 'center',
+          content: container({ size: 'md', content: '<p style="text-align:center;color:var(--ui-muted)">Content here</p>' }),
+        }),
+        `section({ variant: 'paper', title: 'Warm and tactile', align: 'center', content })`
+      )}
+
+      <h2 class="doc-h2" id="spotlight">Spotlight variant</h2>
+      <p>The <code>spotlight</code> variant adds a radial gradient light source at the top centre — gives the section a dramatic, focused feeling.</p>
+      ${demo(
+        uiSection({
+          variant: 'spotlight',
+          eyebrow: 'Spotlight',
+          title: 'Dramatically focused.',
+          align: 'center',
+          content: container({ size: 'md', content: '<p style="text-align:center;color:var(--ui-muted)">Content here</p>' }),
+        }),
+        `section({ variant: 'spotlight', title: 'Dramatically focused', align: 'center', content })`
+      )}
+
       ${table(
         ['Prop', 'Type', 'Default', 'Description'],
         [
           ['<code>content</code>',  'string (HTML)', '—',         'Raw HTML slot'],
-          ['<code>variant</code>',  'string',        "'default'", "'default' · 'alt' · 'dark'"],
+          ['<code>variant</code>',  'string',        "'default'", "'default' · 'alt' · 'dark' · 'diagonal' · 'paper' · 'spotlight'"],
           ['<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'],

package/docs/src/pages/meta.js

@@ -126,6 +126,32 @@ meta: {
 }`, 'js'))}
       ${callout('note', 'For maximum performance, host your own fonts rather than using Google Fonts. External stylesheet requests add render-blocking latency and a DNS lookup.')}
 
+      ${section('vibe', 'Personality presets (meta.vibe)')}
+      <p>Set <code>meta.vibe</code> to apply a personality preset that adjusts typography, border radius, and letter-spacing across all components on the page. The preset sets a <code>data-vibe</code> attribute on <code>&lt;body&gt;</code> — pair it with a <code>theme.css</code> for complete brand expression.</p>
+      ${codeBlock(highlight(`export default {
+  route: '/landing',
+  meta: {
+    vibe:   'playful',
+    styles: ['/pulse-ui.css', '/theme.css'],
+  },
+}`, 'js'))}
+      ${table(
+        ['Vibe', 'Character', 'Best for'],
+        [
+          ['<code>warm</code>',       'Friendly, rounded (14px), humanist feel',                   'Local businesses, wellness, food, services'],
+          ['<code>editorial</code>',  'Serif display, zero radius, tight tracking',                  'Publications, blogs, journalism, literary'],
+          ['<code>playful</code>',    'Extra-large radius (22px), loose spacing',                    'Consumer apps, kids, lifestyle, creators'],
+          ['<code>minimal</code>',    'Ultra-low radius (2px), refined whitespace',                  'Portfolios, luxury, developer tools'],
+          ['<code>bold</code>',       'Tight tracking, strong presence',                             'Agencies, startups, sports'],
+          ['<code>brutalist</code>',  'Zero radius, oversized Arial Black / Impact headings',         'Art, fashion, counter-culture, zines'],
+          ['<code>retro</code>',      'Slab serif, medium radius (8px), nostalgic geometry',          'Craft, breweries, vintage, heritage brands'],
+          ['<code>corporate</code>',  'Conservative radius (4px), tight tracking, professional',     'B2B, finance, legal, consultancies'],
+          ['<code>neon</code>',       'Monospace headline, futuristic, sharp edges',                  'Gaming, crypto, dark-tech, cyberpunk'],
+          ['<code>paper</code>',      'Organic radius (10px), serif body, tactile feel',              'Journals, bookshops, newsletters, diaries'],
+        ]
+      )}
+      ${callout('tip', 'Vibe only adjusts shape and type tokens — it does not set colours. Add a <code>theme.css</code> that defines <code>--ui-accent</code>, <code>--color-bg</code>, and other colour tokens to complete the personality.')}
+
       ${section('seo-tips', 'SEO tips')}
       <ul>
         <li>Write a unique <code>title</code> and <code>description</code> for every page — duplicate metadata prevents pages from competing in search results.</li>

package/docs/src/pages/templates/andypixel.js

@@ -0,0 +1,260 @@
+/**
+ * Pulse — Andy Pixel example
+ *
+ * Demonstrates:
+ *   - Blog article layout — editorial light-theme, prose-width reading column
+ *   - Composing nav, badge, avatar, prose, input, button, footer
+ *   - Custom code block component (dark pre with labelled header)
+ *   - Blockquote / pullquote styling
+ *   - Async newsletter subscribe action with success/error state
+ *   - Author bio strip below article content
+ *   - iconCode, iconCheck from icons.js
+ *   - Orange accent palette with WCAG contrast fixes for badge + inline code
+ *
+ * Run: node examples/dev.server.js  →  http://localhost:3001/andypixel
+ */
+
+import {
+  nav,
+  footer,
+  badge,
+  button,
+  avatar,
+  prose,
+  input,
+} from '../../../../src/ui/index.js'
+
+import { iconCode, iconCheck } from '../../../../src/ui/icons.js'
+import { asset } from '../../lib/layout.js'
+
+// ---------------------------------------------------------------------------
+// Code block helper
+// ---------------------------------------------------------------------------
+
+function codeBlock({ filename, code }) {
+  return `
+    <div class="ap-code-block" role="figure" aria-label="Code example: ${filename}">
+      <div class="ap-code-block__header">
+        ${iconCode({ size: 14 })}
+        <span>${filename}</span>
+      </div>
+      <pre class="ap-code-block__pre"><code class="ap-code-block__code">${code}</code></pre>
+    </div>
+  `
+}
+
+// ---------------------------------------------------------------------------
+// Spec
+// ---------------------------------------------------------------------------
+
+export default {
+  route: '/templates/andypixel',
+
+  meta: {
+    title:       'JavaScript Proxies: The Hidden Superpower \u2014 Andy Pixel',
+    description: 'Discover how JavaScript Proxies let you intercept and redefine fundamental operations on objects.',
+    styles:      ['/pulse-ui.css', '/andypixel.css'],
+    theme:       'light',
+  },
+
+  state: {
+    status: 'idle',
+  },
+
+  view: (state) => `
+    <main id="main-content">
+
+      ${nav({
+        logo:  'Andy Pixel',
+        links: [
+          { label: 'Blog',     href: '#blog'     },
+          { label: 'Projects', href: '#projects' },
+          { label: 'About',    href: '#about'    },
+        ],
+      })}
+
+      <article>
+
+        <header class="ap-article-header">
+          <div class="ap-reading-col">
+
+            <div class="ap-article-meta">
+              ${badge({ label: 'JavaScript' })}
+              ${badge({ label: 'Advanced' })}
+              <span class="u-text-muted u-text-sm">\u00b7 May 28, 2026 \u00b7 8 min read</span>
+            </div>
+
+            <h1 class="ap-article-title">
+              JavaScript Proxies: The Hidden Superpower You\u2019re Not Using
+            </h1>
+
+            <p class="ap-article-subtitle">
+              Intercept, transform, and observe objects at a fundamental level \u2014
+              without touching the source.
+            </p>
+
+            <div class="ap-article-author-strip">
+              ${avatar({ name: 'Andy Pixel', size: 'sm' })}
+              <div>
+                <p class="u-text-sm u-font-bold">Andy Pixel</p>
+                <p class="u-text-sm u-text-muted">Frontend Engineer</p>
+              </div>
+            </div>
+
+          </div>
+        </header>
+
+        <div class="ap-article-body ap-reading-col">
+
+          ${prose({ content: `
+            <p class="ap-article-lead">If you\u2019ve ever wanted to validate object properties automatically,
+            track changes reactively, or build a mock API client that feels real \u2014 the
+            <code>Proxy</code> object is your tool. Yet somehow it flies under the radar
+            for most developers.</p>
+
+            <p>Introduced in ES2015, <code>Proxy</code> wraps an object and lets you intercept
+            fundamental operations \u2014 property reads, writes, deletions, and more \u2014 via
+            \u201ctraps\u201d defined on a handler object.</p>
+
+            <h2>The anatomy of a Proxy</h2>
+
+            <p>A Proxy takes two arguments: the <strong>target</strong> (the object being wrapped)
+            and the <strong>handler</strong> (an object defining which operations to intercept).
+            Every interceptable operation has a corresponding trap method on the handler.</p>
+          ` })}
+
+          ${codeBlock({
+            filename: 'proxy-basics.js',
+            code: `const handler = {
+  get(target, key) {
+    return key in target
+      ? target[key]
+      : \`Property "\${key}" doesn\u2019t exist\`
+  },
+  set(target, key, value) {
+    if (typeof value !== 'number') {
+      throw new TypeError('Only numbers allowed')
+    }
+    target[key] = value
+    return true
+  }
+}
+
+const proxy = new Proxy({}, handler)
+proxy.score = 42        // \u2713 works
+proxy.score = 'oops'   // \u2717 TypeError`,
+          })}
+
+          ${prose({ content: `
+            <p>The <code>get</code> trap runs on every property access. The <code>set</code> trap
+            intercepts every assignment. Return <code>true</code> from <code>set</code> to signal
+            success \u2014 otherwise you\u2019ll get a <code>TypeError</code> in strict mode.</p>
+
+            <h2>Real-world use cases</h2>
+
+            <p>The real power isn\u2019t abstract. Proxy unlocks patterns that are otherwise
+            painful or impossible.</p>
+          ` })}
+
+          <blockquote class="ap-pullquote">
+            <p>\u201cA Proxy doesn\u2019t change what your object <em>is</em> \u2014 it changes what your
+            object <em>does</em> when the runtime touches it.\u201d</p>
+          </blockquote>
+
+          ${prose({ content: `
+            <h3>Reactive state</h3>
+            <p>Vue 3\u2019s reactivity system is built entirely on Proxy. When you access a reactive
+            property, Vue\u2019s <code>get</code> trap tracks the dependency. When you mutate it,
+            the <code>set</code> trap schedules re-renders. No syntax overhead. Just assignment.</p>
+
+            <h3>Input validation</h3>
+            <p>Instead of scattering guard clauses through your codebase, centralise validation
+            in a Proxy handler. The contract lives in one place. Every consumer benefits
+            automatically.</p>
+
+            <h3>API mocking</h3>
+            <p>Wrap a plain object in a Proxy that intercepts property access and returns async
+            functions. You get a fully-typed mock client that mirrors your real API surface \u2014
+            without any code generation.</p>
+
+            <h2>Performance considerations</h2>
+
+            <p>Proxies are not free. Every trap fires a function call. In tight loops over large
+            collections, this adds up. Benchmark before you commit. For most use cases \u2014 form
+            state, reactive stores, config validation \u2014 the overhead is completely negligible.</p>
+
+            <p>The V8 team has steadily optimised Proxy performance since ES2015. Don\u2019t avoid
+            Proxy out of dated fear \u2014 measure it first.</p>
+          ` })}
+
+        </div>
+
+      </article>
+
+      <div class="ap-author-bio-wrap">
+        <div class="ap-reading-col">
+          <div class="ap-author-bio">
+            ${avatar({ name: 'Andy Pixel', size: 'lg' })}
+            <div class="ap-author-bio__text">
+              <p class="ap-author-bio__name">Andy Pixel</p>
+              <p class="u-text-muted u-text-sm">
+                Frontend engineer obsessed with the web platform. Writing about JavaScript,
+                CSS, and creative code. Building things at the edge of what browsers can do.
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      ${ state.status === 'success'
+        ? `<div class="ap-newsletter-success">
+            <p class="u-font-bold u-text-lg">${iconCheck({ size: 20, class: 'u-inline' })} You\u2019re in!</p>
+            <p class="u-text-muted u-mt-2">Next article lands in your inbox.</p>
+          </div>`
+        : `<div class="ap-newsletter-section">
+            <p class="ap-newsletter-eyebrow">Stay in the loop</p>
+            <h2 class="ap-newsletter-title">More like this, in your inbox.</h2>
+            <p class="u-text-muted">
+              Deep-dives on JavaScript, the web platform, and frontend engineering \u2014
+              whenever I publish. No noise.
+            </p>
+            ${ state.status === 'error'
+              ? `<p class="ap-newsletter-error u-mt-3">Something went wrong. Please try again.</p>`
+              : '' }
+            <form class="ap-newsletter-form" data-action="subscribe">
+              ${input({ type: 'email', name: 'email', placeholder: 'you@example.com', label: 'Email address', attrs: { autocomplete: 'email' } })}
+              ${button({ label: 'Subscribe', variant: 'primary', attrs: { type: 'submit' } })}
+            </form>
+          </div>`
+      }
+
+      ${footer({
+        logo:  'Andy Pixel',
+        links: [
+          { label: 'Blog',     href: '#blog'     },
+          { label: 'Projects', href: '#projects' },
+          { label: 'About',    href: '#about'    },
+          { label: 'RSS',      href: '#feed'     },
+        ],
+      })}
+
+    </main>
+    <script src="${asset('/pulse-ui.js')}" defer></script>
+  `,
+
+  actions: {
+    subscribe: {
+      onStart: (state, formData) => ({
+        status: 'loading',
+      }),
+      run: async (state, serverState, formData) => {
+        // Newsletter subscription would call an API here
+      },
+      onSuccess: (state) => ({ status: 'success' }),
+      onError:   (state, err) => ({
+        status: 'error',
+        errors: err?.validation ?? [{ message: err.message }],
+      }),
+    },
+  },
+}