npm - @jay-framework/jay-stack-cli - Versions diffs - 0.15.5 → 0.15.6 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/agent-kit-template/developer/routing.md ADDED Viewed

@@ -0,0 +1,161 @@
+# Directory-Based Routing
+## Route Structure
+Pages live under `src/pages/`. Directory names become URL segments.
+```
+src/pages/
+├── page.jay-html                    → /
+├── about/
+│   └── page.jay-html                → /about
+├── products/
+│   ├── page.jay-html                → /products
+│   └── [slug]/
+│       └── page.jay-html            → /products/:slug
+├── blog/
+│   ├── page.jay-html                → /blog
+│   └── [[slug]]/
+│       └── page.jay-html            → /blog/:slug  (optional)
+└── files/
+    └── [...path]/
+        └── page.jay-html            → /files/*  (catch-all)
+```
+## Dynamic Routes
+| Syntax       | Meaning            | Example                                 |
+| ------------ | ------------------ | --------------------------------------- |
+| `[param]`    | Required parameter | `[slug]` → `/products/:slug`            |
+| `[[param]]`  | Optional parameter | `[[slug]]` → `/blog` or `/blog/my-post` |
+| `[...param]` | Catch-all          | `[...path]` → matches any sub-path      |
+## Route Priority
+Static routes match before dynamic routes (most specific first):
+1. **Static segments** (exact match) — highest priority
+2. **`[param]`** — required dynamic param
+3. **`[[param]]`** — optional param
+4. **`[...param]`** — catch-all — lowest priority
+## Static Route Overrides
+A static route can override a dynamic route for a specific URL — giving one particular page a custom layout while the dynamic route handles everything else:
+```
+src/pages/products/
+├── [slug]/page.jay-html              # dynamic: /products/:slug
+└── ceramic-flower-vase/page.jay-html # static override for this specific product
+```
+The static `ceramic-flower-vase/` route takes priority over `[slug]/` for that URL, but all other product URLs still use the dynamic route.
+### Static Override Params (`jay-params`)
+Static override routes often use the same contract as the dynamic route they override. Since the static route has no dynamic directory segment, the params must be declared explicitly using `<script type="application/jay-params">`:
+```html
+<!-- src/pages/products/ceramic-flower-vase/page.jay-html -->
+<html>
+  <head>
+    <script type="application/jay-params">
+      slug: ceramic-flower-vase
+    </script>
+    <script
+      type="application/jay-headless"
+      plugin="wix-stores"
+      contract="product-page"
+      key="product"
+    ></script>
+  </head>
+  <body>
+    <h1>{product.productName}</h1>
+  </body>
+</html>
+```
+The script body is YAML. The declared params are passed to the component as if extracted from a dynamic URL segment. Without this, the component would receive no param values.
+## Page Files
+Each page directory can contain:
+| File                | Purpose                             |
+| ------------------- | ----------------------------------- |
+| `page.jay-html`     | Template (required for rendering)   |
+| `page.jay-contract` | Page-level data contract (optional) |
+### page.jay-contract
+Defines the page's own ViewState — data that the page's server-side code provides:
+```yaml
+name: Page
+tags:
+  - tag: title
+    type: data
+    dataType: string
+    phase: slow
+  - tag: items
+    type: sub-contract
+    repeated: true
+    trackBy: id
+    tags:
+      - tag: id
+        type: data
+        dataType: string
+      - tag: name
+        type: data
+        dataType: string
+```
+## Dynamic Routes and Contract Params
+When a component on the page — whether the page contract, a headless component, or a headfull full-stack component — declares `params`, the page should be placed in a dynamic route directory that provides those params.
+For example, if a headless component's contract declares:
+```yaml
+name: product-page
+params:
+  slug: string
+tags:
+  - ...
+```
+Then the page using this component should live at a route that provides a `slug` param:
+```
+src/pages/products/[slug]/page.jay-html
+```
+Multiple components on the same page can each declare params. The route directory must provide all required params across all components. For example, if the page contract requires `lang` and a headless component requires `slug`, the page should live at `src/pages/[lang]/products/[slug]/page.jay-html`.
+### Discovering Param Values
+For SSG with dynamic routes, the plugin component provides a `loadParams` generator that yields all valid param combinations. Use it to discover what routes will be generated:
+```bash
+jay-stack params wix-stores/product-page
+# Output: [{"slug": "blue-shirt"}, {"slug": "red-hat"}, ...]
+```
+Params are always strings (URL params).
+## Query Parameters
+URL query parameters (`?page=2&sort=price`) are available in the **fast render phase only** via `props.query`:
+```typescript
+.withFastRender(async (props, carryForward, dbService) => {
+    const page = parseInt(props.query.page || '1');
+    const sort = props.query.sort || 'name';
+    const products = await dbService.getProducts({ page, sort });
+    return phaseOutput({ products, currentPage: page }, {});
+})
+```
+- `props.query` is `Record<string, string>` — empty `{}` when no query string
+- Not available in the slow phase (compile error) — slow results are cached by path params only
+- In the interactive phase, use `new URLSearchParams(window.location.search)` directly

package/agent-kit-template/developer/seo-guide.md ADDED Viewed

@@ -0,0 +1,93 @@
+# SEO Head Tags
+Components inject `<title>`, `<meta>`, `<link>` tags into the HTML `<head>` during SSR by returning `headTags` from `phaseOutput()`.
+## Basic Usage
+```typescript
+return phaseOutput(
+  { title: product.name, price: product.price },
+  { productId: product.id },
+  {
+    headTags: [
+      { tag: 'title', children: `${product.name} | My Store` },
+      { tag: 'meta', attrs: { name: 'description', content: product.description } },
+      { tag: 'meta', attrs: { property: 'og:title', content: product.name } },
+      { tag: 'meta', attrs: { property: 'og:description', content: product.description } },
+      { tag: 'meta', attrs: { property: 'og:image', content: product.imageUrl } },
+      { tag: 'link', attrs: { rel: 'canonical', href: canonicalUrl } },
+    ],
+  },
+);
+```
+## HeadTag Type
+```typescript
+interface HeadTag {
+  tag: string; // 'title', 'meta', 'link', etc.
+  attrs?: Record<string, string>; // HTML attributes
+  children?: string; // Text content (for <title>, <script>, etc.)
+}
+```
+## Common SEO Tags
+```typescript
+// Page title
+{ tag: 'title', children: 'Product Name | Store' }
+// Meta description
+{ tag: 'meta', attrs: { name: 'description', content: 'Product description here' } }
+// Open Graph
+{ tag: 'meta', attrs: { property: 'og:title', content: 'Product Name' } }
+{ tag: 'meta', attrs: { property: 'og:description', content: 'Description' } }
+{ tag: 'meta', attrs: { property: 'og:image', content: 'https://...' } }
+{ tag: 'meta', attrs: { property: 'og:type', content: 'product' } }
+// Twitter Card
+{ tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } }
+{ tag: 'meta', attrs: { name: 'twitter:title', content: 'Product Name' } }
+// Canonical URL
+{ tag: 'link', attrs: { rel: 'canonical', href: 'https://example.com/products/slug' } }
+// JSON-LD structured data
+{ tag: 'script', attrs: { type: 'application/ld+json' }, children: JSON.stringify(structuredData) }
+```
+## Mapping Generic SEO Data
+If the data source provides a generic structure (array of tags with type/props/children), map it:
+```typescript
+const headTags = seoData.tags.map((tag) => ({
+  tag: tag.type,
+  attrs: Object.fromEntries(tag.props.map((p) => [p.key, p.value])),
+  children: tag.children,
+}));
+return phaseOutput(viewState, carryForward, { headTags });
+```
+## Phase Rules
+- Return headTags from **slow** phase for build-time SEO data (product name, description)
+- Return headTags from **fast** phase for per-request data (pricing, availability)
+- Fast phase headTags **replace** slow phase entirely (no merge)
+- No interactive phase — head tags are SSR-only
+## Collision Rules
+- `<title>` — singleton, last-write-wins
+- `<meta name="X">` — keyed by `name`, last-write-wins
+- `<meta property="X">` — keyed by `property`, last-write-wins
+- `<link rel="canonical">` — singleton, last-write-wins
+- Other tags — always included (no dedup)
+- A warning is logged on collision between different components
+## Restrictions
+- Head tags from components inside `forEach` are ignored
+- The framework handles HTML escaping automatically

package/agent-kit-template/plugin/INSTRUCTIONS.md ADDED Viewed

@@ -0,0 +1,40 @@
+# Jay Plugin Development — Agent Kit
+This folder contains guides for creating jay-stack plugins: contracts, headless components, server actions, and services.
+## What is a Jay Plugin?
+A plugin provides headless components (data + interactions, no UI) that project designers use via contracts. Plugins can be standalone npm packages or inline within a project (see `examples/jay-stack/fake-shop`).
+## Workflow
+1. **Define contracts first** — the contract is the source of truth
+2. **Implement components** matching the contracts
+3. **Define actions** with `.jay-action` metadata
+4. **Set up `plugin.yaml`**
+5. **Validate** with `jay-stack validate-plugin`
+## Guides
+| File                                             | Topic                                                                   |
+| ------------------------------------------------ | ----------------------------------------------------------------------- |
+| [contracts-guide.md](contracts-guide.md)         | Contract format: tags, types, phases, props, params, sub-contracts      |
+| [plugin-structure.md](plugin-structure.md)       | plugin.yaml, package layout, exports                                    |
+| [component-structure.md](component-structure.md) | makeJayStackComponent, builder API, three-phase rendering               |
+| [component-state.md](component-state.md)         | createSignal, createMemo, createEffect, createDerivedArray, createEvent |
+| [component-refs.md](component-refs.md)           | Refs, collection refs, element types                                    |
+| [component-data.md](component-data.md)           | Immutable data, JSON Patch, createPatchableSignal                       |
+| [component-context.md](component-context.md)     | Context hooks: provide, reactive, global                                |
+| [render-results.md](render-results.md)           | phaseOutput, RenderPipeline, errors, redirects                          |
+| [actions-guide.md](actions-guide.md)             | makeJayAction, makeJayQuery, .jay-action files                          |
+| [services-guide.md](services-guide.md)           | createJayService, makeJayInit                                           |
+| [seo-guide.md](seo-guide.md)                     | SEO head tags: title, meta, OG, canonical via phaseOutput               |
+| [validation.md](validation.md)                   | jay-stack validate-plugin usage                                         |
+| `../references/<plugin>/`                        | Plugin reference data                                                   |
+## Key Principles
+- **Contract is the source of truth** — define it before implementing the component
+- **Data is immutable** — never mutate ViewState directly, use JSON Patch
+- **Phase-aware** — choose the right rendering phase for each piece of data
+- **Props for configuration, params for URLs** — props are passed by parent components, params come from route segments

package/agent-kit-template/plugin/actions-guide.md ADDED Viewed

@@ -0,0 +1,125 @@
+# Server Actions
+Actions provide RPC-style server endpoints for client-to-server communication.
+## makeJayAction — Mutations (POST)
+```typescript
+import { makeJayAction } from '@jay-framework/fullstack-component';
+export const addToCart = makeJayAction('cart.addToCart')
+  .withServices(CART_SERVICE)
+  .withHandler(async (input: { productId: string; quantity: number }, cartService) => {
+    const cart = await cartService.addItem(input.productId, input.quantity);
+    return { cartItemCount: cart.items.length };
+  });
+```
+## makeJayQuery — Reads (GET)
+Queries use GET and support caching:
+```typescript
+import { makeJayQuery } from '@jay-framework/fullstack-component';
+export const searchProducts = makeJayQuery('products.search')
+  .withServices(PRODUCTS_SERVICE)
+  .withCaching({ maxAge: 60 })
+  .withHandler(async (input: { query: string; page?: number }, productsDb) => {
+    const results = await productsDb.search(input.query, input.page);
+    return { products: results.items, totalCount: results.total };
+  });
+```
+## Builder API
+```typescript
+makeJayAction('name')
+  .withServices(SERVICE1, SERVICE2) // Inject services
+  .withMethod('PUT') // Override HTTP method (default: POST for actions)
+  .withCaching({ maxAge: 60 }) // Enable caching (queries only)
+  .withHandler(async (input, svc1, svc2) => {
+    // Define handler
+    return result;
+  });
+```
+## ActionError
+Throw typed errors from action handlers:
+```typescript
+import { ActionError } from '@jay-framework/fullstack-component';
+throw new ActionError('OUT_OF_STOCK', 'Only 2 units available');
+throw new ActionError('INVALID_INPUT', 'Product ID is required');
+```
+## Calling Actions from Client
+Actions are callable functions on the client:
+```typescript
+.withInteractive(function MyComp(props, refs) {
+    refs.addToCart.onClick(async () => {
+        const result = await addToCart({
+            productId: props.productId,
+            quantity: 1,
+        });
+        // result.cartItemCount
+    });
+})
+```
+## Calling Actions from Server
+When called from server-side code (e.g., within a render phase), services are automatically injected — no network call is made.
+## .jay-action Metadata Files
+Each action should have a `.jay-action` file describing its input/output schemas for agent discovery:
+```yaml
+name: searchProducts
+description: Search products with text, filters, sorting, and pagination
+import:
+  productCard: product-card.jay-contract
+inputSchema:
+  query: string
+  filters?:
+    inStockOnly?: boolean
+    minPrice?: number
+    maxPrice?: number
+  sortBy?: enum(relevance | price_asc | price_desc)
+  pageSize?: number
+outputSchema:
+  products:
+    - productCard
+  totalCount: number
+  hasMore: boolean
+```
+### Jay-Type Notation for Schemas
+| Notation                  | Meaning                   |
+| ------------------------- | ------------------------- |
+| `prop: string`            | Required string           |
+| `prop?: number`           | Optional number           |
+| `prop: boolean`           | Required boolean          |
+| `prop: enum(a \| b \| c)` | Required enum             |
+| `prop:` + nested block    | Nested object             |
+| `prop:` + `- child: type` | Array of objects          |
+| `prop: record(T)`         | Record with typed values  |
+| `prop: importedName`      | Type from `import:` block |
+## Type Helpers
+```typescript
+import { ActionInput, ActionOutput, isJayAction } from '@jay-framework/fullstack-component';
+type SearchInput = ActionInput<typeof searchProducts>;
+type SearchOutput = ActionOutput<typeof searchProducts>;
+```

package/agent-kit-template/plugin/component-context.md ADDED Viewed

@@ -0,0 +1,103 @@
+# Component Context
+Context provides a way to share state between components without passing props through every level.
+## Context Markers
+Create a typed marker to identify a context:
+```typescript
+import { createContextMarker } from '@jay-framework/component';
+interface CartContext {
+  itemCount: () => number;
+  addItem: (productId: string) => void;
+}
+const CART_CONTEXT = createContextMarker<CartContext>('CartContext');
+```
+## provideContext
+Provide a non-reactive context value to child components:
+```typescript
+import { provideContext } from '@jay-framework/component';
+provideContext(CART_CONTEXT, {
+  itemCount: () => items().length,
+  addItem: (id) => addToCartAction({ productId: id }),
+});
+```
+## provideReactiveContext
+Provide a reactive context — the factory function has access to hooks:
+```typescript
+import { provideReactiveContext, createSignal } from '@jay-framework/component';
+const cartCtx = provideReactiveContext(CART_CONTEXT, () => {
+  const [items, setItems] = createSignal<CartItem[]>([]);
+  return {
+    itemCount: () => items().length,
+    addItem: (id) => setItems((prev) => [...prev, { productId: id }]),
+  };
+});
+```
+The returned value is the context instance, usable in the same component.
+## registerReactiveGlobalContext
+Register a context globally during client initialization (in `makeJayInit`):
+```typescript
+import { registerReactiveGlobalContext, createSignal } from '@jay-framework/component';
+export const init = makeJayInit().withClient(() => {
+  registerReactiveGlobalContext(CART_CONTEXT, () => {
+    const [items, setItems] = createSignal<CartItem[]>([]);
+    return {
+      itemCount: () => items().length,
+      addItem: (id) => setItems((prev) => [...prev, { productId: id }]),
+    };
+  });
+});
+```
+Global contexts are available to all components without explicit providing.
+## Consuming Context
+Components consume contexts via `.withContexts()` on the builder:
+```typescript
+makeJayStackComponent<MyContract>()
+  .withContexts(CART_CONTEXT)
+  .withInteractive(function MyComp(props, refs, cartCtx) {
+    refs.addToCart.onClick(() => {
+      cartCtx.addItem(props.productId);
+    });
+    return {
+      render: () => ({
+        cartCount: cartCtx.itemCount(),
+      }),
+    };
+  });
+```
+## Listing in plugin.yaml
+If your plugin provides contexts for other plugins to consume, list them in `plugin.yaml`:
+```yaml
+contexts:
+  - name: cart
+    marker: CART_CONTEXT
+    description: Client-side cart state (item count, add/remove items, totals)
+    doc: ./docs/cart-context.md # optional — markdown documentation
+```
+This makes the context discoverable in `plugins-index.yaml`. If `doc` is provided, the file must exist and be exported from the package.

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

@@ -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.