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

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

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 (39) hide show

package/agent-kit-template/{INSTRUCTIONS.md → designer/INSTRUCTIONS.md} RENAMED Viewed

@@ -37,14 +37,17 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 ## Reference Docs
-| File                                                 | Topic                                                                                           |
-| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| [project-structure.md](project-structure.md)         | Project layout, styling patterns (CSS themes, design tokens), configuration files               |
-| [jay-html-syntax.md](jay-html-syntax.md)             | Jay-HTML template syntax: data binding, conditions, loops, headless components                  |
-| [routing.md](routing.md)                             | Directory-based routing: page structure, dynamic routes, route priority                         |
-| [contracts-and-plugins.md](contracts-and-plugins.md) | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes                 |
-| [cli-commands.md](cli-commands.md)                   | CLI commands: setup, validate, params, action, dev server                                       |
-| `references/<plugin>/`                               | Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`) |
+| File                                                       | Topic                                                                                           |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| [project-structure.md](project-structure.md)               | Project layout, styling patterns (CSS themes, design tokens), configuration files               |
+| [jay-html-syntax.md](jay-html-syntax.md)                   | Jay-HTML overview: philosophy, component types, nesting rules, links to sub-files               |
+| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: data binding, conditions (boolean, enum, numeric, &&/\|\|), loops, refs        |
+| [jay-html-components.md](jay-html-components.md)           | Component imports: headless (key/instance), headfull FS, nesting patterns                       |
+| [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic style bindings, class bindings                               |
+| [routing.md](routing.md)                                   | Directory-based routing: page structure, dynamic routes, route priority                         |
+| [contracts-and-plugins.md](contracts-and-plugins.md)       | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes                 |
+| [cli-commands.md](cli-commands.md)                         | CLI commands: setup, validate, params, action, dev server                                       |
+| `../references/<plugin>/`                                  | Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`) |
 ## Quick Start

package/agent-kit-template/{jay-html-syntax.md → designer/jay-html-components.md} RENAMED Viewed

@@ -1,137 +1,9 @@
-# Jay-HTML Syntax Reference
-## File Structure
-A `.jay-html` file is standard HTML with jay-specific extensions.
-```html
-<html>
-  <head>
-    <!-- Page contract (optional — defines page-level data) -->
-    <script type="application/jay-data" contract="./page.jay-contract"></script>
-    <!-- Explicit route params (for static override routes) -->
-    <script type="application/jay-params">
-      slug: ceramic-flower-vase
-    </script>
-    <!-- Headless component imports -->
-    <script type="application/jay-headless" plugin="..." contract="..." key="..."></script>
-    <!-- Headfull component imports -->
-    <script type="application/jay-headfull" src="..." names="..." contract="..."></script>
-    <!-- Styles -->
-    <style>
-      /* inline CSS */
-    </style>
-    <link rel="stylesheet" href="../../styles/theme.css" />
-  </head>
-  <body>
-    <!-- Template with data bindings -->
-    <h1>{title}</h1>
-  </body>
-</html>
-```
-## Data Binding
-Use `{expression}` to bind contract data:
-```html
-<h1>{productName}</h1>
-<!-- simple -->
-<span>{product.price}</span>
-<!-- nested via key -->
-<div style="color: {textColor}">{msg}</div>
-<!-- in attributes -->
-<a href="/products/{slug}">{name}</a>
-<!-- interpolated in attr values -->
-```
-## Conditional Rendering
-Use the `if` attribute:
-```html
-<span if="inStock">In Stock</span>
-<span if="!inStock">Out of Stock</span>
-<div if="type===physical">Ships to your door</div>
-<div if="type===virtual">Instant download</div>
-```
-Rules:
-- Boolean: `if="tagName"` / `if="!tagName"`
-- Enum variant: `if="tagName===value"` / `if="tagName!==value"` (no quotes around value)
-- Negation: `!` prefix
-## Loops (forEach / trackBy)
-Iterate over repeated sub-contracts:
-```html
-<li forEach="products" trackBy="id">
-  <a href="/products/{slug}">
-    <div>{name}</div>
-    <div>{price}</div>
-  </a>
-</li>
-```
-- `forEach` — the repeated tag name from the contract
-- `trackBy` — stable unique key for each item (must match contract's trackBy)
-- Inside the loop, bindings resolve to the **current item's** tags
-**Nested loops:**
-```html
-<div forEach="options" trackBy="_id">
-  <h3>{name}</h3>
-  <div forEach="choices" trackBy="choiceId">
-    <button ref="choiceButton">{name}</button>
-  </div>
-</div>
-```
-## Refs (Interactions)
-Map elements to contract `interactive` tags using `ref`:
-```html
-<button ref="addToCart">Add to Cart</button>
-<input value="{quantity}" ref="quantityInput" />
-<a ref="productLink" href="/products/{slug}">{name}</a>
-<select ref="sizeSelector">
-  ...
-</select>
-```
-Match the element type to the contract's `elementType`:
-- `HTMLButtonElement` → `<button>`
-- `HTMLInputElement` → `<input>`
-- `HTMLAnchorElement` → `<a>`
-- `HTMLSelectElement` → `<select>`
-**Key-based headless refs** — prefix with the key:
-```html
-<button ref="rating.submitButton">Submit</button> <button ref="mt.happy">+1 Happy</button>
-```
-**Refs inside forEach** — use the tag path from the contract:
-```html
-<div forEach="options" trackBy="_id">
-  <div forEach="choices" trackBy="choiceId">
-    <button ref="choiceButton">{name}</button>
-  </div>
-</div>
-```
+# Jay-HTML Component Imports
 ## Headless Components
+Headless components provide data and interactions with no UI. The page or headfull component provides the template.
 ### Pattern 1: Key-Based Import
 Data merged into parent ViewState under a key. Use when you have **one instance** of a component per page.
@@ -165,6 +37,8 @@ Access data and refs with the key prefix:
 </div>
 ```
+Key-based imports are only available in **pages** (not in headfull FS components).
 ### Pattern 2: Instance-Based (jay: prefix)
 Multiple instances with props and inline templates. Use when you need **multiple instances** or need to pass **props**.
@@ -213,7 +87,9 @@ Inside `<jay:...>`, bindings resolve to **that instance's** contract tags (not t
 ## Headfull Full-Stack Components
-Headfull components that own their UI can be made full-stack by adding a `contract` attribute:
+Headfull components own their UI and can be made full-stack by adding a `contract` attribute.
+### Import Declaration
 ```html
 <head>
@@ -232,7 +108,9 @@ Headfull components that own their UI can be made full-stack by adding a `contra
 - `names` — Component name to import
 - `contract` — Path to the contract file (makes the component full-stack with SSR)
-**Usage** — same as client-only headfull, with props:
+### Usage
+Same as client-only headfull, with props:
 ```html
 <jay:SharedHeader logoUrl="/logo.png" />
@@ -240,50 +118,96 @@ Headfull components that own their UI can be made full-stack by adding a `contra
 Without `contract`, the component is client-only. With `contract`, it participates in slow/fast/interactive phases and is server-side rendered. Use headfull full-stack components for reusable UI with fixed layout that needs SSR (headers, footers, sidebars).
-## Page-Level Contract
+### Headfull FS Component Structure
-A page can define its own data contract:
+A headfull FS component has its own `.jay-html` file with the same structure as a page:
 ```html
-<script type="application/jay-data" contract="./page.jay-contract"></script>
+<!-- components/header/header.jay-html -->
+<html>
+  <head>
+    <script type="application/jay-data">
+      data:
+          logoUrl: string
+    </script>
+  </head>
+  <body>
+    <header>
+      <img src="{logoUrl}" />
+      <nav>Navigation here</nav>
+    </header>
+  </body>
+</html>
 ```
-Tags from the page contract are bound directly (no key prefix).
+## Nesting Components
-## Styling
+### Headfull Inside Headfull
-**Inline `<style>`:**
+A layout component imports a header component:
 ```html
-<head>
-  <style>
-    .product-card {
-      border: 1px solid #ccc;
-      padding: 16px;
-    }
-    .price {
-      font-weight: bold;
-      color: #2d7d2d;
-    }
-  </style>
-</head>
+<!-- layout/layout.jay-html -->
+<html>
+  <head>
+    <script
+      type="application/jay-headfull"
+      src="../header/header"
+      contract="../header/header.jay-contract"
+      names="header"
+    ></script>
+    <script type="application/jay-data">
+      data:
+          sidebarLabel: string
+    </script>
+  </head>
+  <body>
+    <div class="layout">
+      <jay:header logoUrl="/logo.png" />
+      <aside>{sidebarLabel}</aside>
+    </div>
+  </body>
+</html>
 ```
-**External stylesheets:**
+### Headless Inside Headfull
+A header component uses a headless plugin widget:
 ```html
-<link rel="stylesheet" href="../../styles/theme.css" />
+<!-- header/header.jay-html -->
+<html>
+  <head>
+    <script type="application/jay-headless" plugin="my-plugin" contract="cart-indicator"></script>
+    <script type="application/jay-data">
+      data:
+          logoUrl: string
+    </script>
+  </head>
+  <body>
+    <header>
+      <img src="{logoUrl}" />
+      <jay:cart-indicator>
+        <span class="count">{itemCount}</span>
+      </jay:cart-indicator>
+    </header>
+  </body>
+</html>
 ```
-**Dynamic style bindings:**
+Nesting depth is unlimited. Circular imports are detected as errors. Key-based headless imports (`key="..."`) are not allowed inside headfull FS components — use instance-based imports instead.
-```html
-<div style="color: {textColor}; width: {width}px">styled</div>
-```
+## Nesting Rules
+| Parent component | Can import headfull FS? | Can import headless (instance)? | Can import keyed headless? |
+| ---------------- | ----------------------- | ------------------------------- | -------------------------- |
+| **Page**         | Yes                     | Yes                             | Yes                        |
+| **Headfull FS**  | Yes (recursive)         | Yes (in its own head)           | No                         |
+| **Headless**     | No (no template)        | No (no template)                | No (no template)           |
 ## Complete Example
-A homepage with key-based and instance-based headless components:
+A homepage with key-based, instance-based, and headfull components:
 ```html
 <html>
@@ -299,6 +223,12 @@ A homepage with key-based and instance-based headless components:
       plugin="product-widget"
       contract="product-widget"
     ></script>
+    <script
+      type="application/jay-headfull"
+      src="../components/shared-header"
+      names="SharedHeader"
+      contract="../components/shared-header/shared-header.jay-contract"
+    ></script>
     <script type="application/jay-data" contract="./page.jay-contract"></script>
     <style>
       .section {
@@ -313,6 +243,7 @@ A homepage with key-based and instance-based headless components:
     </style>
   </head>
   <body>
+    <jay:SharedHeader logoUrl="/logo.png" />
     <h1>Homepage</h1>
     <!-- Key-based: mood tracker -->

package/agent-kit-template/designer/jay-html-styling.md ADDED Viewed

@@ -0,0 +1,97 @@
+# Jay-HTML Styling
+## Inline Styles
+Add `<style>` blocks in `<head>`:
+```html
+<head>
+  <style>
+    .product-card {
+      border: 1px solid #ccc;
+      padding: 16px;
+    }
+    .price {
+      font-weight: bold;
+      color: #2d7d2d;
+    }
+  </style>
+</head>
+```
+## External Stylesheets
+Link external CSS files:
+```html
+<link rel="stylesheet" href="../../styles/theme.css" />
+```
+## Dynamic Style Bindings
+Use `{expression}` inside `style` attribute values:
+```html
+<div style="color: {textColor}; width: {width}px">styled</div>
+<div style="margin: 10px; color: {color}; padding: 20px">mixed static and dynamic</div>
+<div style="background-color: {bgColor}; font-size: {fontSize}px">with units</div>
+```
+## Class Binding
+### Static Classes
+```html
+<div class="button primary">Click me</div>
+```
+### Dynamic Class Value
+Bind a contract value as a class name:
+```html
+<div class="button {variant}">Click me</div>
+```
+### Conditional Class
+Add a class only when a condition is true:
+```html
+<div class="{isActive ? active}">Tab</div>
+<div class="{hasItems ? has-items}">Cart</div>
+```
+### Ternary Class
+Switch between two classes based on a condition:
+```html
+<div class="{isPrimary ? primary : secondary}">Button</div>
+<div class="{isExpanded ? expanded : collapsed}">Panel</div>
+```
+### Combined Classes
+Mix static, dynamic, and conditional classes:
+```html
+<div class="button {isPrimary ? primary : secondary}">Click me</div>
+<a class="cart-indicator {hasItems ? has-items} {isLoading ? is-loading}">Cart</a>
+<div class="first-class {bool1 ? main : second} {!bool1 ? third : forth}">mixed</div>
+```
+### With Enum Conditions
+```html
+<div class="{status === active ? highlighted}">Item</div>
+```
+### Class Binding Rules
+- Static classes are always present: `class="button"`
+- `{value}` inserts the contract value as a class name
+- `{condition ? class}` adds `class` when condition is truthy
+- `{condition ? classA : classB}` switches between two classes
+- `{!condition ? class}` uses negation
+- Multiple bindings can be combined in one `class` attribute

package/agent-kit-template/designer/jay-html-syntax.md ADDED Viewed

@@ -0,0 +1,44 @@
+# Jay-HTML — AI Designer Instructions
+## Philosophy
+Jay-HTML is standard HTML with data bindings. There is no custom component framework — just native HTML + CSS with `{expression}` bindings for dynamic content.
+The design tool can freely read and rewrite jay-html files as long as contract bindings stay intact. Bindings (`{expression}`, `if`, `forEach`, `ref`) are the only extension to HTML. Everything else — CSS, structure, semantics, accessibility — is native.
+## Component Types
+### Page
+Entry point at `src/pages/`. Can import all component types.
+### Headfull FS
+Reusable component with its own template + contract + three-phase rendering (slow/fast/interactive). Lives alongside the page in a components directory. Can nest other headfull FS and instance headless in its own `<head>`. Cannot use keyed headless.
+### Headless
+Plugin-provided logic component. No template — the page or headfull component provides the UI via inline template (`<jay:xxx>`). Two import patterns:
+- **Key-based** — one instance per page, data merged under a key prefix (`{key.tag}`)
+- **Instance-based** — multiple instances with props, each gets its own inline template
+## Nesting Rules
+| Parent component | Can import headfull FS? | Can import headless (instance)? | Can import keyed headless? |
+| ---------------- | ----------------------- | ------------------------------- | -------------------------- |
+| **Page**         | Yes                     | Yes                             | Yes                        |
+| **Headfull FS**  | Yes (recursive)         | Yes (in its own head)           | No                         |
+| **Headless**     | No (no template)        | No (no template)                | No (no template)           |
+## Validation
+After creating or editing jay-html files, run `jay-stack validate` to check for errors. It catches issues like unknown refs, missing contracts, and invalid bindings. See [cli-commands.md](cli-commands.md) for details.
+## Reference
+| File                                                       | Topic                                                                  |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: file structure, data binding, conditions, loops, refs |
+| [jay-html-components.md](jay-html-components.md)           | Component imports: headless (key/instance), headfull FS, nesting       |
+| [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic styles, class bindings              |

package/agent-kit-template/designer/jay-html-template-syntax.md ADDED Viewed

@@ -0,0 +1,203 @@
+# Jay-HTML Template Syntax
+## File Structure
+A `.jay-html` file is standard HTML with jay-specific extensions.
+```html
+<html>
+  <head>
+    <!-- Page contract (optional — defines page-level data) -->
+    <script type="application/jay-data" contract="./page.jay-contract"></script>
+    <!-- Explicit route params (for static override routes) -->
+    <script type="application/jay-params">
+      slug: ceramic-flower-vase
+    </script>
+    <!-- Headless component imports -->
+    <script type="application/jay-headless" plugin="..." contract="..." key="..."></script>
+    <!-- Headfull component imports -->
+    <script type="application/jay-headfull" src="..." names="..." contract="..."></script>
+    <!-- Styles -->
+    <style>
+      /* inline CSS */
+    </style>
+    <link rel="stylesheet" href="../../styles/theme.css" />
+  </head>
+  <body>
+    <!-- Template with data bindings -->
+    <h1>{title}</h1>
+  </body>
+</html>
+```
+## Data Binding
+Use `{expression}` to bind contract data:
+```html
+<h1>{productName}</h1>
+<!-- simple -->
+<span>{product.price}</span>
+<!-- nested via key -->
+<div style="color: {textColor}">{msg}</div>
+<!-- in attributes -->
+<a href="/products/{slug}">{name}</a>
+<!-- interpolated in attr values -->
+```
+## Boolean Attributes
+HTML boolean attributes (`disabled`, `checked`, `hidden`, `readonly`) can be bound to contract data:
+```html
+<button disabled="isSubmitting">Submit</button>
+<!-- disabled when isSubmitting is true -->
+<button disabled="!inStock">Add to Cart</button>
+<!-- disabled when inStock is false -->
+<input type="checkbox" checked="isSelected" />
+<!-- checked when isSelected is true -->
+<div hidden="!isVisible">Content</div>
+<!-- hidden when isVisible is false -->
+```
+- Set the attribute value to a **boolean tag name** — the attribute is present when true, absent when false
+- Use `!` prefix to negate: `disabled="!enabled"` means disabled when enabled is false
+- Without a value (`disabled` alone), the attribute is always present (standard HTML behavior)
+## Conditional Rendering
+Use the `if` attribute to conditionally show elements.
+### Boolean
+```html
+<span if="inStock">In Stock</span> <span if="!inStock">Out of Stock</span>
+```
+### Enum Variant
+No quotes around the value:
+```html
+<div if="type===physical">Ships to your door</div>
+<div if="type!==physical">Not a physical product</div>
+<div if="status===active">Active</div>
+```
+### Numeric Comparisons
+Compare against numbers or other fields:
+```html
+<span if="count > 0">You have {count} items</span>
+<span if="count <= 0">No items</span>
+<button if="currentPage <= 1" disabled>Previous</button>
+<span if="price <= budget">Affordable</span>
+<span if="available >= required">In stock</span>
+```
+Operators: `>`, `<`, `>=`, `<=`, `==`, `!=`
+### Logical AND / OR
+Combine conditions with `&&` and `||`:
+```html
+<div if="inStock && hasDiscount">Great deal!</div>
+<span if="isPromoted || hasDiscount">Has offer</span>
+```
+Use parentheses for complex expressions:
+```html
+<div if="(inStock && hasDiscount) || isPromoted">Buyable</div>
+<div if="inStock && price > 0">Purchasable</div>
+<button if="count <= 0 || isLoading" disabled>Checkout</button>
+```
+### Rules Summary
+- Boolean: `if="flag"` / `if="!flag"`
+- Enum: `if="tag===value"` / `if="tag!==value"` (no quotes around value)
+- Numeric: `if="count > 0"`, `if="price <= budget"`
+- Field comparison: `if="available >= required"`
+- Logical: `if="a && b"`, `if="a || b"`, `if="(a || b) && c"`
+- Negation: `!` prefix on booleans
+## Loops (forEach / trackBy)
+Iterate over repeated sub-contracts:
+```html
+<li forEach="products" trackBy="id">
+  <a href="/products/{slug}">
+    <div>{name}</div>
+    <div>{price}</div>
+  </a>
+</li>
+```
+- `forEach` — the repeated tag name from the contract
+- `trackBy` — stable unique key for each item (must match contract's trackBy)
+- Inside the loop, bindings resolve to the **current item's** tags
+**Nested loops:**
+```html
+<div forEach="options" trackBy="_id">
+  <h3>{name}</h3>
+  <div forEach="choices" trackBy="choiceId">
+    <button ref="choiceButton">{name}</button>
+  </div>
+</div>
+```
+## Refs (Interactions)
+Map elements to contract `interactive` tags using `ref`:
+```html
+<button ref="addToCart">Add to Cart</button>
+<input value="{quantity}" ref="quantityInput" />
+<a ref="productLink" href="/products/{slug}">{name}</a>
+<select ref="sizeSelector">
+  ...
+</select>
+```
+Match the element type to the contract's `elementType`:
+- `HTMLButtonElement` → `<button>`
+- `HTMLInputElement` → `<input>`
+- `HTMLAnchorElement` → `<a>`
+- `HTMLSelectElement` → `<select>`
+**Key-based headless refs** — prefix with the key:
+```html
+<button ref="rating.submitButton">Submit</button> <button ref="mt.happy">+1 Happy</button>
+```
+**Refs inside forEach** — use the tag path from the contract:
+```html
+<div forEach="options" trackBy="_id">
+  <div forEach="choices" trackBy="choiceId">
+    <button ref="choiceButton">{name}</button>
+  </div>
+</div>
+```
+## Page-Level Contract
+A page can define its own data contract:
+```html
+<script type="application/jay-data" contract="./page.jay-contract"></script>
+```
+Tags from the page contract are bound directly (no key prefix).