@techninja/clearstack 0.2.16 → 0.2.18

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

@@ -1,4 +1,5 @@
 # State & Routing
+
 ## Store, Routing, Unified App State & Realtime Sync
 
 > How data flows through the application.
@@ -19,7 +20,11 @@ export default define({
   tag: 'app-toggle',
   open: false,
   render: ({ open }) => html`
-    <button onclick="${host => { host.open = !host.open; }}">
+    <button
+      onclick="${(host) => {
+        host.open = !host.open;
+      }}"
+    >
       ${open ? 'Close' : 'Open'}
     </button>
   `,
@@ -85,9 +90,11 @@ 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' });
-    }}">
+    <button
+      onclick="${(host) => {
+        store.set(host.state, { theme: host.state.theme === 'light' ? 'dark' : 'light' });
+      }}"
+    >
       Theme: ${state.theme}
     </button>
   `,
@@ -114,13 +121,14 @@ const UserModel = {
   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()),
+    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()),
   },
 };
 
@@ -129,19 +137,19 @@ 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 |
+| 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
 
@@ -161,13 +169,12 @@ 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>`)
+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>`
-)
+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)
@@ -189,11 +196,7 @@ 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>
-  `,
+  render: ({ stack }) => html` <template layout="column height::100vh"> ${stack} </template> `,
 });
 ```
 
@@ -222,14 +225,14 @@ export default define({
 
 ### 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 |
+| 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        |
 
 ---
 
@@ -253,12 +256,12 @@ DOM
 
 ### AppState vs Entity Models
 
-| Concern | Where |
-|---|---|
-| Theme, sidebar, UI flags | `AppState` (singleton) |
+| 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 |
+| Form draft state          | `store(Model, { draft: true })`       |
+| Route state               | `router()` — managed by hybrids       |
 
 ---
 
@@ -280,7 +283,7 @@ export function connectRealtime(url, modelMap) {
   source.addEventListener('update', (event) => {
     const { type } = JSON.parse(event.data);
     const Model = modelMap[type];
-    if (Model) store.clear(Model);  // full clear triggers re-fetch
+    if (Model) store.clear(Model); // full clear triggers re-fetch
   });
 
   source.addEventListener('error', () => {
@@ -326,9 +329,7 @@ export default define({
       return disconnect;
     },
   },
-  render: ({ stack }) => html`
-    <template layout="column height::100vh">${stack}</template>
-  `,
+  render: ({ stack }) => html` <template layout="column height::100vh">${stack}</template> `,
 });
 ```
 
@@ -354,7 +355,7 @@ 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
+    store.clear([Model]); // one clear after the batch settles
   }, 300);
 });
 ```

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

@@ -1,4 +1,5 @@
 # Testing
+
 ## Philosophy, Tools & Patterns
 
 > How we test in a no-build web component project.
@@ -17,15 +18,15 @@ 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. |
+| 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.                      |
 
 ---
 
@@ -33,10 +34,10 @@ bugs at the boundary where they're introduced, not 5 layers up.
 
 ### 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 |
+| 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.
 
@@ -77,24 +78,24 @@ server.test.js                  ← node:test
 
 ### Test File Naming
 
-| Code file | Test file |
-|---|---|
+| 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` |
+| `UserModel.js`  | `UserModel.test.js`  |
+| `src/server.js` | `server.test.js`     |
 
 ### What Gets Tested
 
-| Layer | What to assert |
-|---|---|
-| **Utils** | Input → output. Edge cases. |
+| 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. |
+| **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.                  |
 
 ---
 
@@ -191,7 +192,9 @@ describe('app-button', () => {
   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.addEventListener('click', () => {
+      clicked = true;
+    });
     el.shadowRoot.querySelector('button').click();
     expect(clicked).to.be.true;
   });
@@ -230,9 +233,7 @@ import { playwrightLauncher } from '@web/test-runner-playwright';
 export default {
   files: 'src/components/**/*.test.js',
   nodeResolve: true,
-  browsers: [
-    playwrightLauncher({ product: 'chromium' }),
-  ],
+  browsers: [playwrightLauncher({ product: 'chromium' })],
 };
 ```
 
@@ -255,14 +256,14 @@ export default {
 
 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 |
+| 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/src/public/index.html

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