@techninja/clearstack 0.2.0

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

@@ -0,0 +1,481 @@
+# Component Patterns
+## Authoring, Styling, Templates & JSDoc Typing
+
+> How to write, style, and type components in this framework.
+> See [FRONTEND_IMPLEMENTATION_RULES.md](./FRONTEND_IMPLEMENTATION_RULES.md) for
+> project structure and atomic design hierarchy.
+
+---
+
+## Component Authoring
+
+Every component is a plain object passed to `define()`. No classes.
+
+### Minimal Component
+
+```javascript
+import { html, define } from 'hybrids';
+
+export default define({
+  tag: 'app-button',
+  label: '',
+  render: {
+    value: ({ label }) => html`<button>${label}</button>`,
+    shadow: false,
+  },
+});
+```
+
+Note: `shadow: false` is required on every component in this framework.
+See the Light DOM section below for why.
+
+### Property Types
+
+Properties are declared as default values. Hybrids infers the type:
+
+| Declaration | Type | Reflected to attribute |
+|---|---|---|
+| `count: 0` | Number | Yes |
+| `label: ''` | String | Yes |
+| `active: false` | Boolean | Yes |
+| `items: []` | Array/Object | No |
+| `onClick: () => {}` | Function | No |
+
+### Property Descriptors
+
+For advanced behavior, use the descriptor form:
+
+```javascript
+export default define({
+  tag: 'app-timer',
+  elapsed: {
+    value: 0,
+    connect(host, key, invalidate) {
+      const id = setInterval(() => { host.elapsed++; }, 1000);
+      return () => clearInterval(id);  // cleanup on disconnect
+    },
+    observe(host, value) {
+      if (value >= 60) dispatch(host, 'timeout');
+    },
+  },
+  render: ({ elapsed }) => html`<span>${elapsed}s</span>`,
+});
+```
+
+| Descriptor field | Purpose |
+|---|---|
+| `value` | Default value or factory function |
+| `connect(host, key, invalidate)` | Runs on DOM connect. Return cleanup fn. |
+| `observe(host, value, lastValue)` | Runs when value changes |
+| `reflect` | `true` or `(value) => string` — sync to attribute |
+
+### Event Handling
+
+Always bind events in templates. Never use `addEventListener`.
+
+```javascript
+function handleClick(host, event) {
+  host.count++;
+}
+
+export default define({
+  tag: 'app-counter',
+  count: 0,
+  render: ({ count }) => html`
+    <button onclick="${handleClick}">Count: ${count}</button>
+  `,
+});
+```
+
+For input binding, use `html.set()`:
+
+```javascript
+render: ({ query }) => html`
+  <input value="${query}" oninput="${html.set('query')}" />
+`,
+```
+
+### Event Handler Host Context
+
+In hybrids, the `host` parameter in an event handler resolves to the
+**nearest hybrids component ancestor** in the DOM, not necessarily the
+component that defined the handler.
+
+This matters when passing templates as properties to other components
+(e.g. `page-layout`'s `content` property). Inline arrow functions will
+receive the **wrong host** — the template component, not your page.
+
+```javascript
+// ❌ BAD — host is page-layout, not my-page
+render: {
+  value: ({ showForm }) => html`
+    <page-layout content="${html`
+      <app-button onpress="${(host) => { host.showForm = true; }}"></app-button>
+    `}"></page-layout>
+  `,
+},
+
+// ✅ GOOD — named function, hybrids resolves host to the defining component
+function toggleForm(host) {
+  host.showForm = !host.showForm;
+}
+// ... in render:
+<app-button onpress="${toggleForm}"></app-button>
+```
+
+**Rule: always use named functions for event handlers.** This ensures
+hybrids resolves `host` to the component that owns the property, not
+the nearest ancestor in the DOM tree. Inline arrows in nested templates
+are the #1 source of "nothing happens when I click" bugs.
+
+### Custom Events Must Bubble
+
+In light DOM, custom events dispatched from child components must set
+`bubbles: true` to reach parent listeners — especially when content is
+passed as a template property through intermediate components.
+
+```javascript
+// ❌ BAD — event won't reach listeners above the dispatching component
+dispatch(host, 'press');
+
+// ✅ GOOD — event bubbles through the DOM tree
+dispatch(host, 'press', { bubbles: true });
+```
+
+### When to Use `app-button` vs Plain `<button>`
+
+Custom events from atoms can be unreliable when templates are passed as
+properties through intermediate components (e.g. `page-layout`'s `content`).
+The host context and event bubbling path may not resolve as expected.
+
+| Context | Use | Why |
+|---|---|---|
+| Inside a component's own template | `app-button` | Host context is correct, events bubble normally |
+| Inside a `content` template property | Plain `<button class="btn">` | Direct `onclick` handler, no custom event needed |
+| Reusable molecule/organism | `app-button` | Encapsulated, predictable host |
+| Page-level actions | Plain `<button class="btn">` | Simplest, most reliable |
+
+The `.btn` classes are global (defined in `buttons.css`), so plain buttons
+look identical to `app-button`. Use the atom when you need its component
+API; use a plain button when you need reliable click handling in nested
+templates.
+
+### SVG Content via innerHTML
+
+Hybrids' `html` template doesn't support dynamic SVG content well. For
+canvas/whiteboard components that build SVG from data, use `innerHTML`
+on a wrapper div:
+
+```javascript
+render: {
+  value: (host) => html`
+    <div class="canvas" innerHTML="${buildSvgString(host.objects)}"></div>
+  `,
+}
+```
+
+Event listeners must be re-attached in `observe` since `innerHTML`
+replaces the DOM. Use a flag to avoid duplicate binding, and attach
+persistent listeners (like `keydown`) to the host element instead.
+
+### Coordinate Transforms for Rotated Objects
+
+When objects have rotation via an outer `<g transform="rotate(...)">`:
+
+- **Move:** Shift both the inner translate AND the rotation center by the
+  same screen-space delta. No trigonometry needed.
+- **Resize:** Unrotate the drag delta to align with the object's local axes.
+- **Rotation center:** Store `rotationCx`/`rotationCy` on the object data
+  so it persists across renders and reloads.
+
+### Light DOM (Default)
+
+All components in this framework use **light DOM** (`shadow: false`). This
+means global stylesheets, shared CSS classes, and design tokens all apply
+automatically — no style injection boilerplate.
+
+```javascript
+export default define({
+  tag: 'app-button',
+  label: '',
+  render: {
+    value: ({ label }) => html`<button>${label}</button>`,
+    shadow: false,
+  },
+});
+```
+
+With light DOM, the component's rendered HTML lives in the main document
+tree. CSS scoping is achieved through **native CSS nesting** on the tag name
+(see Styling section below), not through shadow boundary.
+
+### When to Use Shadow DOM
+
+Shadow DOM is the exception, not the rule. Enable it only when:
+
+| Situation | Why shadow DOM |
+|---|---|
+| Wrapping a third-party widget | Prevent its styles from leaking out |
+| Distributing a standalone component | Consumer's styles must not break it |
+| Embedding untrusted content | Hard style boundary needed |
+
+For an internal application where you control all the CSS, shadow DOM
+creates more problems than it solves — you end up fighting it to inject
+shared styles into every component.
+
+### Inline Styles for Small Additions
+
+When a component needs a few custom styles that don't warrant a `.css` file,
+use `.css()` directly on the template:
+
+```javascript
+render: {
+  value: ({ active }) => html`
+    <span class="${active ? 'active' : ''}">${label}</span>
+  `.css`
+    :host { display: inline-block; }
+    .active { font-weight: bold; color: var(--color-primary); }
+  `,
+  shadow: false,
+},
+```
+
+This keeps small style additions co-located with the template. When inline
+styles grow past ~10 rules, move them to the component's `.css` file.
+
+### Content Composition (No Slots)
+
+**`<slot>` is a shadow DOM feature.** It does not work with `shadow: false`.
+Hybrids will throw if it finds a `<slot>` in a light DOM template.
+
+**Template components break host context.** If you pass content as a property
+to another component (e.g. `<page-layout content="${html`...`}">`), event
+handlers inside that content will resolve `host` to the template component,
+not the page that defined the handler. This makes buttons and forms silently
+fail.
+
+The solution: **use template functions, not template components**, for
+page-level layout:
+
+```javascript
+// Template as a function — no component boundary, host context preserved
+export function pageLayout(title, content) {
+  return html`
+    <div class="page-layout">
+      <header>${title}</header>
+      <main>${content}</main>
+    </div>
+  `;
+}
+
+// Page calls the function directly in its render
+render: {
+  value: ({ items }) => pageLayout('Home', html`
+    <button onclick="${handleClick}">Works!</button>
+    <ul>${items.map(...)}</ul>
+  `),
+  shadow: false,
+},
+```
+
+Because `pageLayout` is a plain function (not a `define()`'d component),
+there is no intermediate hybrids element in the DOM tree. The `onclick`
+handler resolves `host` to the page component as expected.
+
+---
+
+## Styling
+
+### Style Inheritance Model
+
+Because components use light DOM, styles flow naturally:
+
+```
+public/index.html
+  ├── <link> src/styles/reset.css      ← base reset
+  ├── <link> src/styles/tokens.css     ← :root custom properties
+  ├── <link> src/styles/shared.css     ← error states, icons, utilities
+  └── <link> src/styles/components.css ← all component styles (loaded once)
+```
+
+Every component automatically inherits all shared styles. No injection needed.
+
+### Three Layers of CSS
+
+| Layer | File(s) | What goes here |
+|---|---|---|
+| **Tokens** | `tokens.css` | `:root` custom properties — colors, spacing, type, radii, shadows |
+| **Shared** | `shared.css` | Error states, loading states, icon base, screen-reader utils, transitions |
+| **Components** | `components.css` + per-component `.css` | Styles scoped to tag names via native CSS nesting |
+
+### Per-Component CSS with Native Nesting
+
+Each component has a `.css` file that scopes styles using the tag name
+as the top-level selector, with native CSS nesting inside:
+
+```css
+/* app-button/app-button.css */
+app-button {
+  display: inline-block;
+
+  & button {
+    padding: var(--space-sm) var(--space-md);
+    border: none;
+    border-radius: var(--radius-md);
+    background: var(--color-primary);
+    color: white;
+    font: inherit;
+
+    &:hover { background: var(--color-primary-hover); }
+    &:disabled { opacity: 0.5; cursor: not-allowed; }
+  }
+
+  &[variant="secondary"] button {
+    background: var(--color-surface);
+    color: var(--color-text);
+    border: 1px solid var(--color-border);
+  }
+
+  &[variant="ghost"] button {
+    background: transparent;
+    color: var(--color-primary);
+  }
+}
+```
+
+This gives you **scoping by convention** — styles only apply inside the
+component's tag. No shadow DOM needed, no style collisions.
+
+### Loading Component Styles
+
+Component `.css` files are imported into a single `src/styles/components.css`
+that aggregates them:
+
+```css
+/* src/styles/components.css */
+@import '../components/atoms/app-button/app-button.css';
+@import '../components/atoms/app-badge/app-badge.css';
+/* ... add as components are created ... */
+```
+
+This file is loaded once in `index.html`. Adding a new component means
+adding one `@import` line.
+
+### Design Tokens
+
+Shared tokens live in `src/styles/tokens.css` as custom properties on `:root`.
+These pierce all boundaries (even shadow DOM if ever used):
+
+```css
+:root {
+  --color-primary: #2563eb;
+  --space-md: 1rem;
+  --radius-md: 0.375rem;
+}
+```
+
+Components reference tokens, never hardcode values.
+
+### Rules
+
+- No CSS-in-JS libraries. No preprocessors. Native CSS only.
+- One `.css` file per component, scoped via tag-name nesting.
+- Shared patterns (error, loading, icons) go in `shared.css`.
+- Use custom properties for all colors, spacing, and typography.
+- Small inline styles via `.css()` are fine — move to file at ~10 rules.
+
+---
+
+## Templates & Layout Engine
+
+### Tagged Template Literals
+
+All templates use `html` from hybrids:
+
+```javascript
+html`<div>${expression}</div>`
+```
+
+Expressions can be: strings, numbers, booleans, other templates, arrays of
+templates, Promises (via `html.resolve()`), or event handlers.
+
+### Layout Attributes
+
+Hybrids' layout engine lets you declare CSS layout inline:
+
+```javascript
+render: () => html`
+  <template layout="column gap:2">
+    <header layout="row center gap">...</header>
+    <main layout="grow">...</main>
+    <footer layout@768px="hidden">...</footer>
+  </template>
+`,
+```
+
+| Attribute | Effect |
+|---|---|
+| `layout="row"` | Flexbox row |
+| `layout="column"` | Flexbox column |
+| `layout="grid:1\|max"` | CSS grid with defined tracks |
+| `layout="grow"` | `flex-grow: 1` |
+| `layout="center"` | Center content |
+| `layout="gap:2"` | Gap using spacing scale |
+| `layout@768px="hidden"` | Responsive — applies at ≥768px |
+
+### Keyed Lists
+
+For efficient list rendering, use `.key()`:
+
+```javascript
+render: ({ items }) => html`
+  <ul>
+    ${items.map(item => html`
+      <li>${item.name}</li>
+    `.key(item.id))}
+  </ul>
+`,
+```
+
+### Async Content
+
+```javascript
+render: ({ dataPromise }) => html`
+  <div>
+    ${html.resolve(dataPromise, html`<span>Loading...</span>`)}
+  </div>
+`,
+```
+
+---
+
+## File Size & Decomposition
+
+**Hard limit: 150 lines per file.** This applies to `.js` and `.css` alike.
+
+### When a file grows too large
+
+| Situation | Action |
+|---|---|
+| Component logic exceeds 150 lines | Extract helpers to `src/utils/` |
+| Template is too complex | Split into child sub-components |
+| CSS exceeds 150 lines | Extract shared patterns to `src/styles/` |
+| Store model has many relations | Split related models into own files |
+
+### What counts toward the limit
+
+- All lines including imports, blank lines, and comments.
+- JSDoc blocks count. Keep them concise.
+
+### What does NOT split
+
+- The 3-file component structure (`component.js`, `component.css`, `index.js`)
+  stays together in one directory. Don't add more files to a component dir.
+
+---
+
+## JSDoc Typing Strategy
+
+See [JSDOC_TYPING.md](./JSDOC_TYPING.md) for the full JSDoc typing
+specification, including component properties, store models, event handlers,
+and validation rules.

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

@@ -0,0 +1,226 @@
+# Conventions
+## Naming Rules & Anti-Patterns
+
+> Quick reference for naming and what to avoid.
+> See [FRONTEND_IMPLEMENTATION_RULES.md](./FRONTEND_IMPLEMENTATION_RULES.md) for
+> the full specification index.
+
+---
+
+## Naming Conventions
+
+### Component Tags
+
+All custom element tags use **kebab-case** with an `app-` prefix:
+
+| Thing | Name | Tag |
+|---|---|---|
+| Button atom | `app-button` | `<app-button>` |
+| Header organism | `app-header` | `<app-header>` |
+| Page layout template | `page-layout` | `<page-layout>` |
+| Home page view | `home-view` | `<home-view>` |
+
+The `app-` prefix prevents collisions with native elements and third-party
+components. Page views and templates may drop the prefix when unambiguous.
+
+### Files & Directories
+
+| Type | Convention | Example |
+|---|---|---|
+| Component file | Match tag name | `app-button.js` |
+| Component CSS | Match tag name | `app-button.css` |
+| Component dir | Match tag name | `app-button/` |
+| Re-export | Always `index.js` | `index.js` |
+| Store model | PascalCase | `UserModel.js` |
+| Utility function | camelCase | `formatDate.js` |
+| Shared CSS | Descriptive kebab | `tokens.css`, `reset.css` |
+
+### JavaScript
+
+| Type | Convention | Example |
+|---|---|---|
+| Event handlers | `handle` + action | `handleClick`, `handleSubmit` |
+| Store models | PascalCase noun | `UserModel`, `AppState` |
+| Utility functions | camelCase verb | `formatDate`, `parseQuery` |
+| Constants | UPPER_SNAKE | `MAX_RETRIES`, `API_BASE` |
+| JSDoc typedefs | PascalCase | `@typedef {Object} User` |
+
+---
+
+## Anti-Patterns
+
+### ❌ Never Do This
+
+**DOM queries inside components:**
+```javascript
+// BAD — breaks encapsulation, ignores shadow DOM
+const el = document.querySelector('.my-thing');
+```
+
+**Manual event listeners:**
+```javascript
+// BAD — leaks memory, bypasses hybrids lifecycle
+connectedCallback() {
+  this.addEventListener('click', this.onClick);
+}
+```
+
+**Global mutable state:**
+```javascript
+// BAD — invisible dependencies, untraceable bugs
+window.appState = { user: null };
+```
+
+**Imperative DOM manipulation:**
+```javascript
+// BAD — fights the reactive render cycle
+host.shadowRoot.querySelector('span').textContent = 'updated';
+```
+
+**Business logic in render:**
+```javascript
+// BAD — render should be pure projection of state
+render: ({ items }) => html`
+  <ul>${items.filter(i => i.active).sort((a,b) => a.name.localeCompare(b.name)).map(...)}</ul>
+`,
+```
+
+**Files over 150 lines:**
+```
+// BAD — extract to utils/ or split into sub-components
+```
+
+**Deep nesting (>3 component levels):**
+```
+// BAD — flatten by composing at the page level
+<app-layout>
+  <app-sidebar>
+    <nav-section>
+      <nav-group>        ← too deep
+```
+
+---
+
+## Error Handling
+
+Errors are handled **at the boundary where they are actionable.** Each layer
+has a single responsibility — catch only what you can meaningfully respond to,
+let everything else propagate.
+
+### Boundary Rules
+
+| Layer | Responsibility | Example |
+|---|---|---|
+| **Utils** | Never catch. Return error values or throw. Caller decides. | `formatDate(null)` returns `''` |
+| **Store connectors** | Let fetch failures propagate. Hybrids' `store.error()` catches them. | Don't wrap fetch in try/catch |
+| **Components** | Display `store.pending()` / `store.error()` states. Never try/catch in render. | `${store.error(model) && html`<div class="error-message">...</div>`}` |
+| **Event handlers** | Guard with `store.ready()` before accessing store properties. | `if (!store.ready(host.state)) return;` |
+| **Server routes** | Return HTTP status + JSON error body. Never crash the process. | `res.status(404).json({ error: 'Not found' })` |
+| **Server infra** | Handle process-level errors with clear messages and exit codes. | Port conflict → log message → `process.exit(1)` |
+
+### Why This Matters
+
+If a store connector catches its own fetch error, `store.error()` never fires
+and the component can't show an error state. If a utility swallows an
+exception, the caller can't decide how to handle it. Each layer trusts the
+next layer up to handle what it can't.
+
+### ❌ Don't
+
+```javascript
+// BAD — swallows the error, store.error() never fires
+[store.connect]: {
+  get: async (id) => {
+    try { return await fetch(`/api/items/${id}`).then(r => r.json()); }
+    catch { return null; }  // silent failure
+  },
+}
+```
+
+```javascript
+// BAD — accesses store properties without ready guard
+function toggle(host) {
+  const next = host.state.theme === 'light' ? 'dark' : 'light';
+  store.set(host.state, { theme: next });  // crashes if model is in error state
+}
+```
+
+### ✅ Do
+
+```javascript
+// GOOD — let it throw, component handles via store.error()
+[store.connect]: {
+  get: (id) => fetch(`/api/items/${id}`).then(r => r.json()),
+}
+```
+
+```javascript
+// GOOD — guard before accessing properties
+function toggle(host) {
+  if (!store.ready(host.state)) return;
+  const next = host.state.theme === 'light' ? 'dark' : 'light';
+  store.set(host.state, { theme: next });
+}
+```
+
+---
+
+### ✅ Always Do This
+
+**Declarative event binding:**
+```javascript
+html`<button onclick="${handleClick}">Go</button>`
+```
+
+**Store for shared state:**
+```javascript
+state: store(AppState),
+```
+
+**Pure functions for logic:**
+```javascript
+// In src/utils/filterActive.js
+export const filterActive = (items) => items.filter(i => i.active);
+
+// In component
+import { filterActive } from '../../utils/filterActive.js';
+render: ({ items }) => html`<ul>${filterActive(items).map(...)}</ul>`,
+```
+
+**JSDoc on all exports:**
+```javascript
+/** @param {User} user */
+export const fullName = (user) => `${user.firstName} ${user.lastName}`;
+```
+
+---
+
+## File Size: Soft Warnings Before Hard Limits
+
+The 150-line limit is a hard gate in CI, but treat **~120 lines as a yellow
+light.** When a file passes 120 lines:
+
+1. Add a `// SPLIT CANDIDATE:` comment noting where a logical split could happen
+2. Continue working — don't split mid-feature
+3. Split when the file hits 150 or when the feature is complete
+
+This prevents premature extraction while keeping the eventual split obvious.
+
+```javascript
+// SPLIT CANDIDATE: moveObj/resizeObj could extract to canvasTransform.js
+function moveObj(o, dx, dy) { ... }
+```
+
+---
+
+## Session Retrospective
+
+At the end of each implementation session, ask:
+
+1. **What patterns did we discover?** Document in the relevant spec doc.
+2. **What broke that we didn't expect?** Add to BUILD_LOG discoveries.
+3. **What tests would catch the bugs we found?** Write them before committing.
+4. **Did any files grow past the yellow light?** Split or add split markers.
+5. **Did the spec need correction?** Update it — the spec improves through use.
+
+This practice is what keeps the spec alive and accurate.