@jay-framework/compiler-jay-html 0.6.10 → 0.8.0

package/docs/jay-html-docs.md

@@ -176,3 +176,139 @@ Since Jay uses immutable view state, the `trackBy` attribute is essential for pr
 ```
 
 In this example, each `ProductCard` component receives the entire product object as its context.
+
+## Recursive Rendering
+
+Jay-HTML supports recursive component structures where elements can reference themselves, enabling the rendering of tree-like and nested data structures.
+
+### Defining Recursive Types
+
+Recursive types are defined in the data contract using the `$/data` or `$/data/path` syntax:
+
+```yaml
+data:
+  title: string
+  tree:
+    id: string
+    name: string
+    children: $/data/tree
+```
+
+The `$/data/tree` reference creates a recursive type where `children` has the same type as `tree` itself.
+
+### Nested Recursive References
+
+You can reference nested types deeper in the data structure:
+
+```yaml
+data:
+  root:
+    value: number
+    nested:
+      id: string
+      children: $/data/root/nested
+```
+
+This creates a recursive type at `root.nested` where `children` has the same type as the parent `nested` object.
+
+### Creating Recursive Regions
+
+Use the `ref` attribute to mark an element as a recursive region, then use `<recurse>` to trigger recursion:
+
+```html
+<div class="tree-node" ref="treeNode">
+  <div class="node-name">{name}</div>
+  <div if="children">
+    <recurse ref="treeNode" accessor="children" />
+  </div>
+</div>
+```
+
+The compiler generates a recursive function for the referenced element, and `<recurse>` calls that function with the specified data.
+
+### Context Switching with `<with-data>`
+
+When your recursive data is nested within a parent structure, use `<with-data>` to switch the view state context:
+
+```yaml
+data:
+  title: string
+  description: string
+  btree:
+    value: number
+    left: $/data/btree
+    right: $/data/btree
+```
+
+```html
+<div class="tree-container">
+  <h1>{title}</h1>
+  <p>{description}</p>
+  <with-data accessor="btree">
+    <div class="tree-node" ref="treeNode">
+      <div>{value}</div>
+      <div if="left">
+        <recurse ref="treeNode" accessor="left" />
+      </div>
+      <div if="right">
+        <recurse ref="treeNode" accessor="right" />
+      </div>
+    </div>
+  </with-data>
+</div>
+```
+
+The `<with-data>` element:
+
+- Accepts an `accessor` attribute specifying a property path
+- Changes the view state context for its children
+- Must have exactly one child element
+- Works with both object and array types
+
+This allows the recursive region to operate on a consistent type (`btree`) whether it's at the root level or in a recursive call.
+
+### Identity Accessor with `forEach`
+
+Within a `<with-data>` context, you can use `forEach="."` to iterate over the current context:
+
+```html
+<with-data accessor="tree">
+  <ul ref="menuItem">
+    <li forEach="." trackBy="id">
+      <span>{name}</span>
+      <div if="children">
+        <recurse ref="menuItem" accessor="children" />
+      </div>
+    </li>
+  </ul>
+</with-data>
+```
+
+The `forEach="."` syntax means "iterate over the current context", which is useful when `<with-data>` has already narrowed the context to an array.
+
+### Recursion Guards
+
+Recursion requires proper guards to prevent infinite loops:
+
+- **Recursion with accessor** (e.g., `<recurse accessor="children"/>`) uses `withData` which includes a built-in null check
+- **Recursion without accessor** (e.g., `<recurse/>` in a forEach loop) must be inside a `forEach` or conditional to prevent infinite recursion
+
+Example with forEach (no accessor needed):
+
+```html
+<ul ref="list">
+  <li forEach="items" trackBy="id">
+    {text}
+    <recurse ref="list" />
+  </li>
+</ul>
+```
+
+Example with accessor (built-in guard):
+
+```html
+<div ref="node">
+  {value}
+  <recurse ref="node" accessor="child" />
+</div>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/compiler-jay-html",
-  "version": "0.6.10",
+  "version": "0.8.0",
   "description": "",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -34,11 +34,11 @@
   },
   "author": "",
   "dependencies": {
-    "@jay-framework/compiler-analyze-exported-types": "^0.6.10",
-    "@jay-framework/compiler-shared": "^0.6.10",
-    "@jay-framework/component": "^0.6.10",
-    "@jay-framework/runtime": "^0.6.10",
-    "@jay-framework/secure": "^0.6.10",
+    "@jay-framework/compiler-analyze-exported-types": "^0.8.0",
+    "@jay-framework/compiler-shared": "^0.8.0",
+    "@jay-framework/component": "^0.8.0",
+    "@jay-framework/runtime": "^0.8.0",
+    "@jay-framework/secure": "^0.8.0",
     "@types/js-yaml": "^4.0.9",
     "change-case": "^4.1.2",
     "js-yaml": "^4.1.0",
@@ -50,8 +50,8 @@
   },
   "devDependencies": {
     "@caiogondim/strip-margin": "^1.0.0",
-    "@jay-framework/4-react": "^0.6.10",
-    "@jay-framework/dev-environment": "^0.6.10",
+    "@jay-framework/4-react": "^0.8.0",
+    "@jay-framework/dev-environment": "^0.8.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",

package/readme.md

@@ -26,7 +26,7 @@ Here's a simple Jay-HTML file:
 
 ## Key Differences from Standard HTML
 
-Jay-HTML extends HTML with seven main features:
+Jay-HTML extends HTML with eight main features:
 
 1. **Component and type imports** - Import reusable components and type definitions
 2. **Data contract definition** - Define component interfaces using YAML
@@ -35,6 +35,7 @@ Jay-HTML extends HTML with seven main features:
 5. **Data binding** - Bind component data to HTML using `{}` syntax
 6. **Conditional rendering** - Show/hide elements based on conditions
 7. **List rendering** - Iterate over arrays with `forEach` and `trackBy`
+8. **Async rendering** - Handle promises with loading, resolved, and error states
 
 ## Component Import System
 
@@ -104,6 +105,56 @@ Headless components provide only the contract and logic:
 ></script>
 ```
 
+## Async Rendering
+
+Jay-HTML provides built-in support for handling asynchronous data with dedicated conditional rendering attributes. Async data can be primitive types (like strings or numbers), objects, or arrays.
+
+### Async Data Declaration
+
+```html
+<script type="application/yaml-jay">
+  data:
+    title: string
+    async status: string              <!-- Primitive type -->
+    async userProfile:                <!-- Object type -->
+      name: string
+      email: string
+    async posts:                      <!-- Array type -->
+    - id: string
+      title: string
+</script>
+```
+
+### Async State Handling
+
+```html
+<body>
+  <h1>{title}</h1>
+
+  <!-- Loading state -->
+  <div when-loading="userProfile">Loading user profile...</div>
+
+  <!-- Success state -->
+  <div when-resolved="userProfile">
+    <h2>Welcome, {name}!</h2>
+    <p>{email}</p>
+  </div>
+
+  <!-- Error state -->
+  <div when-rejected="userProfile">
+    Failed to load profile: {message}
+    <!-- Error properties available: {name}, {message}, {stack} -->
+  </div>
+
+  <!-- Async arrays -->
+  <div when-resolved="posts">
+    <article forEach="." trackBy="id">
+      <h3>{title}</h3>
+    </article>
+  </div>
+</body>
+```
+
 ## Documentation
 
 ### Jay-HTML Syntax

package/test/fixtures/recursive-html/README.md

@@ -0,0 +1,142 @@
+# Recursive Jay-HTML Test Fixtures
+
+These fixtures test the new recursive jay-html feature as designed in Design Log 46.
+
+## Feature Overview
+
+The recursive jay-html feature allows marking HTML subtrees as recursive regions using:
+
+- `ref="regionName"` on an element to mark it as a recursive region
+- `<recurse ref="regionName" />` to trigger recursion at that point
+- `array<$/data>` type syntax to define recursive type references
+
+## Test Cases
+
+### 1. `simple-tree/`
+
+**Tests:** Basic direct recursion with a simple tree structure
+
+**Key Features:**
+
+- Direct recursion: `children: array<$/data>`
+- Recursive region marked with `ref="treeNode"`
+- Recursion triggered in `forEach` with `<recurse ref="treeNode" />`
+- Has a ref within the recursive region (`nodeHeader`)
+- Conditional rendering with `if="open"`
+
+### 2. `indirect-recursion/`
+
+**Tests:** Indirect recursion through a nested container object
+
+**Key Features:**
+
+- Indirect recursion: `submenu.items: array<$/data>`
+- The recursion doesn't happen directly on the root type
+- Demonstrates type generation for nested containers with recursive arrays
+- Combined conditional: `if="hasSubmenu && isOpen"`
+
+### 3. `tree-with-conditional/`
+
+**Tests:** Recursive structure with enum types and complex conditionals
+
+**Key Features:**
+
+- Enum type usage: `type: enum (file | folder)`
+- Conditional recursion based on enum: `if="type == folder && isExpanded"`
+- Demonstrates enum code generation in recursive contexts
+- Shows how enum comparisons work in recursive regions
+
+### 4. `nested-comments/`
+
+**Tests:** Classic nested comments/replies pattern
+
+**Key Features:**
+
+- Simple direct recursion for comment threads
+- Button ref within recursive region (`toggleReplies`)
+- Demonstrates real-world use case (threaded comments)
+- Clean parent-child relationship pattern
+
+### 5. `linked-list/`
+
+**Tests:** Recursive conditional without arrays (single optional child)
+
+**Key Features:**
+
+- Non-array recursion: `next: $/data` (not an array!)
+- Linked list pattern with optional next node
+- Recursion guard is conditional only (no forEach)
+- Type generation: `next: LinkedListViewState | null`
+- Demonstrates single-child recursive structures
+
+### 6. `binary-tree/`
+
+**Tests:** Multiple recursive conditionals (left/right children)
+
+**Key Features:**
+
+- Multiple non-array recursive references: `left: $/data`, `right: $/data`
+- Binary tree pattern with optional left and right children
+- Two separate conditional recursions in same region
+- Type generation: nullable optional children
+- Demonstrates branching recursive structures
+
+## Expected Generated Code Pattern
+
+Each test expects code generation following this pattern:
+
+```typescript
+// 1. Recursive ViewState type with self-reference
+export interface TreeViewState {
+  // ... properties
+  children: Array<TreeViewState>; // Self-referencing array
+}
+
+// 2. Internal recursive render function
+function renderRecursiveRegion_<refName>(data: TreeViewState) {
+  return e('div', {}, [
+    // ... element structure
+    forEach(
+      (vs) => vs.children,
+      (childData) => {
+        return e('li', {}, [
+          renderRecursiveRegion_<refName>(childData), // Recursive call
+        ]);
+      },
+      'trackByKey',
+    ),
+  ]);
+}
+
+// 3. Main render function that calls the recursive function
+const render = (viewState: TreeViewState) =>
+  ConstructContext.withRootContext(viewState, refManager, () =>
+    e('div', {}, [
+      // Non-recursive content
+      renderRecursiveRegion_<refName>(viewState), // Initial call
+    ]),
+  ) as TreeElement;
+```
+
+## Validation Rules Being Tested
+
+1. **Recursion Guards**: Each `<recurse>` must be inside a `forEach` or conditional
+   - forEach guard: Tests 1-4 (array-based recursion)
+   - Conditional guard: Tests 5-6 (non-array recursion)
+2. **Type Consistency**: The array/property type must match the recursive type reference
+   - Array recursion: `array<$/data>` → `Array<ViewState>`
+   - Single recursion: `$/data` → `ViewState | null`
+3. **Valid Region References**: `<recurse ref="name">` must reference an existing `ref="name"` element
+4. **Descendant Requirement**: `<recurse>` must be a descendant of the referenced region
+
+## Not Yet Tested
+
+These fixtures do **not** yet test:
+
+- Multiple recursive regions in one component
+- Referencing nested types (`array<$/data/metadata>`)
+- Error cases (missing guards, invalid references, etc.)
+- React target generation for recursive structures
+- Contract file recursion with `link: $/`
+
+Additional test fixtures should be added for these scenarios.