@jay-framework/compiler-jay-html 0.5.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.
- package/dist/index.d.ts +96 -0
- package/dist/index.js +6464 -0
- package/docs/compiler-patterns.md +145 -0
- package/docs/contract-file-format.md +297 -0
- package/docs/jay-html-docs.md +178 -0
- package/package.json +62 -0
- package/readme.md +115 -0
package/readme.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Jay-HTML Format & Compiler
|
|
2
|
+
|
|
3
|
+
Jay-HTML extends standard HTML with minimal additions to support component-based development. It provides a declarative way to define component interfaces and data contracts.
|
|
4
|
+
|
|
5
|
+
## Basic Example
|
|
6
|
+
|
|
7
|
+
Here's a simple Jay-HTML file:
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<html>
|
|
11
|
+
<head>
|
|
12
|
+
<script type="application/yaml-jay">
|
|
13
|
+
data:
|
|
14
|
+
count: number
|
|
15
|
+
</script>
|
|
16
|
+
</head>
|
|
17
|
+
<body>
|
|
18
|
+
<div>
|
|
19
|
+
<button ref="subtracter">-</button>
|
|
20
|
+
<span style="margin: 0 16px">{count}</span>
|
|
21
|
+
<button ref="adder-button">+</button>
|
|
22
|
+
</div>
|
|
23
|
+
</body>
|
|
24
|
+
</html>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Key Differences from Standard HTML
|
|
28
|
+
|
|
29
|
+
Jay-HTML extends HTML with seven main features:
|
|
30
|
+
|
|
31
|
+
1. **Component and type imports** - Import reusable components and type definitions
|
|
32
|
+
2. **Data contract definition** - Define component interfaces using YAML
|
|
33
|
+
3. **Component composition** - Use imported components as HTML elements
|
|
34
|
+
4. **Element references** - Create programmatic references to DOM elements
|
|
35
|
+
5. **Data binding** - Bind component data to HTML using `{}` syntax
|
|
36
|
+
6. **Conditional rendering** - Show/hide elements based on conditions
|
|
37
|
+
7. **List rendering** - Iterate over arrays with `forEach` and `trackBy`
|
|
38
|
+
|
|
39
|
+
## Component Import System
|
|
40
|
+
|
|
41
|
+
Jay-HTML provides a TypeScript-like import system adapted for HTML. You can import both headfull and headless components.
|
|
42
|
+
|
|
43
|
+
### Importing Headfull Components
|
|
44
|
+
|
|
45
|
+
Headfull components include both the contract and UI design:
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<script
|
|
49
|
+
type="application/jay-headfull"
|
|
50
|
+
src="{path}"
|
|
51
|
+
names="{names to import}"
|
|
52
|
+
sandbox="{boolean}"
|
|
53
|
+
></script>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**Parameters:**
|
|
57
|
+
|
|
58
|
+
- `path` - Relative or absolute path to the component file
|
|
59
|
+
- `names` - Comma-separated list of exported members. Supports renaming with `name as alias` syntax
|
|
60
|
+
- `sandbox` - (Optional, defaults to false) Enable sandboxed component execution
|
|
61
|
+
|
|
62
|
+
### Importing Headless Components
|
|
63
|
+
|
|
64
|
+
Headless components provide only the contract and logic:
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<script
|
|
68
|
+
type="application/jay-headless"
|
|
69
|
+
contract="{contract-path}"
|
|
70
|
+
src="{component-path}"
|
|
71
|
+
name="{component-name}"
|
|
72
|
+
key="{nested-key}"
|
|
73
|
+
></script>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**Parameters:**
|
|
77
|
+
|
|
78
|
+
- `contract` - Path to the contract file (`.jay-contract`)
|
|
79
|
+
- `src` - Path to the component implementation
|
|
80
|
+
- `name` - Name of the exported component definition
|
|
81
|
+
- `key` - Attribute name for nesting the component's ViewState and Refs
|
|
82
|
+
|
|
83
|
+
### Import Examples
|
|
84
|
+
|
|
85
|
+
```html
|
|
86
|
+
<!-- Import a headfull component -->
|
|
87
|
+
<script type="application/jay-headfull" src="./counter.ts" names="Counter" sandbox="false"></script>
|
|
88
|
+
|
|
89
|
+
<!-- Import multiple components with aliases -->
|
|
90
|
+
<script
|
|
91
|
+
type="application/jay-headfull"
|
|
92
|
+
src="./ui-components.ts"
|
|
93
|
+
names="Button as PrimaryButton, Card as ProductCard"
|
|
94
|
+
sandbox="true"
|
|
95
|
+
></script>
|
|
96
|
+
|
|
97
|
+
<!-- Import a headless component -->
|
|
98
|
+
<script
|
|
99
|
+
type="application/jay-headless"
|
|
100
|
+
contract="../data-store/store.jay-contract"
|
|
101
|
+
src="../data-store/store"
|
|
102
|
+
name="dataStore"
|
|
103
|
+
key="store"
|
|
104
|
+
></script>
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Documentation
|
|
108
|
+
|
|
109
|
+
### Jay-HTML Syntax
|
|
110
|
+
|
|
111
|
+
Read the complete Jay-HTML syntax reference including data contracts, component usage, data binding, and directives in [jay-html-docs.md](docs/jay-html-docs.md).
|
|
112
|
+
|
|
113
|
+
### Contract File Format
|
|
114
|
+
|
|
115
|
+
Learn about the structure and format of `.jay-contract` files used for headless components in [contract-file-format.md](docs/contract-file-format.md).
|