@jay-framework/jay-stack-cli 0.15.5 → 0.16.0

package/agent-kit-template/plugin/component-data.md

@@ -0,0 +1,109 @@
+# Immutable Data and Patching
+
+In Jay, ViewState data is immutable. Never mutate objects directly — use signals and JSON Patch for updates.
+
+## Immutable Data Model
+
+ViewState objects passed to the render function are immutable snapshots. The framework compares old and new snapshots to determine what changed in the DOM.
+
+```typescript
+// WRONG — never mutate directly
+viewState.items.push(newItem);
+viewState.count = 5;
+
+// RIGHT — return new values from signals
+const [count, setCount] = createSignal(0);
+setCount(5);
+
+return { render: () => ({ count: count() }) };
+```
+
+## JSON Patch for Complex Updates
+
+For objects with many fields, use `createPatchableSignal` with JSON Patch operations instead of replacing the entire object:
+
+```typescript
+import { createPatchableSignal } from '@jay-framework/component';
+import { REPLACE, ADD, REMOVE } from '@jay-framework/json-patch';
+
+const [state, setState, patchState] = createPatchableSignal({
+  title: 'Product',
+  price: 29.99,
+  tags: ['sale', 'featured'],
+  details: { color: 'red', size: 'M' },
+});
+```
+
+### Patch Operations
+
+**REPLACE** — Update an existing value:
+
+```typescript
+patchState({ op: REPLACE, path: ['price'], value: 19.99 });
+patchState({ op: REPLACE, path: ['details', 'color'], value: 'blue' });
+```
+
+**ADD** — Add a new field or array item:
+
+```typescript
+patchState({ op: ADD, path: ['tags', 1], value: 'new-tag' }); // Insert at index 1
+patchState({ op: ADD, path: ['details', 'weight'], value: '500g' });
+```
+
+**REMOVE** — Remove a field or array item:
+
+```typescript
+patchState({ op: REMOVE, path: ['tags', 0] }); // Remove first tag
+patchState({ op: REMOVE, path: ['details', 'size'] });
+```
+
+**MOVE** — Move a value from one path to another:
+
+```typescript
+import { MOVE } from '@jay-framework/json-patch';
+
+patchState({ op: MOVE, from: ['tags', 0], path: ['tags', 2] }); // Reorder array item
+patchState({ op: MOVE, from: ['details', 'color'], path: ['primaryColor'] }); // Relocate field
+```
+
+### Multiple Patches
+
+Apply multiple patches at once — the framework batches them into a single update:
+
+```typescript
+patchState(
+  { op: REPLACE, path: ['price'], value: 19.99 },
+  { op: REPLACE, path: ['details', 'color'], value: 'blue' },
+);
+```
+
+### When to Use Patch vs Set
+
+- **Simple values** (number, string, boolean): use `setSignal(newValue)`
+- **Objects with few fields**: use `setSignal({ ...old, field: newValue })`
+- **Complex nested objects**: use `patchState` for surgical updates
+- **Arrays with identity tracking**: use `patchState` with ADD/REMOVE
+
+## createDerivedArray (Map Hook)
+
+Transform an array reactively with smart caching. Only remaps items that actually changed:
+
+```typescript
+import { createDerivedArray } from '@jay-framework/component';
+
+const displayProducts = createDerivedArray(
+  () => products(),
+  (item, index, length) => ({
+    label: `${item().name} - ${formatPrice(item().price)}`,
+    position: `${index() + 1} of ${length()}`,
+  }),
+);
+```
+
+Key behavior:
+
+- If an item's object identity hasn't changed, the cached mapped result is reused
+- `index()` and `length()` are tracked — if you don't call them, changes to index/length won't trigger a remap
+- Returns a `Getter<U[]>` — read with `displayProducts()`
+
+See [component-state.md](component-state.md) for the full hook reference.

package/agent-kit-template/plugin/component-refs.md

@@ -0,0 +1,117 @@
+# Component Refs
+
+Refs provide access to DOM elements declared as `interactive` in the contract. They are the second parameter of the interactive constructor.
+
+## Single Refs
+
+A ref maps to one DOM element:
+
+```yaml
+# Contract
+- tag: addToCart
+  type: interactive
+  elementType: HTMLButtonElement
+```
+
+```typescript
+// Component
+.withInteractive(function MyComp(props, refs) {
+    refs.addToCart.onClick(() => {
+        // handle click
+    });
+})
+```
+
+### Ref Methods
+
+Refs provide type-safe access to the DOM element:
+
+```typescript
+refs.submitButton.onClick(() => {
+  /* ... */
+});
+
+// exec$ gives direct access to the element and current ViewState
+refs.submitButton.exec$((element, viewState) => {
+  element.disabled = viewState.isSubmitting;
+});
+```
+
+## Collection Refs
+
+When an interactive tag is inside a `repeated` sub-contract, the ref becomes a collection. In jay-html, collection refs use the `$` suffix:
+
+```html
+<div forEach="items" trackBy="id">
+  <button ref="itemButton$">Click</button>
+</div>
+```
+
+The `$` is stripped from the name in the contract and component code:
+
+```yaml
+# Contract
+- tag: items
+  type: sub-contract
+  repeated: true
+  trackBy: id
+  tags:
+    - tag: id
+      type: data
+      dataType: string
+    - tag: itemButton
+      type: interactive
+      elementType: HTMLButtonElement
+```
+
+### Collection Ref Methods
+
+```typescript
+// Map over all items in the collection
+const labels = refs.itemButton.map((proxy, viewState, coordinate) => {
+  return viewState.name;
+});
+
+// Find a specific item
+const target = refs.itemButton.find((viewState) => viewState.id === 'target-id');
+
+// Find by coordinate
+const target = refs.itemButton.find((viewState, coordinate) =>
+  sameCoordinate(coordinate, ['item-2', 'itemButton']),
+);
+```
+
+## Element Types
+
+Common element types for interactive tags:
+
+| Element Type          | Use For               |
+| --------------------- | --------------------- |
+| `HTMLButtonElement`   | Buttons, clickable    |
+| `HTMLAnchorElement`   | Links                 |
+| `HTMLInputElement`    | Text inputs, checkbox |
+| `HTMLSelectElement`   | Dropdowns             |
+| `HTMLTextAreaElement` | Multi-line text       |
+| `HTMLFormElement`     | Forms                 |
+| `HTMLDivElement`      | Generic containers    |
+
+Multiple element types (when the same ref may bind to different elements):
+
+```yaml
+- tag: trigger
+  type: interactive
+  elementType: HTMLButtonElement | HTMLAnchorElement
+```
+
+## Data + Interactive
+
+A tag can be both data and interactive:
+
+```yaml
+- tag: quantityInput
+  type: [data, interactive]
+  dataType: number
+  elementType: HTMLInputElement
+```
+
+This generates both a ViewState field and a ref.

package/agent-kit-template/plugin/component-state.md

@@ -0,0 +1,140 @@
+# Component State Hooks
+
+All hooks are used inside the interactive phase (the `withInteractive` constructor function). They provide reactive state management for client-side behavior.
+
+## createSignal
+
+Creates a reactive getter/setter pair:
+
+```typescript
+import { createSignal } from '@jay-framework/component';
+
+const [count, setCount] = createSignal(0);
+
+// Read
+count(); // 0
+
+// Write
+setCount(5); // set to 5
+setCount((n) => n + 1); // increment
+```
+
+Can initialize from a getter (reactive dependency):
+
+```typescript
+const [label, setLabel] = createSignal(() => 'Hello ' + props.name());
+```
+
+## createPatchableSignal
+
+Creates a signal with JSON Patch support for fine-grained updates to complex objects:
+
+```typescript
+import { createPatchableSignal } from '@jay-framework/component';
+import { REPLACE } from '@jay-framework/json-patch';
+
+const [data, setData, patchData] = createPatchableSignal({
+  label: 'Hello',
+  count: 0,
+  nested: { value: 42 },
+});
+
+// Patch a specific field
+patchData({ op: REPLACE, path: ['label'], value: 'Updated' });
+
+// Patch nested field
+patchData({ op: REPLACE, path: ['nested', 'value'], value: 99 });
+```
+
+See [component-data.md](component-data.md) for more on immutable data and patching.
+
+## createMemo
+
+Creates a memoized computed value that recalculates only when dependencies change:
+
+```typescript
+import { createMemo } from '@jay-framework/component';
+
+const fullName = createMemo(() => `${firstName()} ${lastName()}`);
+
+// Read
+fullName(); // recomputes only when firstName() or lastName() change
+```
+
+With initial value:
+
+```typescript
+const total = createMemo((prev) => prev + latestValue(), 0);
+```
+
+## createEffect
+
+Registers a side effect that runs on mount and when dependencies change. Optional cleanup function:
+
+```typescript
+import { createEffect } from '@jay-framework/component';
+
+createEffect(() => {
+  const handler = () => setWindowWidth(window.innerWidth);
+  window.addEventListener('resize', handler);
+  return () => window.removeEventListener('resize', handler); // cleanup
+});
+```
+
+Effects track reactive dependencies automatically:
+
+```typescript
+createEffect(() => {
+  document.title = `${count()} items`; // reruns when count() changes
+});
+```
+
+## createDerivedArray
+
+Efficiently maps an array with smart caching. Only remaps items that actually changed:
+
+```typescript
+import { createDerivedArray } from '@jay-framework/component';
+
+const displayItems = createDerivedArray(
+  () => products(),
+  (item, index, length) => ({
+    name: item().name,
+    displayPrice: formatPrice(item().price),
+    isLast: index() === length() - 1,
+  }),
+);
+
+// Read the mapped array
+displayItems();
+```
+
+Key optimizations:
+
+- Reuses mapped items when the source item hasn't changed
+- Only tracks `index()` and `length()` if you actually call them
+- Uses object identity (not deep equality) for cache hits
+
+## createEvent
+
+Creates an event emitter for component-to-parent communication:
+
+```typescript
+import { createEvent } from '@jay-framework/component';
+
+const onChange = createEvent<{ value: number }>((emitter) => {
+  emitter.emit({ value: count() });
+});
+```
+
+## useReactive
+
+Gets the current reactive context for advanced use cases:
+
+```typescript
+import { useReactive } from '@jay-framework/component';
+
+const reactive = useReactive();
+```
+
+Most components won't need this — prefer the higher-level hooks above.

package/agent-kit-template/plugin/component-structure.md

@@ -0,0 +1,174 @@
+# Component Structure
+
+Full-stack components use `makeJayStackComponent` with a fluent builder API and three rendering phases.
+
+## Basic Structure
+
+```typescript
+import { makeJayStackComponent, phaseOutput } from '@jay-framework/fullstack-component';
+import type { MyContract } from './my-contract.generated';
+
+export const myComponent = makeJayStackComponent<MyContract>()
+  .withSlowlyRender(async (props) => {
+    const data = await fetchStaticData();
+    return phaseOutput(
+      { title: data.title, description: data.description }, // ViewState
+      { productId: data.id }, // CarryForward
+    );
+  })
+  .withFastRender(async (props) => {
+    return phaseOutput({ price: await getPrice(), inStock: true }, {});
+  })
+  .withInteractive(function MyComponent(props, refs) {
+    // Client-side hooks here
+    return { render: () => ({}) };
+  });
+```
+
+## Builder API
+
+### `.withProps<T>()`
+
+Declare the props type (must match contract `props`):
+
+```typescript
+makeJayStackComponent<MyContract>().withProps<{ productId: string; currency?: string }>();
+```
+
+### `.withServices(...markers)`
+
+Inject server-side services:
+
+```typescript
+.withServices(DATABASE_SERVICE, CACHE_SERVICE)
+.withSlowlyRender(async (props, db, cache) => {
+    // db and cache are injected
+})
+```
+
+### `.withContexts(...markers)`
+
+Consume client-side contexts in the interactive phase:
+
+```typescript
+.withContexts(CART_CONTEXT)
+.withInteractive(function MyComp(props, refs, cartCtx) {
+    // cartCtx available in interactive phase
+})
+```
+
+### `.withLoadParams(fn)`
+
+Generate URL params for SSG (static site generation). Returns an async iterable of param arrays:
+
+```typescript
+.withLoadParams(async function* (db) {
+    const products = await db.getAllProducts();
+    yield products.map(p => ({ slug: p.slug }));
+})
+```
+
+### `.withSlowlyRender(fn)` — Build-time rendering
+
+Runs during SSG. Has access to props and services. Returns `phaseOutput(viewState, carryForward)`.
+
+CarryForward data is passed to the fast phase but not included in the ViewState.
+
+```typescript
+.withSlowlyRender(async (props, db) => {
+    const product = await db.getProduct(props.slug);
+    if (!product) return notFound('Product not found');
+    return phaseOutput(
+        { title: product.name, description: product.desc },
+        { productId: product.id },  // Available in fast phase
+    );
+})
+```
+
+### `.withFastRender(fn)` — Request-time rendering
+
+Runs on each request. Receives props (including `query` for query parameters) and carry-forward from slow phase.
+
+```typescript
+.withFastRender(async (props, db) => {
+    const price = await db.getPrice(props.carryForward.productId);
+    return phaseOutput({ price, inStock: price > 0 }, {});
+})
+```
+
+### `.withClientDefaults(fn)` — Default client ViewState
+
+Provides default values for client-side ViewState before hydration:
+
+```typescript
+.withClientDefaults(() => ({
+    quantity: 1,
+    selectedVariant: 'default',
+}))
+```
+
+### `.withInteractive(ComponentConstructor)` — Client-side logic
+
+The interactive phase runs in the browser. Use hooks here (see component-state.md):
+
+```typescript
+.withInteractive(function ProductPage(props, refs) {
+    const [quantity, setQuantity] = createSignal(1);
+
+    refs.addToCart.onClick(() => {
+        addToCartAction({ productId: props.productId, quantity: quantity() });
+    });
+
+    return {
+        render: () => ({
+            quantity: quantity(),
+        }),
+    };
+})
+```
+
+## Render Return Types
+
+Each phase can return:
+
+- `phaseOutput(viewState, carryForward)` — success
+- `notFound()`, `badRequest()`, `unauthorized()`, `forbidden()` — client errors
+- `serverError5xx(status, message)` — server errors
+- `redirect3xx(status, location)` — redirects
+
+See [render-results.md](render-results.md) for details.
+
+## Props and Contract Alignment
+
+The component's props type must match the contract's `props` section:
+
+```yaml
+# Contract
+props:
+  - name: productId
+    type: string
+    required: true
+```
+
+```typescript
+// Component
+makeJayStackComponent<MyContract>().withProps<{ productId: string }>();
+```
+
+## Params and Contract Alignment
+
+If the contract has `params`, the component should use `withLoadParams` and the route must have matching dynamic segments:
+
+```yaml
+# Contract
+params:
+  slug: string
+```
+
+```typescript
+// Component
+.withLoadParams(async function* (db) {
+    const items = await db.getAll();
+    yield items.map(i => ({ slug: i.slug }));
+})
+```