@techninja/clearstack 0.2.0

package/templates/shared/docs/clearstack/STATE_AND_ROUTING.md

@@ -0,0 +1,363 @@
+# State & Routing
+## Store, Routing, Unified App State & Realtime Sync
+
+> How data flows through the application.
+> See [FRONTEND_IMPLEMENTATION_RULES.md](./FRONTEND_IMPLEMENTATION_RULES.md) for
+> project structure and [BACKEND_API_SPEC.md](./BACKEND_API_SPEC.md) for the
+> server-side data contract.
+
+---
+
+## State Management
+
+### Component-Local State
+
+For state that belongs to a single component instance, use plain properties:
+
+```javascript
+export default define({
+  tag: 'app-toggle',
+  open: false,
+  render: ({ open }) => html`
+    <button onclick="${host => { host.open = !host.open; }}">
+      ${open ? 'Close' : 'Open'}
+    </button>
+  `,
+});
+```
+
+Local state resets when the component disconnects from the DOM.
+
+### Shared State via Store
+
+For state shared across components or persisted beyond a component's lifetime,
+use `store()` with a model definition.
+
+#### Singleton Model (App-Wide State)
+
+One instance, no `id`. Lives in `src/store/AppState.js`:
+
+```javascript
+/** @typedef {{ theme: 'light'|'dark', sidebarOpen: boolean }} AppState */
+
+/** @type {import('hybrids').Model<AppState>} */
+const AppState = {
+  theme: 'light',
+  sidebarOpen: false,
+};
+
+export default AppState;
+```
+
+#### localStorage Connector: Return `{}`, Never `undefined`
+
+When a localStorage-backed singleton has no stored value yet (first visit),
+the `get` connector **must return `{}`**, not `undefined` or `null`.
+
+Hybrids treats `undefined` from `get` as a failed fetch and puts the model
+into an error state. Returning `{}` lets hybrids merge with the model's
+default values, so the model initializes cleanly:
+
+```javascript
+[store.connect]: {
+  // ✅ GOOD — returns empty object, hybrids merges with defaults
+  get: () => {
+    const raw = localStorage.getItem('appState');
+    return raw ? JSON.parse(raw) : {};
+  },
+  // ❌ BAD — undefined triggers error state
+  // get: () => {
+  //   const raw = localStorage.getItem('appState');
+  //   return raw ? JSON.parse(raw) : undefined;
+  // },
+}
+```
+
+This applies to all localStorage-backed singletons (`AppState`, `UserPrefs`).
+
+Consume in any component:
+
+```javascript
+import { store, html, define } from 'hybrids';
+import AppState from '../../store/AppState.js';
+
+export default define({
+  tag: 'theme-toggle',
+  state: store(AppState),
+  render: ({ state }) => html`
+    <button onclick="${host => {
+      store.set(host.state, { theme: host.state.theme === 'light' ? 'dark' : 'light' });
+    }}">
+      Theme: ${state.theme}
+    </button>
+  `,
+});
+```
+
+#### Enumerable Model (Entity Records)
+
+Has `id: true`. Lives in `src/store/UserModel.js`:
+
+```javascript
+/**
+ * @typedef {Object} User
+ * @property {string} id
+ * @property {string} firstName
+ * @property {string} lastName
+ * @property {string} email
+ */
+
+/** @type {import('hybrids').Model<User>} */
+const UserModel = {
+  id: true,
+  firstName: '',
+  lastName: '',
+  email: '',
+  [store.connect]: {
+    get: (id) => fetch(`/api/users/${id}`).then(r => r.json()),
+    set: (id, values) => fetch(`/api/users/${id}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(values),
+    }).then(r => r.json()),
+    list: (id) => fetch(`/api/users?${new URLSearchParams(id)}`).then(r => r.json()),
+  },
+};
+
+export default UserModel;
+```
+
+#### Store API Quick Reference
+
+| Method | Purpose |
+|---|---|
+| `store(Model)` | Descriptor — binds model to a component property |
+| `store.get(Model, id)` | Get a cached instance (triggers fetch if needed) |
+| `store.set(model, values)` | Update (async, returns Promise) |
+| `store.sync(model, values)` | Update (sync, immediate) |
+| `store.pending(model)` | `false` or `Promise` while loading |
+| `store.ready(model)` | `true` when loaded and valid |
+| `store.error(model)` | `false` or `Error` |
+| `store.clear(Model)` | Invalidate singular model cache |
+| `store.clear([Model])` | Invalidate list cache — **required for list stores** |
+| `store.submit(draft)` | Submit draft mode changes |
+| `store.resolve(Model, id)` | Returns Promise that resolves when ready |
+
+#### Decision Tree: Local vs Shared State
+
+```
+Is this state used by more than one component?
+  YES → store()
+  NO  → Does it need to survive component disconnect?
+          YES → store()
+          NO  → plain property
+```
+
+#### Guarding List Item Access
+
+`store.ready(list)` checks if the list itself has loaded, but individual
+items within the list can still be in a pending state (e.g. after a cache
+clear triggers re-fetch). Always guard property access on list items:
+
+```javascript
+// ❌ BAD — task may be pending, accessing .title throws
+tasks.map((task) => html`<span>${task.title}</span>`)
+
+// ✅ GOOD — guard each item, show fallback for pending items
+tasks.map((task) => store.ready(task)
+  ? html`<span>${task.title}</span>`
+  : html`<span class="spinner"></span>`
+)
+```
+
+This is especially important after batch operations (e.g. drag reorder)
+where multiple items are invalidated simultaneously.
+
+---
+
+## Routing
+
+### Router Shell
+
+The app has one router shell component that manages the view stack.
+Lives in `src/router/index.js`:
+
+```javascript
+import { define, html, router } from 'hybrids';
+import HomeView from '../pages/home/index.js';
+
+export default define({
+  tag: 'app-router',
+  stack: router(HomeView, { url: '/' }),
+  render: ({ stack }) => html`
+    <template layout="column height::100vh">
+      ${stack}
+    </template>
+  `,
+});
+```
+
+### View Configuration
+
+Each page declares its routing config via `[router.connect]`:
+
+```javascript
+import { define, html, router } from 'hybrids';
+import AboutView from '../about/index.js';
+
+export default define({
+  tag: 'home-view',
+  [router.connect]: {
+    url: '/',
+    stack: [AboutView],
+  },
+  render: () => html`
+    <template layout="column gap:2 padding:2">
+      <h1>Home</h1>
+      <a href="${router.url(AboutView)}">About</a>
+    </template>
+  `,
+});
+```
+
+### Routing Patterns
+
+| Pattern | Code |
+|---|---|
+| Navigate to view | `<a href="${router.url(View)}">` |
+| Navigate with params | `router.url(View, { id: '42' })` |
+| Back button | `<a href="${router.backUrl()}">Back</a>` |
+| Check active view | `router.active(View)` |
+| Guarded route | `guard: () => isAuthenticated()` |
+| Dialog overlay | `dialog: true` on the view config |
+
+---
+
+## Unified App State
+
+The frontend maintains a single `AppState` singleton that acts as the
+**source of truth for UI state**. Entity data lives in enumerable store
+models that sync with the backend.
+
+### Architecture
+
+```
+Backend REST API
+      ↕ fetch / SSE
+Store Models (UserModel, etc.)  ←→  [store.connect] storage
+      ↕ store()
+Component Properties
+      ↕ render()
+DOM
+```
+
+### AppState vs Entity Models
+
+| Concern | Where |
+|---|---|
+| Theme, sidebar, UI flags | `AppState` (singleton) |
+| User records, posts, etc. | `UserModel`, `PostModel` (enumerable) |
+| Form draft state | `store(Model, { draft: true })` |
+| Route state | `router()` — managed by hybrids |
+
+---
+
+## Realtime Sync
+
+For live data updates, the backend pushes events via **Server-Sent Events
+(SSE)**. The frontend listens and invalidates the relevant store cache.
+
+### Frontend: SSE Listener
+
+Lives in `src/utils/realtimeSync.js`:
+
+```javascript
+import { store } from 'hybrids';
+
+export function connectRealtime(url, modelMap) {
+  const source = new EventSource(url);
+
+  source.addEventListener('update', (event) => {
+    const { type } = JSON.parse(event.data);
+    const Model = modelMap[type];
+    if (Model) store.clear(Model);  // full clear triggers re-fetch
+  });
+
+  source.addEventListener('error', () => {
+    source.close();
+    setTimeout(() => connectRealtime(url, modelMap), 5000);
+  });
+
+  return () => source.close();
+}
+```
+
+`store.clear(Model)` fully invalidates the cache for that model type.
+Any component bound to the model via `store()` will automatically re-fetch
+from the API. This is the mechanism that makes multi-user realtime work —
+when user A creates a task, user B's task list updates automatically.
+
+For the local user, form submit handlers also call `store.clear(Model)`
+immediately after a successful save. The SSE event that follows is
+redundant for the local user but ensures other connected clients update.
+
+### Backend: SSE Endpoint
+
+See [BACKEND_API_SPEC.md](./BACKEND_API_SPEC.md) for the `/api/events` SSE
+contract.
+
+### Wiring It Up
+
+In the router shell's `connect` descriptor:
+
+```javascript
+import { connectRealtime } from '../utils/realtimeSync.js';
+import UserModel from '../store/UserModel.js';
+
+export default define({
+  tag: 'app-router',
+  stack: router(HomeView, { url: '/' }),
+  connection: {
+    value: undefined,
+    connect(host) {
+      const disconnect = connectRealtime('/api/events', {
+        user: UserModel,
+      });
+      return disconnect;
+    },
+  },
+  render: ({ stack }) => html`
+    <template layout="column height::100vh">${stack}</template>
+  `,
+});
+```
+
+When the backend sends `{ type: "user", id: "42" }` over SSE, the store
+cache for `UserModel` is cleared, and any component displaying that user
+re-fetches automatically.
+
+### Debouncing Batch Operations
+
+Operations like drag-to-reorder send multiple PUTs, each triggering an SSE
+event. Without debouncing, each event clears the store and triggers a
+re-render while the previous render is still pending — causing cascading
+errors.
+
+The `connectRealtime()` utility debounces by entity type: multiple SSE
+events within 300ms trigger only one `store.clear()`. This means a reorder
+of 5 tasks sends 5 PUTs → 5 SSE events → 1 store clear after 300ms.
+
+```javascript
+// Inside connectRealtime — debounce per entity type
+const timers = {};
+source.addEventListener('update', (event) => {
+  const { type } = JSON.parse(event.data);
+  clearTimeout(timers[type]);
+  timers[type] = setTimeout(() => {
+    store.clear([Model]);  // one clear after the batch settles
+  }, 300);
+});
+```
+
+For the local user, the UI should not call `store.clear()` explicitly
+after batch operations — let the debounced SSE handler do it once.

package/templates/shared/docs/clearstack/TESTING.md

@@ -0,0 +1,268 @@
+# Testing
+## Philosophy, Tools & Patterns
+
+> How we test in a no-build web component project.
+> See [FRONTEND_IMPLEMENTATION_RULES.md](./FRONTEND_IMPLEMENTATION_RULES.md) for
+> the full specification index.
+
+---
+
+## Philosophy
+
+### Test What Matters, When It Matters
+
+Tests are written **alongside implementation, not after**. Each phase of
+development produces tests before moving to the next phase. This catches
+bugs at the boundary where they're introduced, not 5 layers up.
+
+### Core Principles
+
+| Principle | Rule |
+|---|---|
+| Test at the right level | Pure logic → unit. Components → browser. API → integration. |
+| No mocking the framework | Don't mock `html`, `store`, or `define`. Test through them. |
+| Real browser for components | Web components need a real DOM. No jsdom, no happy-dom. |
+| Zero build for tests | Test files are ES modules, same as app code. |
+| Small test files | Same 150-line rule applies to test files. |
+| Test behavior, not implementation | Assert what the user sees, not internal state shape. |
+| Co-locate tests | Tests live next to the code they test. |
+
+---
+
+## Tools
+
+### Two Test Runners, Clear Boundaries
+
+| Tool | Tests | Runs in |
+|---|---|---|
+| `node:test` (built-in) | Server, utils, store model shapes | Node.js |
+| `@web/test-runner` | Components, pages, browser integration | Real Chromium |
+
+No other test frameworks. No Jest, no Mocha, no Jasmine.
+
+### Why Two Runners
+
+- **`node:test`** is zero-dependency and fast. Perfect for pure functions
+  and server-side code that doesn't touch the DOM.
+- **`@web/test-runner`** launches a real browser, serves ES modules natively,
+  and respects import maps. Components mount into a real DOM with shadow roots,
+  events, and rendering — exactly like production.
+
+---
+
+## File Conventions
+
+### Test File Location
+
+Tests live **next to the code they test**, with a `.test.js` suffix:
+
+```
+src/utils/
+├── formatDate.js
+└── formatDate.test.js          ← node:test
+
+src/components/atoms/app-button/
+├── app-button.js
+├── app-button.css
+├── app-button.test.js          ← @web/test-runner
+└── index.js
+
+src/store/
+├── UserModel.js
+└── UserModel.test.js           ← node:test
+
+src/server.js
+server.test.js                  ← node:test
+```
+
+### Test File Naming
+
+| Code file | Test file |
+|---|---|
+| `app-button.js` | `app-button.test.js` |
+| `formatDate.js` | `formatDate.test.js` |
+| `UserModel.js` | `UserModel.test.js` |
+| `src/server.js` | `server.test.js` |
+
+### What Gets Tested
+
+| Layer | What to assert |
+|---|---|
+| **Utils** | Input → output. Edge cases. |
+| **Store models** | Shape is correct. Computed fields work. Storage connector URLs are right. |
+| **Atoms** | Renders correct HTML. Props reflect to attributes. Events fire. |
+| **Molecules** | Child atoms are present. Composed behavior works. |
+| **Organisms** | Store integration. Data flows to children. |
+| **Server API** | CRUD responses. Schema endpoint. Status codes. |
+| **Pages** | Don't unit-test pages. Test via manual or E2E if needed. |
+
+---
+
+## Patterns
+
+### Node Tests (utils, store, server)
+
+Using the built-in `node:test` and `node:assert`:
+
+```javascript
+// src/utils/formatDate.test.js
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { formatDate } from './formatDate.js';
+
+describe('formatDate', () => {
+  it('formats ISO string to readable date', () => {
+    assert.equal(formatDate('2024-01-15T09:00:00Z'), 'Jan 15, 2024');
+  });
+
+  it('returns empty string for null', () => {
+    assert.equal(formatDate(null), '');
+  });
+});
+```
+
+Run with:
+
+```bash
+node --test src/utils/*.test.js
+```
+
+### Server Tests
+
+Test the API endpoints using fetch against a running server:
+
+```javascript
+// server.test.js
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+
+let server;
+const BASE = 'http://localhost:3001';
+
+before(async () => {
+  // Import and start server on test port
+  const app = await import('./src/server.js');
+  server = app.start(3001);
+});
+
+after(() => server?.close());
+
+describe('GET /api/users', () => {
+  it('returns a list with data array', async () => {
+    const res = await fetch(`${BASE}/api/users`);
+    const body = await res.json();
+    assert.equal(res.status, 200);
+    assert.ok(Array.isArray(body.data));
+  });
+});
+
+describe('GET /api/users?schema=true', () => {
+  it('returns JSON Schema with properties', async () => {
+    const res = await fetch(`${BASE}/api/users?schema=true`);
+    const schema = await res.json();
+    assert.equal(schema.title, 'User');
+    assert.ok(schema.properties.firstName);
+  });
+});
+```
+
+### Component Tests (browser)
+
+Using `@web/test-runner` with `@open-wc/testing`:
+
+```javascript
+// src/components/atoms/app-button/app-button.test.js
+import { fixture, html, expect } from '@open-wc/testing';
+import './app-button.js';
+
+describe('app-button', () => {
+  it('renders with label', async () => {
+    const el = await fixture(html`<app-button label="Click me"></app-button>`);
+    const button = el.shadowRoot.querySelector('button');
+    expect(button.textContent).to.contain('Click me');
+  });
+
+  it('reflects disabled attribute', async () => {
+    const el = await fixture(html`<app-button disabled></app-button>`);
+    const button = el.shadowRoot.querySelector('button');
+    expect(button.hasAttribute('disabled')).to.be.true;
+  });
+
+  it('dispatches click event', async () => {
+    const el = await fixture(html`<app-button label="Go"></app-button>`);
+    let clicked = false;
+    el.addEventListener('click', () => { clicked = true; });
+    el.shadowRoot.querySelector('button').click();
+    expect(clicked).to.be.true;
+  });
+});
+```
+
+### Store Integration Tests (browser)
+
+For components that bind to the store, test the full cycle:
+
+```javascript
+// src/components/organisms/task-list/task-list.test.js
+import { fixture, html, expect, waitUntil } from '@open-wc/testing';
+import { store } from 'hybrids';
+import './task-list.js';
+
+describe('task-list', () => {
+  it('renders tasks from store', async () => {
+    const el = await fixture(html`<task-list project-id="1"></task-list>`);
+    await waitUntil(() => el.shadowRoot.querySelectorAll('task-card').length > 0);
+    const cards = el.shadowRoot.querySelectorAll('task-card');
+    expect(cards.length).to.be.greaterThan(0);
+  });
+});
+```
+
+---
+
+## Configuration
+
+### web-test-runner.config.js
+
+```javascript
+import { playwrightLauncher } from '@web/test-runner-playwright';
+
+export default {
+  files: 'src/components/**/*.test.js',
+  nodeResolve: true,
+  browsers: [
+    playwrightLauncher({ product: 'chromium' }),
+  ],
+};
+```
+
+### package.json Scripts
+
+```json
+{
+  "scripts": {
+    "test": "npm run test:node && npm run test:browser",
+    "test:node": "node --test 'src/**/*.test.js' 'server.test.js'",
+    "test:browser": "web-test-runner",
+    "test:watch": "web-test-runner --watch"
+  }
+}
+```
+
+---
+
+## Build-Phase Test Checkpoints
+
+Each implementation phase must pass its tests before proceeding:
+
+| Phase | Implement | Then test |
+|---|---|---|
+| 1. Infrastructure | server, vendor script, index.html | Server starts, routes respond, vendor files exist |
+| 2. Store + Utils | models, formatDate, realtimeSync | Model shapes, util outputs, localStorage round-trip |
+| 3. Atoms | app-button, app-badge, app-icon | Render, props, events |
+| 4. Molecules | task-card, project-card | Composition, slot content |
+| 5. Organisms | task-list, project-header | Store binding, data rendering |
+| 6. Pages + Router | views, app-router | Navigation, full page render |
+
+**Rule: never skip a checkpoint.** If phase 3 tests fail, fix before
+starting phase 4. Bugs compound; catch them at the boundary.

package/templates/shared/public/index.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{name}}</title>
+  <link rel="stylesheet" href="/src/styles/reset.css">
+  <link rel="stylesheet" href="/src/styles/tokens.css">
+  <link rel="stylesheet" href="/src/styles/shared.css">
+  <link rel="stylesheet" href="/src/styles/buttons.css">
+  <link rel="stylesheet" href="/src/styles/forms.css">
+  <link rel="stylesheet" href="/src/styles/components.css">
+
+  <script type="importmap">
+  {
+    "imports": {
+      "hybrids": "/vendor/hybrids/index.js"
+    }
+  }
+  </script>
+</head>
+<body>
+  <app-router></app-router>
+  <script type="module" src="/src/router/index.js"></script>
+</body>
+</html>