@jay-framework/compiler-jay-html 0.5.0

package/docs/compiler-patterns.md

@@ -0,0 +1,145 @@
+# Jay Compiler Patterns
+
+Jay Compiler Patterns are used by jay security module for detecting safe code patterns that can be extracted from
+a component file and run in the main context, while the rest of the component runs in a sandbox.
+
+A simple example is the following event handler:
+
+```typescript
+refs.cycles.oninput(({ event }: JayEvent<Event, MainViewState>) => {
+  const cycles = (event.target as HTMLInputElement).value;
+  setCycles(Number(cycles));
+});
+```
+
+As the event handler can run in a sandbox environment that does not have access to the browser native event,
+the code above will break unless is running in the main context `(event.target as HTMLInputElement).value`.
+
+Given the compiler pattern
+
+```typescript
+import { JayEvent } from '@jay-framework/runtime';
+function inputValuePattern({ event }: JayEvent<any, any>) {
+  return event.target.value;
+}
+```
+
+The event handler is rewritten into
+
+```typescript
+refs.cycles.oninput$(handler$('1')).then(({ event }: JayEvent<any, MainViewState>) => {
+  setCycles(Number(event.$0));
+});
+```
+
+while the main context gains
+
+```typescript
+const funcRepository: FunctionsRepository = {
+  '1': ({ event }: JayEvent<any, any>) => {
+    const cycles = (event.target as HTMLInputElement).value;
+    return { $0: event.target.value };
+  },
+};
+```
+
+The full example can be found at [mini-benchmark](../../../../examples/jay/mini-benchmark)
+
+## Writing compiler patterns
+
+Jay compiler patterns are written as TS functions. However, those functions are not run directly, instead, they are
+compiled into AST patterns that are matched against AST of event handlers and `exec$` APIs.
+
+Pattern matching is checking
+
+1. the access path used for values
+2. the input parameter types
+3. the output type
+4. Compiler patterns are designed to be simple, one liner expressions.
+5. A function can contain multiple lines, at which each line is considered a different expression.
+6. the `@JayPattern` can be used to force a pattern to only be valid in a certain environment.
+
+Jay supports a number of types of patterns:
+
+## return patterns
+
+A return pattern is a pattern that returns a value, which can be used by the component code (as in the example above).
+
+A return pattern is written as a function that returns a value.
+
+```typescript
+import { JayEvent } from '@jay-framework/runtime';
+
+function inputValuePattern(handler: JayEvent<any, any>): string {
+  return handler.event.target.value;
+}
+```
+
+- A return pattern must have a type
+- A pattern must have parameter types
+
+> Note: it is not important if we write the pattern using `handler.event.target.value` or
+> deconstruct the handler with `{ event }` and write the pattern as `event.target.value` - the AST matching is the same.
+
+## call patterns
+
+A call pattern is a pattern that matches a call to a function.
+
+```typescript
+import {JayEvent} from '@jay-framework/runtime';
+
+@JayPattern(JayTargetEnv.main)
+function eventPreventDefault(handler: JayEvent<any, any>) {
+    handler.event.preventDefault();
+}
+```
+
+The pattern above allows the call of the native `event.preventDefault()` in the main context.
+
+## chainable call patterns
+
+The combination of a call pattern and a return pattern, allowing to match a sequence of return and call functions.
+
+An example is the string replace function which can run in any environment.
+
+```typescript
+@JayPattern(JayTargetEnv.any)
+function stringReplace(value: string, regex: RegExp, replacement: string): string {
+    return value.replace(regex, replacement)
+}
+```
+
+> Note: the matching is only on the function body `value.replace(regex, replacement)`. The parameters and return
+> are just indications of types and inputs / outputs.
+
+## assignment pattern
+
+Assignment pattern allows to support assignment of values directly in the main context.
+
+An example is the assignment of a string value to an input.
+
+```typescript
+import {JayEvent} from '@jay-framework/runtime';
+
+@JayPattern(JayTargetEnv.main)
+function setInputValue(handler: JayEvent<any, any>, value: string) {
+    handler.event.target.value = value;
+}
+```
+
+In most cases, the same can be achieved using state management. However, consider the following event handler
+
+```typescript
+refs.input.onClick(({ event }) => {
+  const inputValue = event.target.value;
+  const validValue = inputValue.replace(/[^A-Za-z0-9]+/g, '');
+  event.target.value = validValue;
+});
+```
+
+The combination of assignment, read and chainable call patterns allows to push all of the event handler to the main
+context for sync input validation.
+
+## constants
+
+Constants are considered "safe" be definition and if used in patterns are also extracted to the main context.

package/docs/contract-file-format.md

@@ -0,0 +1,297 @@
+# Contract File Format
+
+Contract files (`.jay-contract`) define the interface between headless components and their UI implementations. They specify the data structure, interactive elements, and component composition using a YAML-based format.
+
+## Basic Structure
+
+A contract file consists of a `name` and a list of `tags`:
+
+```yaml
+name: component-name
+tags:
+  - tag: tagName
+    type: tagType
+    # additional properties based on type
+```
+
+## Tag Types
+
+### Data Tags
+
+Data tags define the component's view state properties.
+
+```yaml
+- tag: count
+  type: data
+  dataType: number
+  required: true
+  description: The current count value
+```
+
+**Properties:**
+
+- `type: data` - Identifies this as a data property
+- `dataType` - The data type (string, number, boolean, enum)
+- `required` - (Optional) Whether this property is required
+- `description` - (Optional) Documentation for the property
+
+### Interactive Tags
+
+Interactive tags define elements that can be interacted with programmatically.
+
+```yaml
+- tag: submitButton
+  type: interactive
+  elementType: HTMLButtonElement
+  description: Button to submit the form
+```
+
+**Properties:**
+
+- `type: interactive` - Identifies this as an interactive element
+- `elementType` - The HTML element type (required)
+- `description` - (Optional) Documentation for the element
+
+### Variant Tags
+
+Variant tags define design variations or states.
+
+```yaml
+- tag: status
+  type: variant
+  dataType: enum (active | inactive | pending)
+  description: The current status of the component
+```
+
+**Properties:**
+
+- `type: variant` - Identifies this as a variant
+- `dataType` - Must be an enum type (required)
+- `description` - (Optional) Documentation for the variant
+
+### Sub-Contract Tags
+
+Sub-contract tags define nested component structures.
+
+```yaml
+- tag: items
+  type: sub-contract
+  repeated: true
+  tags:
+    - tag: title
+      type: data
+      dataType: string
+    - tag: completed
+      type: data
+      dataType: boolean
+```
+
+**Properties:**
+
+- `type: sub-contract` - Identifies this as a nested contract
+- `repeated` - (Optional) Whether this represents an array of items
+- `tags` - Nested tag definitions
+- `link` - (Alternative to tags) Reference to another contract file
+
+## Linked Contracts
+
+Linked contracts allow you to reference external contract files, enabling component reuse and modular design. Instead of defining nested tags inline, you can link to a separate contract file.
+
+### Basic Linked Contract
+
+```yaml
+- tag: discount
+  type: sub-contract
+  link: ./discount
+```
+
+This references a `discount.jay-contract` file in the same directory.
+
+### Linked Contract with Repeated Items
+
+```yaml
+- tag: media
+  type: sub-contract
+  tags:
+    - tag: items
+      type: sub-contract
+      link: ./media-item
+      repeated: true
+```
+
+This creates an array of items, each following the structure defined in `media-item.jay-contract`.
+
+### Benefits of Linked Contracts
+
+1. **Reusability** - Define a contract once and use it across multiple components
+2. **Maintainability** - Changes to the linked contract automatically apply everywhere
+3. **Modularity** - Break complex components into smaller, focused contracts
+4. **Consistency** - Ensure consistent structure across related components
+
+### File Resolution
+
+- **Relative paths** - `./component` or `../components/button`
+- **Module imports** - `<npm-module-name>/<path-to-contract>`
+- **File extension** - The `.jay-contract` extension is automatically appended
+- **Directory structure** - Contracts can be organized in subdirectories
+
+### Example: E-commerce Product Structure
+
+```yaml
+name: product-page
+tags:
+  - tag: name
+    type: data
+    dataType: string
+  - tag: price
+    type: data
+    dataType: number
+  - tag: discount
+    type: sub-contract
+    link: ./discount
+  - tag: media
+    type: sub-contract
+    tags:
+      - tag: items
+        type: sub-contract
+        link: ./media-item
+        repeated: true
+      - tag: mainMedia
+        type: sub-contract
+        link: ./media-item
+  - tag: addToCart
+    type: interactive
+    elementType: HTMLButtonElement
+```
+
+In this example:
+
+- `discount` links to a reusable discount contract
+- `media.items` creates an array of media items using the linked contract
+- `media.mainMedia` uses the same contract for a single item
+
+### Best Practices for Linked Contracts
+
+1. **Use descriptive names** for contract files that indicate their purpose
+2. **Keep contracts focused** - Each linked contract should represent a single concept
+3. **Organize by feature** - Group related contracts in feature-specific directories
+4. **Document dependencies** - Make it clear which contracts are required
+5. **Version contracts** - Consider versioning for breaking changes
+
+## Data Types
+
+### Basic Types
+
+| Type      | Example             | Description       |
+| --------- | ------------------- | ----------------- |
+| `string`  | `dataType: string`  | Text values       |
+| `number`  | `dataType: number`  | Numeric values    |
+| `boolean` | `dataType: boolean` | True/false values |
+
+### Enum Types
+
+```yaml
+dataType: enum (option1 | option2 | option3)
+```
+
+Enums define a set of allowed values separated by `|`.
+
+## Examples
+
+### Simple Counter Component
+
+```yaml
+name: counter
+tags:
+  - tag: count
+    type: data
+    dataType: number
+    required: true
+  - tag: add
+    type: interactive
+    elementType: HTMLButtonElement
+  - tag: subtract
+    type: interactive
+    elementType: HTMLButtonElement
+```
+
+### Form Component with Nested Structure
+
+```yaml
+name: userForm
+tags:
+  - tag: submitButton
+    type: interactive
+    elementType: HTMLButtonElement
+  - tag: personalInfo
+    type: sub-contract
+    tags:
+      - tag: sectionTitle
+        type: data
+        dataType: string
+      - tag: nameFields
+        type: sub-contract
+        tags:
+          - tag: firstName
+            type: [data, interactive]
+            dataType: string
+            elementType: HTMLInputElement
+          - tag: lastName
+            type: [data, interactive]
+            dataType: string
+            elementType: HTMLInputElement
+```
+
+### Product Component with External References
+
+```yaml
+name: product-page
+tags:
+  - tag: name
+    type: data
+    dataType: string
+  - tag: price
+    type: data
+    dataType: number
+  - tag: discount
+    type: sub-contract
+    link: ./discount
+  - tag: media
+    type: sub-contract
+    tags:
+      - tag: items
+        type: sub-contract
+        link: ./media-item
+        repeated: true
+  - tag: addToCart
+    type: interactive
+    elementType: HTMLButtonElement
+```
+
+## Validation Rules
+
+### Required Properties
+
+- **Variant tags** must have a `dataType` (enum)
+- **Interactive tags** must have an `elementType`
+- **Sub-contract tags** must have either `tags` or `link`
+
+### Type Restrictions
+
+- **Sub-contract tags** cannot be combined with other types
+- **Sub-contract tags** cannot have `dataType` or `elementType`
+- **Unknown tag types** will cause validation errors
+
+### Defaults
+
+- If `type` is not specified, defaults to `data`
+- If `dataType` is not specified for data tags, defaults to `string`
+
+## Best Practices
+
+1. **Use descriptive names** for tags that clearly indicate their purpose
+2. **Add descriptions** to document complex or non-obvious tags
+3. **Use enums** for variant tags to ensure type safety
+4. **Structure nested contracts** logically to match your component hierarchy
+5. **Reference external contracts** for reusable sub-components
+6. **Mark required properties** explicitly for better validation

package/docs/jay-html-docs.md

@@ -0,0 +1,178 @@
+# Jay-HTML Syntax Reference
+
+Jay-HTML extends standard HTML with several features for component-based development. This document covers the syntax elements that distinguish Jay-HTML from regular HTML.
+
+A Jay-HTML file must contain one `application/jay-data` script and can include several unique Jay directives.
+
+## Data Contract Definition
+
+The data contract defines the `ViewState` - the input data structure for the component.
+The ViewState is defined as a YAML script with `data:` as the root element.
+Each property in the YAML becomes a property of the component's view state, supporting nested objects and arrays.
+
+### Supported Data Types
+
+| Type            | Example                                                                      | Description                          |
+| --------------- | ---------------------------------------------------------------------------- | ------------------------------------ |
+| `string`        | `text: string`                                                               | Text values                          |
+| `number`        | `count: number`                                                              | Numeric values                       |
+| `boolean`       | `isVisible: boolean`                                                         | True/false values                    |
+| `object`        | <code>user: </br>&nbsp;&nbsp;name: string</br>&nbsp;&nbsp;age: number</code> | Nested object structures             |
+| `array`         | <code>items: </br>-&nbsp;name: string</br>&nbsp;&nbsp;value: number</code>   | Collections of items                 |
+| `enum`          | `status: enum(active \| inactive \| pending)`                                | Enumerated values                    |
+| `imported type` | `config: ImportedConfig`                                                     | Types imported from other components |
+
+### View State Context
+
+Jay-HTML treats the view state as the **current context** that gets bound to components and elements. The `forEach` directive changes this context from an object to individual array items.
+
+#### Example: Context Switching with forEach
+
+```yaml
+data:
+  users:
+    - id: string
+    - name: string
+    - email: string
+```
+
+```html
+<!-- Current context: users array -->
+<div forEach="users" trackBy="id">
+  <!-- Current context: individual user object -->
+  <span>{name}</span>
+  <span>{email}</span>
+</div>
+```
+
+In this example, the context switches from the `users` array to individual `user` objects within the forEach loop.
+
+## Component Usage
+
+Jay-HTML allows you to use components as part of the HTML structure. Components must be imported before they can be used.
+
+### Importing Components
+
+```html
+<script
+  type="application/jay-headfull"
+  src="./my-component.ts"
+  names="MyComponent"
+  sandbox="false"
+></script>
+```
+
+### Using Components
+
+```html
+<MyComponent title="Welcome" count="{itemCount}"></MyComponent>
+```
+
+### Property Binding Options
+
+Components accept properties in three ways:
+
+1. **Static values**: `title="Welcome"`
+2. **View state bindings**: `count="{itemCount}"` - binds to a specific property
+3. **Context binding**: `data="{.}"` - binds the entire current context
+
+> **Note**: Jay currently doesn't support passing children as properties to components. This feature is planned for future releases.
+
+## Element References
+
+The `ref` attribute creates references to HTML elements or components that your component code can interact with.
+
+### Creating References
+
+```html
+<div ref="mainContainer">{content}</div>
+<Counter ref="counterComponent" initialValue="{startCount}" />
+```
+
+For each element with a `ref` attribute, Jay generates a corresponding member in the component's refs type, enabling programmatic interaction.
+
+Reference types are defined in the `@jay-framework/runtime` library - see [refs.md](../../../runtime/runtime/docs/refs.md) for details.
+
+## Data Binding
+
+The `{}` syntax enables dynamic data binding to the current view state context. This syntax supports property access, conditional expressions, and simple operations.
+
+### Basic Binding
+
+```html
+<div>{title}</div>
+<div>Hello, {user.name}!</div>
+<div>Count: {items.length}</div>
+```
+
+### Conditional Expressions
+
+```html
+<div>{isVisible ? 'Visible' : 'Hidden'}</div>
+<div>{hasName ? name : 'Anonymous'}</div>
+<div>{!isLoading ? 'Ready' : 'Loading...'}</div>
+```
+
+### Enum Comparisons
+
+```html
+<div>{status === 'active' ? 'Online' : 'Offline'}</div>
+<div>{role !== 'admin' ? 'User' : 'Administrator'}</div>
+```
+
+### Class Binding
+
+Class bindings support dynamic and conditional class inclusion:
+
+```html
+<div class="{status}">Status indicator</div>
+<div class="{isActive ? 'active' : 'inactive'}">Toggle state</div>
+<div class="{isPrimary ? 'primary' : 'secondary'} button">Button</div>
+```
+
+## Conditional Rendering
+
+The `if` directive conditionally renders elements based on expressions.
+
+### Basic Conditional Rendering
+
+```html
+<div if="isVisible">
+  <p>This content is only shown when isVisible is true</p>
+</div>
+```
+
+> **Note**: The `if` directive automatically evaluates expressions, so `{}` binding syntax is not needed.
+
+## List Rendering
+
+The `forEach` and `trackBy` directives enable rendering lists of items.
+
+### Basic List Rendering
+
+```html
+<ul>
+  <li forEach="users" trackBy="id">
+    <span>{name}</span>
+    <span>{email}</span>
+  </li>
+</ul>
+```
+
+### How It Works
+
+- `forEach="users"` - iterates over the `users` array
+- `trackBy="id"` - uses the `id` property to track items for efficient DOM updates
+- Within the loop, the context becomes individual array items
+
+Since Jay uses immutable view state, the `trackBy` attribute is essential for proper item tracking and DOM optimization.
+
+### Example with Component
+
+```html
+<div forEach="products" trackBy="sku">
+  <ProductCard product="{.}" />
+</div>
+```
+
+In this example, each `ProductCard` component receives the entire product object as its context.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@jay-framework/compiler-jay-html",
+  "version": "0.5.0",
+  "description": "",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "directories": {
+    "lib": "lib"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:pegjs && npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:pegjs": "pegjs --allowed-start-rules dynamicAttribute,booleanAttribute,dynamicText,dynamicProperty,conditionFunc,accessor,Identifier,classExpression,dynamicComponentProp,importNames,enum,is_enum,reactDynamicText,reactDynamicProperty,reactClassExpression,condition  -o lib/expressions/expression-parser.cjs lib/expressions/expression-parser.pegjs",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format cjs",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "",
+  "dependencies": {
+    "@jay-framework/compiler-analyze-exported-types": "workspace:^",
+    "@jay-framework/compiler-shared": "workspace:^",
+    "@jay-framework/component": "workspace:^",
+    "@jay-framework/runtime": "workspace:^",
+    "@jay-framework/secure": "workspace:^",
+    "@types/js-yaml": "^4.0.9",
+    "change-case": "^4.1.2",
+    "js-yaml": "^4.1.0",
+    "node-html-parser": "^6.1.12",
+    "pegjs": "^0.10.0",
+    "pluralize": "^8.0.0",
+    "style-to-object": "^1.0.8",
+    "typescript": "^5.3.3"
+  },
+  "devDependencies": {
+    "@caiogondim/strip-margin": "^1.0.0",
+    "@jay-framework/4-react": "workspace:^",
+    "@jay-framework/dev-environment": "workspace:^",
+    "@testing-library/jest-dom": "^6.2.0",
+    "@types/js-beautify": "^1",
+    "@types/node": "^20.11.5",
+    "@types/react": "^18.2.0",
+    "jest-diff": "^29.7.0",
+    "jest-matcher-utils": "^29.7.0",
+    "js-beautify": "^1.14.11",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}