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

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 }));
+})
+```

package/agent-kit-template/plugin/contracts-guide.md

@@ -0,0 +1,193 @@
+# Contract Authoring Guide
+
+Contracts (`.jay-contract` files) are the source of truth for a component's data shape. Define the contract before implementing the component.
+
+## Basic Structure
+
+```yaml
+name: ProductCard
+description: Displays a single product with price and add-to-cart. Use for product grids and featured sections.
+props:
+  - name: productId
+    type: string
+    required: true
+    description: The product to display
+params:
+  slug: string
+tags:
+  - tag: name
+    type: data
+    dataType: string
+    phase: slow
+```
+
+## Tag Types
+
+### `data` — Read-only values
+
+```yaml
+- tag: productName
+  type: data
+  dataType: string # string (default), number, boolean, date
+  required: true # optional, defaults to false
+  phase: slow # slow, fast, or fast+interactive
+  description: Display name
+```
+
+### `variant` — Enum/boolean for conditionals
+
+```yaml
+- tag: status
+  type: variant
+  dataType: enum (AVAILABLE | OUT_OF_STOCK | PREORDER)
+  phase: fast+interactive
+```
+
+### `interactive` — Element refs for user interaction
+
+```yaml
+- tag: addToCart
+  type: interactive
+  elementType: HTMLButtonElement # HTMLAnchorElement, HTMLInputElement, HTMLSelectElement, etc.
+```
+
+Interactive tags are always `fast+interactive` — do not specify a phase.
+
+A tag can be both data and interactive:
+
+```yaml
+- tag: quantityInput
+  type: [data, interactive]
+  dataType: number
+  elementType: HTMLInputElement
+```
+
+### `sub-contract` — Nested objects
+
+Inline:
+
+```yaml
+- tag: pricing
+  type: sub-contract
+  tags:
+    - tag: amount
+      type: data
+      dataType: number
+    - tag: currency
+      type: data
+      dataType: string
+```
+
+Linked (reference another contract file):
+
+```yaml
+- tag: author
+  type: sub-contract
+  link: ./author.jay-contract
+```
+
+### `sub-contract` with `repeated: true` — Arrays
+
+```yaml
+- tag: items
+  type: sub-contract
+  repeated: true
+  trackBy: id # Required: identifies each item
+  phase: fast
+  tags:
+    - tag: id
+      type: data
+      dataType: string
+    - tag: name
+      type: data
+      dataType: string
+```
+
+`trackBy` must reference a `data` tag with `string` or `number` type within the same sub-contract.
+
+## Async Data
+
+Wrap any tag in `Promise<T>` with `async: true`:
+
+```yaml
+- tag: reviews
+  type: data
+  async: true
+  dataType: string # Compiles to Promise<string>
+
+- tag: relatedProducts
+  type: sub-contract
+  repeated: true
+  trackBy: id
+  async: true # Compiles to Promise<Array<...>>
+  tags:
+    - tag: id
+      type: data
+      dataType: string
+```
+
+## Rendering Phases
+
+Each tag has a phase that determines when its data is available:
+
+| Phase              | When               | Use For                                 |
+| ------------------ | ------------------ | --------------------------------------- |
+| `slow`             | Build time (SSG)   | Static content, SEO data, product names |
+| `fast`             | Request time (SSR) | Per-request data, live pricing, stock   |
+| `fast+interactive` | Request + client   | Data that also updates on the client    |
+
+**How to choose:**
+
+- Can the data be known at build time? Use `slow`
+- Does it change per request (user, time, session)? Use `fast`
+- Does it also update on the client after interaction? Use `fast+interactive`
+- Interactive tags (refs) are always `fast+interactive`
+
+**Phase rules for arrays:** Child phases must be >= parent phase. If the array is `fast`, all children must be `fast` or later.
+
+## Props vs Params
+
+### Props — Component configuration
+
+Props are passed by the parent component or jay-html template. Use for component inputs like IDs, configuration flags, display options.
+
+```yaml
+props:
+  - name: productId
+    type: string
+    required: true
+    description: The product to display
+  - name: showPricing
+    type: boolean
+    default: 'true'
+```
+
+### Params — URL route segments
+
+Params come from dynamic route segments (`[slug]`, `[[lang]]`, `[...path]`). Use for page-level routing data.
+
+```yaml
+params:
+  slug: string # required — from [slug]
+  lang: string? # optional — from [[lang]]
+  path: string[] # catch-all — from [...path]
+```
+
+## Description Field
+
+Always include a `description` at the contract level explaining when to use this contract:
+
+```yaml
+name: product-search
+description: Product listing with filters, sorting, and pagination. Use for search results and category pages.
+```
+
+## Validation Rules
+
+- Tag names must be unique at each level
+- `repeated: true` requires `trackBy`
+- `trackBy` must reference a `data` tag with `string` or `number` type
+- Interactive tags cannot have an explicit `phase`
+- Sub-contracts must have either `tags` (inline) or `link` (external), not both
+- Array children must have phase >= parent phase
+- Prop names must be unique