zero-query 0.9.7 → 0.9.8

package/cli/scaffold/{app → minimal/app}/app.js

@@ -1,24 +1,26 @@
-// app/app.js — application entry point
+// app.js — Application entry point
 //
-// This file bootstraps the zQuery app: imports all components,
-// sets up routing, wires the responsive nav, and demonstrates
-// several core APIs: $.router, $.ready, $.bus, $.on, and $.storage.
+// Bootstraps the app: imports components, sets up routing,
+// and wires the responsive sidebar.
+//
+// Key APIs used:
+//   $.router  — SPA navigation (history mode)
+//   $.ready   — run after DOM is loaded
+//   $.on      — global delegated event listeners
+//   $.storage — localStorage wrapper
 
 import './store.js';
 import './components/home.js';
 import './components/counter.js';
-import './components/todos.js';
-import './components/api-demo.js';
 import './components/about.js';
-import './components/contacts/contacts.js';
 import './components/not-found.js';
 import { routes } from './routes.js';
 
 // ---------------------------------------------------------------------------
-// Router — SPA navigation with history mode
+// Router
 // ---------------------------------------------------------------------------
 const router = $.router({
-  el: '#app',   //@ Mount point (Set in index.html)
+  el: '#app',
   routes,
   fallback: 'not-found',
   mode: 'history'
@@ -48,47 +50,43 @@ function toggleMobileMenu(open) {
 
 function closeMobileMenu() { toggleMobileMenu(false); }
 
-// $.on — global delegated event listeners
 $.on('click', '#menu-toggle', () => toggleMobileMenu(!$sidebar.hasClass('open')));
 $.on('click', '#overlay', closeMobileMenu);
-
-// Close sidebar on Escape key — using $.on direct (no selector needed)
-$.on('keydown', (e) => {
-  if (e.key === 'Escape') closeMobileMenu();
-});
-
-// ---------------------------------------------------------------------------
-// Toast notification system via $.bus (event bus)
-// ---------------------------------------------------------------------------
-// Any component can emit: $.bus.emit('toast', { message, type })
-// Types: 'success', 'error', 'info'
-$.bus.on('toast', ({ message, type = 'info' }) => {
-  const toast = $.create('div')
-    .addClass('toast', `toast-${type}`)
-    .text(message)
-    .appendTo('#toasts');
-  // Auto-remove after 3 seconds
-  setTimeout(() => {
-    toast.addClass('toast-exit');
-    setTimeout(() => toast.remove(), 300);
-  }, 3000);
-});
+$.on('keydown', (e) => { if (e.key === 'Escape') closeMobileMenu(); });
 
 // ---------------------------------------------------------------------------
-// On DOM ready — final setup
+// On DOM ready
 // ---------------------------------------------------------------------------
 $.ready(() => {
   // Display version in the sidebar footer
-  const versionEl = $.id('nav-version');
-  if (versionEl) versionEl.textContent = 'v' + $.version;
+  $('#nav-version').text('v' + $.version);
 
-  // Restore last theme from localStorage ($.storage)
-  const savedTheme = $.storage.get('theme');
-  if (savedTheme) document.documentElement.setAttribute('data-theme', savedTheme);
+  // Theme: restore saved preference or auto-detect from system
+  const saved = $.storage.get('theme');
+  const preference = saved || 'system';
+  applyTheme(preference);
 
-  // Set active link on initial load
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+    const current = $.storage.get('theme') || 'system';
+    if (current === 'system') applyTheme('system');
+  });
+
+  // Highlight the active link on initial load
   const current = window.location.pathname;
   $.all(`.nav-link[z-link="${current}"]`).addClass('active');
 
   console.log('⚡ {{NAME}} — powered by zQuery v' + $.version);
 });
+
+// ---------------------------------------------------------------------------
+// Theme helper
+// ---------------------------------------------------------------------------
+function applyTheme(preference) {
+  let resolved = preference;
+  if (preference === 'system') {
+    resolved = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+  $('html').attr('data-theme', resolved);
+}
+
+window.__applyTheme = applyTheme;

package/cli/scaffold/minimal/app/components/about.js

@@ -0,0 +1,68 @@
+// about.js — About page with theme switcher
+//
+// Features used:
+//   $.storage   — localStorage wrapper (get / set)
+//   $.version   — library version string
+//   data-theme  — dark / light theming
+
+$.component('about-page', {
+  styles: `
+    .theme-switch   { display: inline-flex; border-radius: var(--radius); overflow: hidden;
+                      border: 1px solid var(--border); background: var(--bg); }
+    .theme-btn      { padding: 0.45rem 1rem; font-size: 0.82rem; font-weight: 500;
+                      background: transparent; border: none; color: var(--text-muted);
+                      cursor: pointer; transition: all .15s ease; font-family: inherit; }
+    .theme-btn:hover  { color: var(--text); background: var(--bg-hover); }
+    .theme-btn.active { background: var(--accent-soft); color: var(--accent); font-weight: 600; }
+    .theme-btn + .theme-btn { border-left: 1px solid var(--border); }
+
+    .next-steps     { padding-left: 1.25rem; }
+    .next-steps li  { margin-bottom: 0.4rem; font-size: 0.9rem; color: var(--text-muted); }
+    .next-steps a   { color: var(--accent); }
+  `,
+
+  state: () => ({
+    theme: 'system',
+  }),
+
+  mounted() {
+    this.state.theme = $.storage.get('theme') || 'system';
+  },
+
+  setTheme(mode) {
+    this.state.theme = mode;
+    $.storage.set('theme', mode);
+    window.__applyTheme(mode);
+  },
+
+  render() {
+    const t = this.state.theme;
+    return `
+      <div class="page-header">
+        <h1>About</h1>
+        <p class="subtitle">zQuery v${$.version} — zero-dependency frontend micro-library.</p>
+      </div>
+
+      <div class="card">
+        <h3>Theme</h3>
+        <p>Choose your preferred appearance. <strong>System</strong> follows your OS setting.</p>
+        <div class="theme-switch">
+          <button class="theme-btn ${t === 'system' ? 'active' : ''}" @click="setTheme('system')">System</button>
+          <button class="theme-btn ${t === 'dark' ? 'active' : ''}" @click="setTheme('dark')">Dark</button>
+          <button class="theme-btn ${t === 'light' ? 'active' : ''}" @click="setTheme('light')">Light</button>
+        </div>
+      </div>
+
+      <div class="card">
+        <h3>Next Steps</h3>
+        <ul class="next-steps">
+          <li>Read the <a href="https://z-query.com/docs" target="_blank" rel="noopener">full documentation</a></li>
+          <li>Explore the <a href="https://github.com/tonywied17/zero-query" target="_blank" rel="noopener">source on GitHub</a></li>
+          <li>Run <code>npx zquery bundle</code> to build for production</li>
+          <li>Run <code>npx zquery dev</code> for live-reload development</li>
+          <li>Try <code>npx zquery create my-app</code> for the full-featured scaffold</li>
+        </ul>
+      </div>
+    `;
+  }
+});

package/cli/scaffold/minimal/app/components/counter.js

@@ -0,0 +1,122 @@
+// counter.js — Interactive counter
+//
+// Features used:
+//   $.getStore / store.subscribe — shared state + live re-render
+//   @click / z-model + z-number  — events + two-way binding
+//   z-if / z-for / z-key         — conditional & keyed list rendering
+
+$.component('counter-page', {
+  styles: `
+    .ctr-display   { padding: 2rem 0 1.25rem; text-align: center; }
+    .ctr-num       { font-size: 4rem; font-weight: 800; font-variant-numeric: tabular-nums;
+                     color: var(--accent); transition: color .2s; line-height: 1; }
+    .ctr-num.negative { color: var(--danger); }
+    .ctr-label     { font-size: .82rem; color: var(--text-muted); margin-top: .35rem; }
+    .ctr-actions   { display: flex; justify-content: center; gap: .65rem;
+                     margin-bottom: 1.5rem; }
+    .ctr-actions .btn { min-width: 120px; justify-content: center; }
+    .ctr-config    { display: flex; align-items: center; justify-content: center; gap: 1.25rem;
+                     padding-top: 1.15rem; border-top: 1px solid var(--border); }
+    .ctr-config label { display: flex; align-items: center; gap: .5rem;
+                        color: var(--text-muted); font-size: .88rem; }
+    .ctr-config .input-sm { width: 65px; text-align: center; }
+    .ctr-hist      { display: flex; flex-wrap: wrap; gap: .4rem; }
+    .ctr-hist-item { display: inline-flex; align-items: center; gap: .3rem;
+                     padding: .3rem .65rem; border-radius: var(--radius);
+                     background: var(--bg-hover); border: 1px solid var(--border);
+                     font-size: .82rem; font-variant-numeric: tabular-nums; }
+    .ctr-hist-item:last-child { border-color: var(--accent); background: rgba(88,166,255,.06); }
+    .ctr-hist-op   { color: var(--text-muted); font-weight: 500; }
+    .ctr-hist-val  { color: var(--accent); font-weight: 600; }
+
+    @media (max-width: 768px) {
+      .ctr-num       { font-size: 2.75rem; }
+      .ctr-actions   { gap: .5rem; }
+      .ctr-actions .btn { min-width: 100px; }
+      .ctr-config    { flex-wrap: wrap; gap: .75rem; }
+    }
+    @media (max-width: 480px) {
+      .ctr-num       { font-size: 2.25rem; }
+      .ctr-actions .btn { min-width: 0; flex: 1; }
+    }
+  `,
+
+  state: () => ({
+    history: [],
+  }),
+
+  mounted() {
+    this._unsub = $.getStore('main').subscribe(() => this.setState({}));
+  },
+
+  destroyed() {
+    if (this._unsub) this._unsub();
+  },
+
+  increment() {
+    const store = $.getStore('main');
+    store.dispatch('increment');
+    this._pushHistory('+', store.state.step, store.state.count);
+  },
+
+  decrement() {
+    const store = $.getStore('main');
+    store.dispatch('decrement');
+    this._pushHistory('−', store.state.step, store.state.count);
+  },
+
+  setStep(e) {
+    $.getStore('main').dispatch('setStep', Number(e.target.value));
+  },
+
+  _pushHistory(action, value, result) {
+    const raw = this.state.history.__raw || this.state.history;
+    const next = [...raw, { id: Date.now(), action, value, result }];
+    this.state.history = next.length > 8 ? next.slice(-8) : next;
+  },
+
+  reset() {
+    $.getStore('main').dispatch('reset');
+    this.state.history = [];
+  },
+
+  render() {
+    const { count, step } = $.getStore('main').state;
+
+    return `
+      <div class="page-header">
+        <h1>Counter</h1>
+        <p class="subtitle">Reactive <code>store</code>, <code>subscribe</code>, <code>dispatch</code>, and <code>z-for</code>.</p>
+      </div>
+
+      <div class="card">
+        <div class="ctr-display">
+          <div class="ctr-num ${count < 0 ? 'negative' : ''}">${count}</div>
+          <div class="ctr-label">current value${step !== 1 ? ` · step ${step}` : ''}</div>
+        </div>
+
+        <div class="ctr-actions">
+          <button class="btn btn-outline" @click="decrement">− Subtract</button>
+          <button class="btn btn-primary" @click="increment">+ Add</button>
+        </div>
+
+        <div class="ctr-config">
+          <label>Step size
+            <input type="number" value="${step}" @input="setStep" min="1" max="100" class="input input-sm" />
+          </label>
+          <button class="btn btn-ghost btn-sm" @click="reset">Reset</button>
+        </div>
+      </div>
+
+      <div class="card" z-if="history.length > 0">
+        <h3>History <small style="color:var(--text-muted);font-weight:400;font-size:.85rem;">${this.state.history.length} entries</small></h3>
+        <div class="ctr-hist">
+          <span z-for="e in history" z-key="{{e.id}}" class="ctr-hist-item">
+            <span class="ctr-hist-op">{{e.action}}{{e.value}}</span>
+            <span class="ctr-hist-val">→ {{e.result}}</span>
+          </span>
+        </div>
+      </div>
+    `;
+  }
+});

package/cli/scaffold/minimal/app/components/home.js

@@ -0,0 +1,68 @@
+// home.js — Landing page
+//
+// Features used:
+//   $.component      — define a component
+//   $.getStore       — read/dispatch global store
+//   store.subscribe  — re-render on store changes
+//   @click / z-model — event binding + two-way input
+
+$.component('home-page', {
+  state: () => ({
+    greeting: '',
+  }),
+
+  mounted() {
+    const hour = new Date().getHours();
+    this.state.greeting =
+      hour < 12 ? 'Good morning' :
+      hour < 18 ? 'Good afternoon' : 'Good evening';
+
+    this._unsub = $.getStore('main').subscribe(() => this.setState({}));
+  },
+
+  destroyed() {
+    if (this._unsub) this._unsub();
+  },
+
+  increment() { $.getStore('main').dispatch('increment'); },
+  decrement() { $.getStore('main').dispatch('decrement'); },
+  reset()     { $.getStore('main').dispatch('reset'); },
+  setStep(e)  { $.getStore('main').dispatch('setStep', Number(e.target.value)); },
+
+  render() {
+    const { count, step } = $.getStore('main').state;
+
+    return `
+      <div class="page-header">
+        <h1>{{greeting}} 👋</h1>
+        <p class="subtitle">Welcome to your new zQuery project.</p>
+      </div>
+
+      <div class="card">
+        <h3>Getting Started</h3>
+        <p>
+          This is the <strong>minimal</strong> scaffold — three pages, a global store,
+          and the router. Edit the files in <code>app/</code> to start building.
+        </p>
+        <p>
+          Run <code>npx zquery dev</code> for live-reload, or
+          <code>npx zquery bundle</code> when you're ready to ship.
+        </p>
+      </div>
+
+      <div class="card">
+        <h3>Global Store</h3>
+        <p>The counter from <a z-link="/counter">Counter</a> is backed by <code>$.store</code> — its value persists across pages:</p>
+        <div style="display:flex;align-items:center;gap:.75rem;margin-top:.75rem;">
+          <button class="btn btn-outline btn-sm" @click="decrement">−</button>
+          <span style="font-size:1.25rem;font-weight:700;color:var(--accent);min-width:2rem;text-align:center;">${count}</span>
+          <button class="btn btn-primary btn-sm" @click="increment">+</button>
+          <button class="btn btn-outline btn-sm" @click="reset" style="margin-left:.5rem;">Reset</button>
+          <label style="display:flex;align-items:center;gap:.4rem;margin-left:.5rem;font-size:.85rem;color:var(--text-muted);">
+            Step <input type="number" value="${step}" @input="setStep" min="1" max="100" class="input input-sm" style="width:55px;text-align:center;" />
+          </label>
+        </div>
+      </div>
+    `;
+  },
+});

package/cli/scaffold/minimal/app/components/not-found.js

@@ -0,0 +1,16 @@
+// not-found.js — 404 fallback page
+//
+// Uses $.getRouter() to display the unmatched path.
+
+$.component('not-found', {
+  render() {
+    const router = $.getRouter();
+    return `
+      <div class="page-header center">
+        <h1>404</h1>
+        <p class="subtitle">The page <code>${$.escapeHtml(router.current?.path || '')}</code> was not found.</p>
+        <a z-link="/" class="btn btn-primary">← Go Home</a>
+      </div>
+    `;
+  }
+});

package/cli/scaffold/minimal/app/routes.js

@@ -0,0 +1,9 @@
+// routes.js — Route definitions
+//
+// Maps URL paths to component tag names.
+
+export const routes = [
+  { path: '/',        component: 'home-page'    },
+  { path: '/counter', component: 'counter-page' },
+  { path: '/about',   component: 'about-page'   },
+];

package/cli/scaffold/minimal/app/store.js

@@ -0,0 +1,36 @@
+// store.js — Global state management
+//
+// A simple centralized store. Any component can access it
+// via $.getStore('main') and dispatch actions to update state.
+
+export const store = $.store('main', {
+  state: {
+    count: 0,
+    step: 1,
+  },
+
+  actions: {
+    increment(state) {
+      state.count += state.step;
+    },
+
+    decrement(state) {
+      state.count -= state.step;
+    },
+
+    reset(state) {
+      state.count = 0;
+    },
+
+    setStep(state, value) {
+      state.step = Math.max(1, Math.min(100, value));
+    },
+  },
+
+  getters: {
+    isNegative: (state) => state.count < 0,
+    isPositive: (state) => state.count > 0,
+  },
+
+  debug: true,
+});