zero-query 0.3.1 → 0.4.9

package/cli/scaffold/scripts/components/contacts/contacts.html

@@ -0,0 +1,139 @@
+<!--
+  contacts.html — external template for contacts-page component
+
+  This template is fetched via templateUrl and uses {{expression}} syntax
+  for data binding. All zQuery directives work here: z-if, z-else,
+  z-for, z-show, z-bind, z-class, z-style, z-text, z-model, z-ref,
+  z-cloak, @click, @submit.prevent, etc.
+
+  Expressions have access to `state` and `props` automatically.
+  Inside z-for loops, use {{item.prop}} for per-item values.
+-->
+<div class="page-header" z-cloak>
+  <h1>Contacts</h1>
+  <p class="subtitle">
+    External template &amp; styles via <code>templateUrl</code> / <code>styleUrl</code>.
+    Directives: <code>z-if</code>, <code>z-for</code>, <code>z-show</code>,
+    <code>z-bind</code>, <code>z-class</code>, <code>z-model</code>, and more.
+  </p>
+</div>
+
+<!-- Toolbar: add button -->
+<div class="card contacts-toolbar">
+  <div class="contacts-toolbar-row">
+    <span class="contacts-count" z-if="contacts.length > 0">
+      <strong z-text="contacts.length"></strong> contacts
+      · <strong z-text="favoriteCount"></strong> ★ favorited
+      <span z-show="totalAdded > 0"> · <span z-text="totalAdded"></span> added this session</span>
+    </span>
+    <span class="contacts-count" z-else>No contacts yet</span>
+    <button class="btn btn-primary" @click="toggleForm">
+      <span z-if="showForm">✕ Cancel</span>
+      <span z-else>+ Add Contact</span>
+    </button>
+  </div>
+
+  <!-- Add contact form — toggled via z-show -->
+  <form class="contacts-form" z-show="showForm" @submit.prevent="addContact">
+    <div class="form-field form-field-full">
+      <input
+        type="text"
+        z-model="newName"
+        z-trim
+        placeholder="Full name"
+        class="input"
+        @blur="validateName"
+      />
+      <small class="field-error" z-show="nameError" z-text="nameError"></small>
+    </div>
+    <div class="form-field">
+      <input
+        type="email"
+        z-model="newEmail"
+        z-trim
+        placeholder="Email address"
+        class="input"
+        @blur="validateEmail"
+      />
+      <small class="field-error" z-show="emailError" z-text="emailError"></small>
+    </div>
+    <select z-model="newRole" class="input">
+      <option value="Developer">Developer</option>
+      <option value="Designer">Designer</option>
+      <option value="Manager">Manager</option>
+      <option value="QA">QA</option>
+    </select>
+    <button type="submit" class="btn btn-primary">Save Contact</button>
+  </form>
+</div>
+
+<!-- Contact count -->
+<div class="card" z-if="contacts.length > 0">
+  <!-- Contacts list — z-for renders each item -->
+  <ul class="contacts-list">
+    <li
+      z-for="contact in contacts"
+      class="contacts-item {{contact.id === selectedId ? 'selected' : ''}} {{contact.favorite ? 'is-favorite' : ''}}"
+      @click="selectContact({{contact.id}})"
+    >
+      <!-- Status indicator — class set per status -->
+      <span
+        class="status-dot status-{{contact.status}}"
+        title="{{contact.status}}"
+      ></span>
+
+      <!-- Contact info -->
+      <div class="contacts-info">
+        <strong>{{contact.name}}</strong>
+        <small>{{contact.email}}</small>
+      </div>
+
+      <!-- Role badge -->
+      <span class="role-badge role-{{contact.role.toLowerCase()}}">{{contact.role}}</span>
+
+      <!-- Favorite toggle — .stop modifier prevents row click -->
+      <button
+        class="fav-btn {{contact.favorite ? 'is-fav' : ''}}"
+        @click.stop="toggleFavorite({{contact.id}})"
+      >{{contact.favorite ? '★' : '☆'}}</button>
+    </li>
+  </ul>
+</div>
+
+<!-- Empty state -->
+<div class="card" z-else>
+  <div class="empty-state">
+    <p>No contacts yet — add one above!</p>
+  </div>
+</div>
+
+<!-- Selected contact detail panel — z-if conditional rendering -->
+<div class="card contact-detail" z-if="selectedId !== null">
+  <div class="detail-header">
+    <div>
+      <h3 z-text="contacts.find(c => c.id === selectedId)?.name || ''"></h3>
+      <p class="muted" z-text="contacts.find(c => c.id === selectedId)?.email || ''"></p>
+    </div>
+    <div class="detail-actions">
+      <button
+        class="btn btn-outline btn-sm"
+        @click="cycleStatus({{selectedId}})"
+      >
+        Status: <span z-text="contacts.find(c => c.id === selectedId)?.status || ''"></span>
+      </button>
+
+      <!-- Confirm delete pattern using z-if / z-else -->
+      <button
+        class="btn btn-danger btn-sm"
+        z-if="confirmDeleteId !== selectedId"
+        @click.stop="confirmDelete({{selectedId}})"
+      >Delete</button>
+
+      <span z-else class="confirm-group">
+        <span class="confirm-text">Sure?</span>
+        <button class="btn btn-danger btn-sm" @click.stop="deleteContact({{selectedId}})">Yes</button>
+        <button class="btn btn-ghost btn-sm" @click.stop="cancelDelete">No</button>
+      </span>
+    </div>
+  </div>
+</div>

package/cli/scaffold/scripts/components/contacts/contacts.js

@@ -0,0 +1,137 @@
+// scripts/components/contacts/contacts.js — contact book
+//
+// Demonstrates: external templateUrl + styleUrl, z-if/z-else, z-for,
+//               z-show, z-bind/:attr, z-class, z-style, z-text, z-html,
+//               z-model, z-ref, z-cloak, @click, @submit.prevent,
+//               @input.debounce, event modifiers, and template {{expressions}}
+//
+// This component uses external files for its template and styles,
+// resolved automatically relative to this JS file's location.
+// Contacts are persisted in the global $.store('main') so they
+// survive navigation between routes.
+
+$.component('contacts-page', {
+  templateUrl: 'contacts.html',
+  styleUrl:    'contacts.css',
+
+  state: () => ({
+    contacts: [],
+    showForm: false,
+    newName: '',
+    newEmail: '',
+    newRole: 'Developer',
+    nameError: '',
+    emailError: '',
+    selectedId: null,
+    confirmDeleteId: null,
+    totalAdded: 0,
+    favoriteCount: 0,
+  }),
+
+  mounted() {
+    const store = $.getStore('main');
+    this._syncFromStore(store);
+    this._unsub = store.subscribe(() => this._syncFromStore(store));
+  },
+
+  destroyed() {
+    if (this._unsub) this._unsub();
+  },
+
+  _syncFromStore(store) {
+    this.state.contacts      = store.state.contacts;
+    this.state.totalAdded    = store.state.contactsAdded;
+    this.state.favoriteCount = store.getters.favoriteCount;
+  },
+
+  // -- Actions --
+
+  toggleForm() {
+    this.state.showForm = !this.state.showForm;
+    if (!this.state.showForm) this._clearForm();
+  },
+
+  _validateName(name) {
+    if (!name) return 'Name is required.';
+    if (name.length < 2) return 'Name must be at least 2 characters.';
+    return '';
+  },
+
+  _validateEmail(email) {
+    if (!email) return 'Email is required.';
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return 'Enter a valid email address.';
+    const store = $.getStore('main');
+    if (store.state.contacts.some(c => c.email.toLowerCase() === email.toLowerCase())) {
+      return 'A contact with this email already exists.';
+    }
+    return '';
+  },
+
+  validateName() {
+    this.state.nameError = this._validateName(this.state.newName.trim());
+  },
+
+  validateEmail() {
+    this.state.emailError = this._validateEmail(this.state.newEmail.trim());
+  },
+
+  addContact() {
+    const name  = this.state.newName.trim();
+    const email = this.state.newEmail.trim();
+
+    const nameError  = this._validateName(name);
+    const emailError = this._validateEmail(email);
+    this.state.nameError  = nameError;
+    this.state.emailError = emailError;
+    if (nameError || emailError) return;
+
+    $.getStore('main').dispatch('addContact', {
+      name,
+      email,
+      role: this.state.newRole,
+    });
+
+    this._clearForm();
+    this.state.showForm = false;
+    $.bus.emit('toast', { message: `${name} added!`, type: 'success' });
+  },
+
+  toggleFavorite(id) {
+    $.getStore('main').dispatch('toggleFavorite', Number(id));
+  },
+
+  selectContact(id) {
+    this.state.selectedId = this.state.selectedId === Number(id) ? null : Number(id);
+    this.state.confirmDeleteId = null;
+  },
+
+  confirmDelete(id) {
+    this.state.confirmDeleteId = Number(id);
+  },
+
+  cancelDelete() {
+    this.state.confirmDeleteId = null;
+  },
+
+  deleteContact(id) {
+    const numId = Number(id);
+    const store = $.getStore('main');
+    const c = store.state.contacts.find(c => c.id === numId);
+    store.dispatch('deleteContact', numId);
+    this.state.selectedId = null;
+    this.state.confirmDeleteId = null;
+    $.bus.emit('toast', { message: `${c ? c.name : 'Contact'} removed`, type: 'error' });
+  },
+
+  cycleStatus(id) {
+    $.getStore('main').dispatch('cycleContactStatus', Number(id));
+  },
+
+  _clearForm() {
+    this.state.newName   = '';
+    this.state.newEmail  = '';
+    this.state.newRole   = 'Developer';
+    this.state.nameError = '';
+    this.state.emailError = '';
+  },
+});

package/cli/scaffold/scripts/components/counter.js

@@ -0,0 +1,65 @@
+// scripts/components/counter.js — interactive counter
+//
+// Demonstrates: component state, instance methods, @click event binding,
+//               z-model two-way binding with z-number modifier, z-class,
+//               z-if, z-for, $.bus toast notifications
+
+$.component('counter-page', {
+  state: () => ({
+    count: 0,
+    step: 1,
+    history: [],
+  }),
+
+  increment() {
+    this.state.count += this.state.step;
+    this.state.history.push({ action: '+', value: this.state.step, result: this.state.count });
+    if (this.state.history.length > 8) this.state.history.shift();
+  },
+
+  decrement() {
+    this.state.count -= this.state.step;
+    this.state.history.push({ action: '−', value: this.state.step, result: this.state.count });
+    if (this.state.history.length > 8) this.state.history.shift();
+  },
+
+  reset() {
+    this.state.count = 0;
+    this.state.history = [];
+    $.bus.emit('toast', { message: 'Counter reset!', type: 'info' });
+  },
+
+  render() {
+    return `
+      <div class="page-header">
+        <h1>Counter</h1>
+        <p class="subtitle">Component state, <code>@click</code> handlers, <code>z-model</code>, <code>z-class</code>, and <code>z-for</code>.</p>
+      </div>
+
+      <div class="card counter-card">
+        <div class="counter-display">
+          <span class="counter-value" z-class="{'negative': count < 0}">${this.state.count}</span>
+        </div>
+
+        <div class="counter-controls">
+          <button class="btn btn-danger" @click="decrement">− Subtract</button>
+          <button class="btn btn-primary" @click="increment">+ Add</button>
+        </div>
+
+        <div class="counter-step">
+          <label>Step size:
+            <input type="number" z-model="step" z-number 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 card-muted" z-if="history.length > 0">
+        <h3>History</h3>
+        <div class="history-list">
+          <span z-for="e in history" class="history-item">{{e.action}}{{e.value}} → <strong>{{e.result}}</strong></span>
+        </div>
+      </div>
+    `;
+  }
+});

package/cli/scaffold/scripts/components/home.js

@@ -0,0 +1,137 @@
+// scripts/components/home.js — dashboard / landing page
+//
+// Demonstrates: $.component, state, render, mounted lifecycle,
+//               signal + computed + effect (reactive primitives),
+//               $.store integration, $.bus, template rendering
+
+$.component('home-page', {
+  state: () => ({
+    greeting: '',
+    signalDemo: 0,
+  }),
+
+  mounted() {
+    // $.signal() — fine-grained reactive primitive
+    const count = $.signal(0);
+
+    // $.computed() — derived reactive value that auto-updates
+    const doubled = $.computed(() => count.value * 2);
+
+    // $.effect() — runs whenever its dependencies change
+    $.effect(() => {
+      this.state.signalDemo = doubled.value;
+    });
+
+    // Store the signal setter so the button can use it
+    this._signalCount = count;
+
+    // Greet based on time of day
+    const hour = new Date().getHours();
+    this.state.greeting = hour < 12 ? 'Good morning'
+                        : hour < 18 ? 'Good afternoon'
+                        : 'Good evening';
+
+    // Track page visit via the global store
+    const store = $.getStore('main');
+    store.dispatch('incrementVisits');
+  },
+
+  incrementSignal() {
+    if (this._signalCount) {
+      this._signalCount.value++;
+    }
+  },
+
+  render() {
+    const store = $.getStore('main');
+    return `
+      <div class="page-header">
+        <h1>${this.state.greeting} 👋</h1>
+        <p class="subtitle">Welcome to your new <strong>zQuery</strong> app. Explore the pages to see different features in action.</p>
+      </div>
+
+      <div class="card-grid">
+        <div class="card card-accent">
+          <h3>⚡ Reactive Signals</h3>
+          <p>Fine-grained reactivity with <code>signal()</code>, <code>computed()</code>, and <code>effect()</code>.</p>
+          <div class="signal-demo">
+            <span class="signal-value">Doubled: ${this.state.signalDemo}</span>
+            <button class="btn btn-sm" @click="incrementSignal">Increment Signal</button>
+          </div>
+        </div>
+
+        <div class="card">
+          <h3>🔢 Counter</h3>
+          <p>Component state, two-way binding with <code>z-model</code>, and event handling.</p>
+          <a z-link="/counter" class="btn btn-outline">Try It →</a>
+        </div>
+
+        <div class="card">
+          <h3>✅ Todos</h3>
+          <p>Global store with actions & getters. <strong>${store.getters.todoCount}</strong> items, <strong>${store.getters.doneCount}</strong> done.</p>
+          <a z-link="/todos" class="btn btn-outline">Try It →</a>
+        </div>
+
+        <div class="card">
+          <h3>📇 Contacts</h3>
+          <p>External templates &amp; styles via <code>templateUrl</code> / <code>styleUrl</code>. <strong>${store.getters.contactCount}</strong> contacts, <strong>${store.getters.favoriteCount}</strong> ★ favorited.</p>
+          <a z-link="/contacts" class="btn btn-outline">Try It →</a>
+        </div>
+
+        <div class="card">
+          <h3>🌐 API Demo</h3>
+          <p>Fetch data with <code>$.get()</code>, loading states, and <code>$.escapeHtml()</code>.</p>
+          <a z-link="/api" class="btn btn-outline">Try It →</a>
+        </div>
+      </div>
+
+      <div class="card card-muted">
+        <h3>📊 App Stats</h3>
+        <div class="stats-grid">
+          <div class="stat-group">
+            <span class="stat-group-title">🏠 General</span>
+            <div class="stat-group-values">
+              <div class="stat">
+                <span class="stat-value">${store.state.visits}</span>
+                <span class="stat-label">Page Views</span>
+              </div>
+            </div>
+          </div>
+
+          <div class="stat-group">
+            <span class="stat-group-title">✅ Todos</span>
+            <div class="stat-group-values">
+              <div class="stat">
+                <span class="stat-value">${store.getters.todoCount}</span>
+                <span class="stat-label">Total</span>
+              </div>
+              <div class="stat">
+                <span class="stat-value">${store.getters.pendingCount}</span>
+                <span class="stat-label">Pending</span>
+              </div>
+              <div class="stat">
+                <span class="stat-value">${store.getters.doneCount}</span>
+                <span class="stat-label">Done</span>
+              </div>
+            </div>
+          </div>
+
+          <div class="stat-group">
+            <span class="stat-group-title">📇 Contacts</span>
+            <div class="stat-group-values">
+              <div class="stat">
+                <span class="stat-value">${store.getters.contactCount}</span>
+                <span class="stat-label">Total</span>
+              </div>
+              <div class="stat">
+                <span class="stat-value">${store.getters.favoriteCount}</span>
+                <span class="stat-label">★ Favorited</span>
+              </div>
+            </div>
+          </div>
+        </div>
+        <small class="muted">Stats powered by <code>$.store()</code> getters — visit count tracked globally.</small>
+      </div>
+    `;
+  }
+});

package/cli/scaffold/scripts/components/not-found.js

@@ -0,0 +1,16 @@
+// scripts/components/not-found.js — 404 fallback page
+//
+// Demonstrates: $.getRouter() to read the current 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/scripts/components/todos.js

@@ -0,0 +1,130 @@
+// scripts/components/todos.js — todo list with global store
+//
+// Demonstrates: $.getStore, store.dispatch, store.subscribe,
+//               store getters, z-model, z-ref, z-class, z-for,
+//               z-if, z-show, @click with args, @submit.prevent,
+//               mounted/destroyed lifecycle, $.bus toast, $.debounce
+
+$.component('todos-page', {
+  state: () => ({
+    newTodo: '',
+    filter: 'all',      // 'all' | 'active' | 'done'
+    search: '',
+    filtered: [],        // computed in render() for z-for access
+    total: 0,
+    done: 0,
+    pending: 0,
+  }),
+
+  mounted() {
+    const store = $.getStore('main');
+    this._unsub = store.subscribe(() => this.setState({}));
+
+    // $.debounce — debounced search filter (300ms)
+    this._debouncedSearch = $.debounce((val) => {
+      this.state.search = val;
+    }, 300);
+  },
+
+  destroyed() {
+    if (this._unsub) this._unsub();
+  },
+
+  addTodo() {
+    const text = this.state.newTodo.trim();
+    if (!text) return;
+    $.getStore('main').dispatch('addTodo', text);
+    this.state.newTodo = '';
+    this.state.search = '';
+    this.state.filter = 'all';
+    $.bus.emit('toast', { message: 'Todo added!', type: 'success' });
+  },
+
+  toggleTodo(id) {
+    $.getStore('main').dispatch('toggleTodo', id);
+  },
+
+  removeTodo(id) {
+    $.getStore('main').dispatch('removeTodo', id);
+    $.bus.emit('toast', { message: 'Todo removed', type: 'error' });
+  },
+
+  clearCompleted() {
+    $.getStore('main').dispatch('clearCompleted');
+    $.bus.emit('toast', { message: 'Completed todos cleared', type: 'info' });
+  },
+
+  setFilter(f) {
+    this.state.filter = f;
+  },
+
+  onSearch(e) {
+    this._debouncedSearch(e.target.value);
+  },
+
+  render() {
+    const store = $.getStore('main');
+    const todos = store.state.todos;
+    const { filter, search } = this.state;
+
+    // Compute filtered list and store stats into state for directive access
+    let list = todos;
+    if (filter === 'active') list = todos.filter(t => !t.done);
+    if (filter === 'done')   list = todos.filter(t => t.done);
+    if (search) {
+      const q = search.toLowerCase();
+      list = list.filter(t => t.text.toLowerCase().includes(q));
+    }
+    this.state.filtered = list;
+    this.state.total    = store.getters.todoCount;
+    this.state.done     = store.getters.doneCount;
+    this.state.pending  = store.getters.pendingCount;
+
+    return `
+      <div class="page-header">
+        <h1>Todos</h1>
+        <p class="subtitle">Global store with <code>$.store()</code>, <code>z-for</code>, <code>z-class</code>, <code>z-if</code>, and <code>z-show</code>.</p>
+      </div>
+
+      <div class="card">
+        <form class="todo-form" @submit.prevent="addTodo">
+          <input
+            type="text"
+            z-model="newTodo" z-trim
+            placeholder="What needs to be done?"
+            class="input"
+            z-ref="todoInput"
+          />
+          <button type="submit" class="btn btn-primary">Add</button>
+        </form>
+      </div>
+
+      <div class="card">
+        <div class="todo-toolbar">
+          <div class="todo-filters">
+            <button class="btn btn-sm" z-class="{'btn-primary': filter === 'all', 'btn-ghost': filter !== 'all'}" @click="setFilter('all')">All (${this.state.total})</button>
+            <button class="btn btn-sm" z-class="{'btn-primary': filter === 'active', 'btn-ghost': filter !== 'active'}" @click="setFilter('active')">Active (${this.state.pending})</button>
+            <button class="btn btn-sm" z-class="{'btn-primary': filter === 'done', 'btn-ghost': filter !== 'done'}" @click="setFilter('done')">Done (${this.state.done})</button>
+          </div>
+          <input type="text" placeholder="Search…" class="input input-sm" @input="onSearch" value="${$.escapeHtml(this.state.search)}" />
+        </div>
+
+        <div z-if="filtered.length === 0" class="empty-state">
+          <p>${this.state.total === 0 ? 'No todos yet — add one above!' : 'No matching todos.'}</p>
+        </div>
+
+        <ul z-else class="todo-list">
+          <li z-for="t in filtered" class="todo-item {{t.done ? 'done' : ''}}">
+            <button class="todo-check" @click="toggleTodo('{{t.id}}')"></button>
+            <span class="todo-text">{{$.escapeHtml(t.text)}}</span>
+            <button class="todo-remove" @click="removeTodo('{{t.id}}')">✕</button>
+          </li>
+        </ul>
+
+        <div class="todo-footer" z-show="done > 0">
+          <button class="btn btn-ghost btn-sm" @click="clearCompleted">Clear completed (${this.state.done})</button>
+        </div>
+      </div>
+    `;
+  }
+});

package/cli/scaffold/scripts/routes.js

@@ -0,0 +1,13 @@
+// scripts/routes.js — route definitions
+//
+// Each route maps a URL path to a component tag name.
+// Supports: static paths, :params, wildcards, and lazy loading via `load`.
+
+export const routes = [
+  { path: '/',         component: 'home-page'     },
+  { path: '/counter',  component: 'counter-page'  },
+  { path: '/todos',    component: 'todos-page'    },
+  { path: '/contacts', component: 'contacts-page' },
+  { path: '/api',      component: 'api-demo'      },
+  { path: '/about',    component: 'about-page'    },
+];