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

package/docs/contract-file-format.md

@@ -178,6 +178,220 @@ In this example:
 4. **Document dependencies** - Make it clear which contracts are required
 5. **Version contracts** - Consider versioning for breaking changes
 
+## Recursive Links
+
+Recursive links allow you to create self-referential data structures within a contract, such as trees, nested menus, or hierarchical data. They use the special `$/` syntax to reference parts of the same contract.
+
+### Basic Recursive Link
+
+```yaml
+name: folder-tree
+tags:
+  - tag: name
+    type: data
+    dataType: string
+  - tag: children
+    type: sub-contract
+    repeated: true
+    link: $/
+```
+
+The `link: $/` references the root of the current contract, creating a recursive structure.
+
+**Generated TypeScript:**
+
+```typescript
+export interface FolderTreeViewState {
+  name: string;
+  children: Array<FolderTreeViewState>;
+}
+```
+
+### Nested Path Recursive Links
+
+You can reference nested properties within the contract using path syntax:
+
+```yaml
+name: document
+tags:
+  - tag: title
+    type: data
+    dataType: string
+  - tag: metadata
+    type: sub-contract
+    tags:
+      - tag: category
+        type: data
+        dataType: string
+      - tag: tags
+        type: data
+        dataType: string
+  - tag: relatedDocuments
+    type: sub-contract
+    repeated: true
+    link: $/metadata
+```
+
+The `link: $/metadata` references the `metadata` sub-contract within the same contract.
+
+**Generated TypeScript:**
+
+```typescript
+export interface MetadataOfDocumentViewState {
+  category: string;
+  tags: string;
+}
+
+export interface DocumentViewState {
+  title: string;
+  metadata: MetadataOfDocumentViewState;
+  relatedDocuments: Array<MetadataOfDocumentViewState>;
+}
+```
+
+### Array Item Unwrapping with `[]`
+
+When a recursive link points to an array property, you can use the `[]` suffix to unwrap and link to the item type instead of the full array:
+
+```yaml
+name: product-list
+tags:
+  - tag: title
+    type: data
+    dataType: string
+  - tag: products
+    type: sub-contract
+    repeated: true
+    tags:
+      - tag: id
+        type: data
+        dataType: string
+      - tag: name
+        type: data
+        dataType: string
+      - tag: price
+        type: data
+        dataType: number
+  - tag: featuredProduct
+    type: sub-contract
+    link: $/products[]
+    description: Links to a single product item (not the array)
+```
+
+**Without `[]` - Links to the Array:**
+
+- `link: $/products` → `Array<ProductOfProductListViewState>`
+
+**With `[]` - Links to the Array Item:**
+
+- `link: $/products[]` → `ProductOfProductListViewState | null`
+
+**Generated TypeScript:**
+
+```typescript
+export interface ProductOfProductListViewState {
+  id: string;
+  name: string;
+  price: number;
+}
+
+export interface ProductListViewState {
+  title: string;
+  products: Array<ProductOfProductListViewState>;
+  featuredProduct: ProductOfProductListViewState | null;
+}
+```
+
+### Recursive Link Syntax Reference
+
+| Syntax              | Resolves To            | Generated Type              |
+| ------------------- | ---------------------- | --------------------------- |
+| `$/`                | Root contract          | `ContractViewState \| null` |
+| `$/propertyName`    | Nested property        | `PropertyType \| null`      |
+| `$/arrayProperty`   | Array property         | `Array<ItemType>`           |
+| `$/arrayProperty[]` | Array item type        | `ItemType \| null`          |
+| `$/nested/path`     | Deeply nested property | `PropertyType \| null`      |
+
+### Type Nullability Rules
+
+- **Non-array types** get `| null` since they may not exist
+- **Array types** don't get `| null` since an empty array (`[]`) can be used
+- **Repeated tags** with `repeated: true` always generate arrays
+
+### Common Use Cases
+
+**1. Tree Structures (Direct Recursion)**
+
+```yaml
+name: tree-node
+tags:
+  - tag: value
+    type: data
+    dataType: string
+  - tag: children
+    type: sub-contract
+    repeated: true
+    link: $/
+```
+
+**2. Linked Lists (Single Recursion)**
+
+```yaml
+name: linked-list
+tags:
+  - tag: value
+    type: data
+    dataType: string
+  - tag: next
+    type: sub-contract
+    link: $/
+```
+
+**3. Nested Menus (Indirect Recursion)**
+
+```yaml
+name: menu
+tags:
+  - tag: label
+    type: data
+    dataType: string
+  - tag: submenu
+    type: sub-contract
+    tags:
+      - tag: items
+        type: sub-contract
+        repeated: true
+        link: $/
+```
+
+**4. Featured Item from Array (Array Unwrapping)**
+
+```yaml
+name: catalog
+tags:
+  - tag: items
+    type: sub-contract
+    repeated: true
+    tags:
+      - tag: id
+        type: data
+        dataType: string
+      - tag: title
+        type: data
+        dataType: string
+  - tag: featured
+    type: sub-contract
+    link: $/items[]
+```
+
+### Best Practices for Recursive Links
+
+1. **Use descriptive paths** - Make it clear what you're referencing
+2. **Document recursion** - Add descriptions explaining the recursive relationship
+3. **Consider depth limits** - Be aware of potential deeply nested structures
+4. **Use `[]` for single items** - When referencing one item from an array, use `[]` unwrapping
+5. **Validate paths** - Ensure the referenced paths exist in your contract
+
 ## Data Types
 
 ### Basic Types

package/docs/jay-html-docs.md

@@ -211,6 +211,67 @@ data:
 
 This creates a recursive type at `root.nested` where `children` has the same type as the parent `nested` object.
 
+### Array Recursion vs. Array Item References
+
+When working with arrays, you can use two different syntaxes:
+
+**Array Recursion** - Use `array<$/data/path>` to create arrays of recursive items:
+
+```yaml
+data:
+  name: string
+  id: string
+  children: array<$/data>
+```
+
+This creates an array where each item has the same type as the root data structure.
+
+**Generated TypeScript:**
+
+```typescript
+export interface TreeViewState {
+  name: string;
+  id: string;
+  children: Array<TreeViewState>;
+}
+```
+
+**Array Item Unwrapping** - Use `$/data/path[]` to reference a single item from an array property:
+
+```yaml
+data:
+  products:
+    - id: string
+      name: string
+      price: number
+  featuredProduct: $/data/products[]
+```
+
+The `[]` suffix unwraps the array and links to the item type instead of the full array.
+
+**Generated TypeScript:**
+
+```typescript
+export interface ProductOfProductListViewState {
+  id: string;
+  name: string;
+  price: number;
+}
+
+export interface ProductListViewState {
+  products: Array<ProductOfProductListViewState>;
+  featuredProduct: ProductOfProductListViewState | null;
+}
+```
+
+**Comparison:**
+
+| Syntax               | Use Case                  | Generated Type     |
+| -------------------- | ------------------------- | ------------------ |
+| `array<$/data>`      | Multiple items (array)    | `Array<ItemType>`  |
+| `$/data/arrayProp`   | Reference to entire array | `Array<ItemType>`  |
+| `$/data/arrayProp[]` | Single item from array    | `ItemType \| null` |
+
 ### Creating Recursive Regions
 
 Use the `ref` attribute to mark an element as a recursive region, then use `<recurse>` to trigger recursion:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/compiler-jay-html",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -34,11 +34,11 @@
   },
   "author": "",
   "dependencies": {
-    "@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",
+    "@jay-framework/compiler-analyze-exported-types": "^0.9.0",
+    "@jay-framework/compiler-shared": "^0.9.0",
+    "@jay-framework/component": "^0.9.0",
+    "@jay-framework/runtime": "^0.9.0",
+    "@jay-framework/secure": "^0.9.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.8.0",
-    "@jay-framework/dev-environment": "^0.8.0",
+    "@jay-framework/4-react": "^0.9.0",
+    "@jay-framework/dev-environment": "^0.9.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",

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

@@ -9,6 +9,7 @@ The recursive jay-html feature allows marking HTML subtrees as recursive regions
 - `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
+- `$/data/path[]` syntax to unwrap array items and reference the item type
 
 ## Test Cases
 
@@ -126,8 +127,17 @@ const render = (viewState: TreeViewState) =>
 2. **Type Consistency**: The array/property type must match the recursive type reference
    - Array recursion: `array<$/data>` → `Array<ViewState>`
    - Single recursion: `$/data` → `ViewState | null`
+   - Array reference: `$/data/arrayProp` → `Array<ItemType>`
+   - Array item unwrap: `$/data/arrayProp[]` → `ItemType | 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
+5. **Array Unwrap Validation**: The `[]` syntax must point to an actual array property
+
+## Type Nullability Rules
+
+- **Non-array types** get `| null` since they may not exist
+- **Array types** don't get `| null` since an empty array (`[]`) can be used
+- **Repeated tags** with `repeated: true` always generate arrays
 
 ## Not Yet Tested
 
@@ -137,6 +147,5 @@ These fixtures do **not** yet test:
 - 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.