@jay-framework/jay-stack-cli 0.19.7 → 0.20.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.
|
@@ -11,7 +11,7 @@ Jay Stack is a full-stack framework where:
|
|
|
11
11
|
- **jay-html** templates provide the UI that binds to contract data
|
|
12
12
|
- **Rendering phases** determine when data is available (build-time, request-time, client-side)
|
|
13
13
|
|
|
14
|
-
Your job is to create `.jay-html` pages that bind to the data and interactions defined by contracts.
|
|
14
|
+
Your job is to create `.jay-html` pages that bind to the data and interactions defined by contracts. **All visible UI structure belongs in jay-html** — not in `page.ts` via `document.createElement`. Behavior and state live in `page.ts`; elements are reached through **refs** declared in the template.
|
|
15
15
|
|
|
16
16
|
## Rendering Phases
|
|
17
17
|
|
|
@@ -119,3 +119,35 @@ A tag can be both data and interactive:
|
|
|
119
119
|
```
|
|
120
120
|
|
|
121
121
|
This generates both a ViewState field and a ref.
|
|
122
|
+
|
|
123
|
+
## DOM access rules (Jay Stack pages)
|
|
124
|
+
|
|
125
|
+
Refs are the **only supported path** from TypeScript to elements Jay renders. Direct `document` access bypasses the framework and can break rendering, updates, and performance.
|
|
126
|
+
|
|
127
|
+
### Do
|
|
128
|
+
|
|
129
|
+
- Declare elements in **jay-html** with `ref="..."`.
|
|
130
|
+
- Drive overlays, lists, and visibility with **ViewState** (`if`, `forEach`, signal-backed bindings).
|
|
131
|
+
- Attach handlers with ref APIs: `refs.myRef.onclick`, `oninput`, `onkeydown`, etc.
|
|
132
|
+
- Use `refs.myRef.exec$((element, viewState) => …)` **inside handlers** for focus, scroll, measure, or native APIs.
|
|
133
|
+
- For drags: `setPointerCapture` on the ref element that received `pointerdown`, then listen on that element.
|
|
134
|
+
|
|
135
|
+
### Avoid
|
|
136
|
+
|
|
137
|
+
- `document.querySelector` / `getElementById` to find template elements
|
|
138
|
+
- `document.createElement` + `appendChild` for UI that belongs in jay-html
|
|
139
|
+
- `document.addEventListener('mousemove'|'mouseup')` for drags (use pointer capture instead)
|
|
140
|
+
|
|
141
|
+
### Rare `document` exceptions
|
|
142
|
+
|
|
143
|
+
Use only when no ref can exist, with an inline comment:
|
|
144
|
+
|
|
145
|
+
| Case | Example |
|
|
146
|
+
| ---------------------- | ----------------------------------------------------- |
|
|
147
|
+
| Offscreen processing | `document.createElement('canvas')` for image export |
|
|
148
|
+
| Coordinate hit-testing | `document.elementFromPoint` during cross-overlay drag |
|
|
149
|
+
| Tests | `document.dispatchEvent` in Vitest |
|
|
150
|
+
|
|
151
|
+
Global shortcuts or paste: prefer a root shell ref (`ref="appRoot"`) with capture listeners.
|
|
152
|
+
|
|
153
|
+
See also: `.cursor/skills/jay-dom-refs/SKILL.md` in the jay monorepo.
|
|
@@ -81,6 +81,12 @@ export const page = makeJayStackComponent<ProductPageContract>()
|
|
|
81
81
|
});
|
|
82
82
|
```
|
|
83
83
|
|
|
84
|
+
## DOM access in interactive phase
|
|
85
|
+
|
|
86
|
+
Reach rendered elements through **refs** only. Put overlays, panels, and lists in **jay-html**; drive them with ViewState from `.withInteractive`. Do not use `document.querySelector`, imperative `createElement` UI, or document-level drag listeners.
|
|
87
|
+
|
|
88
|
+
See [component-refs.md](component-refs.md#dom-access-rules-jay-stack-pages).
|
|
89
|
+
|
|
84
90
|
## Calling File Upload Actions
|
|
85
91
|
|
|
86
92
|
Actions created with `.withFiles()` accept browser `File` objects directly. Use `oninput` events on file inputs to drive signals, then pass them to the action:
|
|
@@ -119,3 +119,35 @@ A tag can be both data and interactive:
|
|
|
119
119
|
```
|
|
120
120
|
|
|
121
121
|
This generates both a ViewState field and a ref.
|
|
122
|
+
|
|
123
|
+
## DOM access rules (Jay Stack pages)
|
|
124
|
+
|
|
125
|
+
Refs are the **only supported path** from TypeScript to elements Jay renders. Direct `document` access bypasses the framework and can break rendering, updates, and performance.
|
|
126
|
+
|
|
127
|
+
### Do
|
|
128
|
+
|
|
129
|
+
- Declare elements in **jay-html** with `ref="..."`.
|
|
130
|
+
- Drive overlays, lists, and visibility with **ViewState** (`if`, `forEach`, signal-backed bindings).
|
|
131
|
+
- Attach handlers with ref APIs: `refs.myRef.onclick`, `oninput`, `onkeydown`, etc.
|
|
132
|
+
- Use `refs.myRef.exec$((element, viewState) => …)` **inside handlers** for focus, scroll, measure, or native APIs.
|
|
133
|
+
- For drags: `setPointerCapture` on the ref element that received `pointerdown`, then listen on that element.
|
|
134
|
+
|
|
135
|
+
### Avoid
|
|
136
|
+
|
|
137
|
+
- `document.querySelector` / `getElementById` to find template elements
|
|
138
|
+
- `document.createElement` + `appendChild` for UI that belongs in jay-html
|
|
139
|
+
- `document.addEventListener('mousemove'|'mouseup')` for drags (use pointer capture instead)
|
|
140
|
+
|
|
141
|
+
### Rare `document` exceptions
|
|
142
|
+
|
|
143
|
+
Use only when no ref can exist, with an inline comment:
|
|
144
|
+
|
|
145
|
+
| Case | Example |
|
|
146
|
+
| ---------------------- | ----------------------------------------------------- |
|
|
147
|
+
| Offscreen processing | `document.createElement('canvas')` for image export |
|
|
148
|
+
| Coordinate hit-testing | `document.elementFromPoint` during cross-overlay drag |
|
|
149
|
+
| Tests | `document.dispatchEvent` in Vitest |
|
|
150
|
+
|
|
151
|
+
Global shortcuts or paste: prefer a root shell ref (`ref="appRoot"`) with capture listeners.
|
|
152
|
+
|
|
153
|
+
See also: `.cursor/skills/jay-dom-refs/SKILL.md` in the jay monorepo.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jay-framework/jay-stack-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -24,15 +24,15 @@
|
|
|
24
24
|
"test:watch": "vitest"
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"@jay-framework/compiler-jay-html": "^0.
|
|
28
|
-
"@jay-framework/compiler-shared": "^0.
|
|
29
|
-
"@jay-framework/dev-server": "^0.
|
|
30
|
-
"@jay-framework/editor-server": "^0.
|
|
31
|
-
"@jay-framework/fullstack-component": "^0.
|
|
32
|
-
"@jay-framework/logger": "^0.
|
|
33
|
-
"@jay-framework/plugin-validator": "^0.
|
|
34
|
-
"@jay-framework/production-server": "^0.
|
|
35
|
-
"@jay-framework/stack-server-runtime": "^0.
|
|
27
|
+
"@jay-framework/compiler-jay-html": "^0.20.0",
|
|
28
|
+
"@jay-framework/compiler-shared": "^0.20.0",
|
|
29
|
+
"@jay-framework/dev-server": "^0.20.0",
|
|
30
|
+
"@jay-framework/editor-server": "^0.20.0",
|
|
31
|
+
"@jay-framework/fullstack-component": "^0.20.0",
|
|
32
|
+
"@jay-framework/logger": "^0.20.0",
|
|
33
|
+
"@jay-framework/plugin-validator": "^0.20.0",
|
|
34
|
+
"@jay-framework/production-server": "^0.20.0",
|
|
35
|
+
"@jay-framework/stack-server-runtime": "^0.20.0",
|
|
36
36
|
"chalk": "^4.1.2",
|
|
37
37
|
"commander": "^14.0.0",
|
|
38
38
|
"express": "^5.0.1",
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
"yaml": "^2.3.4"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
|
-
"@jay-framework/dev-environment": "^0.
|
|
46
|
+
"@jay-framework/dev-environment": "^0.20.0",
|
|
47
47
|
"@types/express": "^5.0.2",
|
|
48
48
|
"@types/node": "^22.15.21",
|
|
49
49
|
"nodemon": "^3.0.3",
|