@invisibleloop/pulse 0.12.2 → 0.14.1

package/docs/src/pages/testing.js

@@ -112,7 +112,7 @@ const result = await render(productSpec, {
       )}
 
       ${section('selectors', 'Supported selectors')}
-      <p>The selector engine supports the most common patterns. Descendant combinators (<code>div p</code>) are not supported — use <code>element.findAll()</code> to search within a matched element instead.</p>
+      <p>The selector engine supports the most common CSS patterns including descendant combinators (<code>div p</code>, <code>.parent li</code>). Descendant selectors match the rightmost token within the ancestor context — if no ancestors match, the result is empty (count 0).</p>
       ${table(
         ['Selector', 'Example', 'Matches'],
         [
@@ -122,6 +122,7 @@ const result = await render(productSpec, {
           ['Attribute present','<code>[disabled]</code>',              'Elements with a <code>disabled</code> attribute'],
           ['Attribute value',  '<code>[type="submit"]</code>',         'Elements where <code>type</code> equals <code>submit</code>'],
           ['Compound',         '<code>button.primary[disabled]</code>', 'All conditions on the same element'],
+          ['Descendant',       '<code>tbody tr</code>',                '<code>&lt;tr&gt;</code> elements inside <code>&lt;tbody&gt;</code>'],
         ]
       )}
       ${codeBlock(highlight(`result.has('button')                         // any <button>

package/examples/andypixel.css

@@ -0,0 +1,237 @@
+/*
+ * andypixel.css — Andy Pixel blog article example
+ *
+ * Token definitions (hex values) + layout styles (var() only).
+ * Orange accent palette — editorial light theme.
+ */
+
+/* ─── Token definitions ──────────────────────────────────────── */
+
+[data-theme="light"] {
+  --accent:       #f97316;
+  --accent-hover: #ea6c0a;
+  --accent-dim:   #fff3e8;
+  --surface-2:    #f0f0f0;
+  --border:       #e5e5e5;
+  --muted-bg:     #f5f5f5;
+
+  /* Code block dark-shell tokens — defined here so app.css stays hex-free */
+  --ap-code-shell:      #1e1e1e;
+  --ap-code-text:       #d4d4d4;
+  --ap-btn-dark:        #1a1a1a;
+  --ap-btn-dark-hover:  #333333;
+}
+
+/* ─── Base ───────────────────────────────────────────────────── */
+
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: var(--ui-font, system-ui, sans-serif);
+  line-height: 1.6;
+  background: var(--ui-bg);
+  color: var(--ui-text);
+}
+
+/* ─── Contrast fixes ─────────────────────────────────────────── */
+
+/* Badge: muted on surface-2 fails WCAG AA at small size */
+.ui-badge--default {
+  color: var(--ui-text);
+}
+
+/* Inline code: accent on surface-2 fails WCAG AA */
+.ui-prose code {
+  color: var(--ui-text);
+}
+
+/* ─── Reading column ─────────────────────────────────────────── */
+
+.ap-reading-col {
+  max-width: 72ch;
+  margin-left: auto;
+  margin-right: auto;
+  padding-left: var(--ui-space-6);
+  padding-right: var(--ui-space-6);
+}
+
+/* ─── Article header ─────────────────────────────────────────── */
+
+.ap-article-header {
+  padding: var(--ui-space-12) 0 var(--ui-space-8);
+  border-bottom: 3px solid var(--ui-accent);
+  margin-bottom: var(--ui-space-10);
+}
+
+.ap-article-meta {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  flex-wrap: wrap;
+  margin-bottom: var(--ui-space-5);
+}
+
+.ap-article-title {
+  font-family: var(--ui-font-display, system-ui, serif);
+  font-size: clamp(2rem, 5vw, 3.25rem);
+  font-weight: 800;
+  line-height: 1.1;
+  letter-spacing: -0.02em;
+  color: var(--ui-text);
+  margin-bottom: var(--ui-space-4);
+}
+
+.ap-article-subtitle {
+  font-size: var(--ui-text-xl);
+  color: var(--ui-muted);
+  line-height: 1.55;
+  margin-bottom: var(--ui-space-6);
+  max-width: 56ch;
+}
+
+.ap-article-author-strip {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-3);
+}
+
+/* ─── Article body ───────────────────────────────────────────── */
+
+.ap-article-body {
+  padding-bottom: var(--ui-space-12);
+}
+
+.ap-article-lead {
+  font-size: var(--ui-text-xl) !important;
+  line-height: 1.65 !important;
+  color: var(--ui-text) !important;
+}
+
+/* ─── Code block ─────────────────────────────────────────────── */
+
+.ap-code-block {
+  margin: var(--ui-space-6) 0;
+  border-radius: var(--ui-radius);
+  overflow: hidden;
+  border: 1px solid var(--ui-border);
+}
+
+.ap-code-block__header {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  padding: var(--ui-space-2) var(--ui-space-4);
+  background: var(--ui-text);
+  color: var(--ui-accent);
+  font-family: var(--ui-mono, monospace);
+  font-size: var(--ui-text-sm);
+}
+
+.ap-code-block__pre {
+  background: var(--ap-code-shell);
+  padding: var(--ui-space-5) var(--ui-space-6);
+  overflow-x: auto;
+  margin: 0;
+}
+
+.ap-code-block__code {
+  font-family: var(--ui-mono, monospace);
+  font-size: var(--ui-text-sm);
+  line-height: 1.75;
+  color: var(--ap-code-text);
+}
+
+/* ─── Pullquote ──────────────────────────────────────────────── */
+
+.ap-pullquote {
+  margin: var(--ui-space-8) 0;
+  padding: var(--ui-space-5) var(--ui-space-6);
+  border-left: 4px solid var(--ui-accent);
+  background: var(--accent-dim);
+  border-radius: 0 var(--ui-radius) var(--ui-radius) 0;
+}
+
+.ap-pullquote p {
+  font-family: var(--ui-font-display, system-ui, serif);
+  font-size: var(--ui-text-xl);
+  font-style: italic;
+  color: var(--ui-text);
+  margin: 0;
+  line-height: 1.55;
+}
+
+/* ─── Author bio ─────────────────────────────────────────────── */
+
+.ap-author-bio-wrap {
+  border-top: 1px solid var(--ui-border);
+  border-bottom: 1px solid var(--ui-border);
+  padding: var(--ui-space-8) 0;
+  margin-bottom: var(--ui-space-10);
+}
+
+.ap-author-bio {
+  display: flex;
+  gap: var(--ui-space-4);
+  align-items: flex-start;
+}
+
+.ap-author-bio__name {
+  font-weight: 700;
+  font-size: var(--ui-text-base);
+  margin-bottom: var(--ui-space-1);
+}
+
+/* ─── Newsletter ─────────────────────────────────────────────── */
+
+.ap-newsletter-section {
+  max-width: 540px;
+  margin: 0 auto;
+  text-align: center;
+  padding: var(--ui-space-12) var(--ui-space-6);
+  border-top: 3px solid var(--ui-accent);
+}
+
+.ap-newsletter-eyebrow {
+  font-family: var(--ui-mono, monospace);
+  font-size: var(--ui-text-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--ui-text);
+  margin-bottom: var(--ui-space-2);
+}
+
+.ap-newsletter-title {
+  font-family: var(--ui-font-display, system-ui, serif);
+  font-size: clamp(1.5rem, 4vw, 2.25rem);
+  font-weight: 800;
+  letter-spacing: -0.02em;
+  color: var(--ui-text);
+  margin-bottom: var(--ui-space-3);
+  line-height: 1.15;
+}
+
+.ap-newsletter-form {
+  display: flex;
+  gap: var(--ui-space-2);
+  margin-top: var(--ui-space-6);
+  flex-wrap: wrap;
+  justify-content: center;
+}
+
+/* Orange bg on small text fails WCAG AA — use near-black for contrast (15:1) */
+.ap-newsletter-form .ui-btn--primary {
+  background: var(--ap-btn-dark);
+}
+.ap-newsletter-form .ui-btn--primary:hover {
+  background: var(--ap-btn-dark-hover);
+}
+
+.ap-newsletter-error {
+  color: var(--ui-error, #dc2626);
+  margin-top: var(--ui-space-3);
+}
+
+.ap-newsletter-success {
+  padding: var(--ui-space-12) var(--ui-space-6);
+  text-align: center;
+}

package/examples/andypixel.js

@@ -0,0 +1,258 @@
+/**
+ * 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'
+
+// ---------------------------------------------------------------------------
+// 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: '/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', '/examples/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>
+  `,
+
+  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 }],
+      }),
+    },
+  },
+}