@atom.io/spa 0.0.0-stage → 0.0.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/LICENSE +373 -0
- package/README.md +401 -2
- package/README.mdx +150 -0
- package/dist/astro-application.d.ts +15 -0
- package/dist/astro-application.d.ts.map +1 -0
- package/dist/astro-application.js +62 -0
- package/dist/astro-application.js.map +1 -0
- package/dist/astro-client.d.ts +9 -0
- package/dist/astro-client.d.ts.map +1 -0
- package/dist/astro-client.js +98 -0
- package/dist/astro-client.js.map +1 -0
- package/dist/astro-context-OdlexHR4.js +79 -0
- package/dist/astro-context-OdlexHR4.js.map +1 -0
- package/dist/astro-middleware.d.ts +4 -0
- package/dist/astro-middleware.d.ts.map +1 -0
- package/dist/astro-middleware.js +49 -0
- package/dist/astro-middleware.js.map +1 -0
- package/dist/astro-request-DRKvDjsO.js +70 -0
- package/dist/astro-request-DRKvDjsO.js.map +1 -0
- package/dist/astro-server.d.ts +4 -0
- package/dist/astro-server.d.ts.map +1 -0
- package/dist/astro-server.js +30 -0
- package/dist/astro-server.js.map +1 -0
- package/dist/astro-shared-BT45auwR.js +29 -0
- package/dist/astro-shared-BT45auwR.js.map +1 -0
- package/dist/astro-shared-DkZaqX7L.d.ts +31 -0
- package/dist/astro-shared-DkZaqX7L.d.ts.map +1 -0
- package/dist/astro.d.ts +6 -0
- package/dist/astro.d.ts.map +1 -0
- package/dist/astro.js +26 -0
- package/dist/astro.js.map +1 -0
- package/dist/client.min.d.ts +1 -0
- package/dist/client.min.js +1 -0
- package/dist/core-BhiA9fFi.d.ts +44 -0
- package/dist/core-BhiA9fFi.d.ts.map +1 -0
- package/dist/core-Dvqm7w2y.js +231 -0
- package/dist/core-Dvqm7w2y.js.map +1 -0
- package/dist/development/astro-application.js +62 -0
- package/dist/development/astro-application.js.map +1 -0
- package/dist/development/astro-client.js +98 -0
- package/dist/development/astro-client.js.map +1 -0
- package/dist/development/astro-context-OdlexHR4.js +79 -0
- package/dist/development/astro-context-OdlexHR4.js.map +1 -0
- package/dist/development/astro-middleware.js +49 -0
- package/dist/development/astro-middleware.js.map +1 -0
- package/dist/development/astro-request-DRKvDjsO.js +70 -0
- package/dist/development/astro-request-DRKvDjsO.js.map +1 -0
- package/dist/development/astro-server.js +30 -0
- package/dist/development/astro-server.js.map +1 -0
- package/dist/development/astro-shared-BT45auwR.js +29 -0
- package/dist/development/astro-shared-BT45auwR.js.map +1 -0
- package/dist/development/astro.js +26 -0
- package/dist/development/astro.js.map +1 -0
- package/dist/development/core-DB3sQz4h.js +234 -0
- package/dist/development/core-DB3sQz4h.js.map +1 -0
- package/dist/development/dom-D9cY6l1R.js +194 -0
- package/dist/development/dom-D9cY6l1R.js.map +1 -0
- package/dist/development/index.js +40 -0
- package/dist/development/index.js.map +1 -0
- package/dist/development/jsx-runtime.js +25 -0
- package/dist/development/jsx-runtime.js.map +1 -0
- package/dist/development/server.js +78 -0
- package/dist/development/server.js.map +1 -0
- package/dist/development/vite-BadrFSIM.js +126 -0
- package/dist/development/vite-BadrFSIM.js.map +1 -0
- package/dist/development/vite.js +1 -0
- package/dist/dom-BR9o9wZW.js +188 -0
- package/dist/dom-BR9o9wZW.js.map +1 -0
- package/dist/index.d.ts +24 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +40 -0
- package/dist/index.js.map +1 -0
- package/dist/jsx-runtime-BzGV18VO.d.ts +965 -0
- package/dist/jsx-runtime-BzGV18VO.d.ts.map +1 -0
- package/dist/jsx-runtime.d.ts +2 -0
- package/dist/jsx-runtime.js +25 -0
- package/dist/jsx-runtime.js.map +1 -0
- package/dist/server.d.ts +3 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +78 -0
- package/dist/server.js.map +1 -0
- package/dist/size.json +30 -0
- package/dist/vite-BadrFSIM.js +126 -0
- package/dist/vite-BadrFSIM.js.map +1 -0
- package/dist/vite.d.ts +6 -0
- package/dist/vite.d.ts.map +1 -0
- package/dist/vite.js +1 -0
- package/package.json +131 -5
- package/src/astro-application.ts +71 -0
- package/src/astro-client.ts +136 -0
- package/src/astro-context.ts +102 -0
- package/src/astro-middleware.ts +48 -0
- package/src/astro-request.ts +79 -0
- package/src/astro-server.ts +43 -0
- package/src/astro-shared.ts +78 -0
- package/src/astro.ts +47 -0
- package/src/compiler.ts +189 -0
- package/src/core.ts +385 -0
- package/src/dom.ts +385 -0
- package/src/env.d.ts +1 -0
- package/src/index.ts +24 -0
- package/src/jsx-runtime.ts +63 -0
- package/src/jsx-types.d.ts +909 -0
- package/src/server.ts +150 -0
- package/src/use-loadable.ts +67 -0
- package/src/vite.ts +48 -0
package/README.md
CHANGED
|
@@ -1,3 +1,402 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center"><img src="https://raw.githubusercontent.com/jeremybanka/atom.io/main/apps/atom.io.fyi/public/spa/icon-512.png" alt="SPA logo" width="160" height="160"></p>
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# SPA
|
|
4
|
+
|
|
5
|
+
An experimental JSX framework whose state engine is atom.io. Components run once per mounted instance. Calls to accessors inside compiled JSX subscribe the affected DOM computations; atom.io updates those computations without rerunning component setup.
|
|
6
|
+
|
|
7
|
+
The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here. It has no independent state primitive, effect API, React hook dispatcher, or compatibility layer.
|
|
8
|
+
|
|
9
|
+
## A point, not two signals
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
import type { VNode } from "@atom.io/spa"
|
|
13
|
+
import { useId, useRef, useSetter, useValue } from "@atom.io/spa"
|
|
14
|
+
import { atom } from "atom.io"
|
|
15
|
+
|
|
16
|
+
const pointAtom = atom<{ x: number; y: number }>({
|
|
17
|
+
key: `point`,
|
|
18
|
+
default: { x: 20, y: 20 },
|
|
19
|
+
})
|
|
20
|
+
const circleAtom = atom<SVGCircleElement | null>({
|
|
21
|
+
key: `circle`,
|
|
22
|
+
default: null,
|
|
23
|
+
})
|
|
24
|
+
|
|
25
|
+
export function PointEditor(): VNode {
|
|
26
|
+
const point = useValue(pointAtom)
|
|
27
|
+
const setPoint = useSetter(pointAtom)
|
|
28
|
+
const circle = useRef(circleAtom)
|
|
29
|
+
const id = useId()
|
|
30
|
+
return (
|
|
31
|
+
<section aria-labelledby={id}>
|
|
32
|
+
<h2 id={id}>Point</h2>
|
|
33
|
+
<svg viewBox="0 0 100 100">
|
|
34
|
+
<circle ref={circle} cx={point().x} cy={point().y} r="3" />
|
|
35
|
+
</svg>
|
|
36
|
+
<output>
|
|
37
|
+
{point().x}, {point().y}
|
|
38
|
+
</output>
|
|
39
|
+
<button
|
|
40
|
+
onClick={() => {
|
|
41
|
+
setPoint(({ x, y }) => ({ x: x + 1, y }))
|
|
42
|
+
}}
|
|
43
|
+
>
|
|
44
|
+
Move right
|
|
45
|
+
</button>
|
|
46
|
+
</section>
|
|
47
|
+
)
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The point accessor returns the current object. Each JSX attribute reads its coordinate when evaluated. Both bindings depend on the point atom, and unchanged primitive results skip DOM writes. Reads during setup are snapshots; reads in event handlers are current and untracked. Shared derived state belongs in atom.io selectors.
|
|
53
|
+
|
|
54
|
+
## Vite
|
|
55
|
+
|
|
56
|
+
Add @atom.io/spa and atom.io to the application's dependencies. The spa plugin is required: the ordinary TypeScript JSX transform cannot preserve live expressions. It compiles expressions into lazy child computations and property getters; it also preserves spread precedence and live component props.
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import spa from "@atom.io/spa/vite"
|
|
60
|
+
import { defineConfig } from "vite"
|
|
61
|
+
|
|
62
|
+
export default defineConfig({ plugins: [spa()] })
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"compilerOptions": {
|
|
69
|
+
"module": "ESNext",
|
|
70
|
+
"moduleResolution": "bundler",
|
|
71
|
+
"target": "ES2022",
|
|
72
|
+
"jsx": "preserve",
|
|
73
|
+
"jsxImportSource": "@atom.io/spa",
|
|
74
|
+
"strict": true
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```tsx
|
|
81
|
+
import { render } from "@atom.io/spa"
|
|
82
|
+
|
|
83
|
+
import { PointEditor } from "./point.tsx"
|
|
84
|
+
|
|
85
|
+
const root = render(() => <PointEditor />, document.getElementById(`app`)!)
|
|
86
|
+
// Call root.dispose() when the application shell removes this root.
|
|
87
|
+
import.meta.hot?.dispose(root.dispose)
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The development plugin keeps SPA and atom.io outside dependency prebundling so renderer entrypoints, component hooks, and stores share one runtime, including Astro adapter environments. It uses full page reloads. Components and render computations are synchronous. Modern browsers with ES2022 and DOM Range support are the target.
|
|
92
|
+
|
|
93
|
+
## Component API
|
|
94
|
+
|
|
95
|
+
| API | Contract |
|
|
96
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
97
|
+
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
98
|
+
| useValue(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
|
|
99
|
+
| useSetter(token) | Return a stable atom.io writer. |
|
|
100
|
+
| useTimeline(token) | Return an accessor for at, length, undo, redo, clear, and available grouped transaction controls. |
|
|
101
|
+
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
102
|
+
| useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
|
|
103
|
+
| useId() | Allocate an instance-stable ID using the root's prefix. |
|
|
104
|
+
| onCleanup(callback) | Register synchronous teardown with the current owner. |
|
|
105
|
+
| onMount(callback) | Run once after attachment and ref publication; omitted during server rendering. |
|
|
106
|
+
| useStore() | Return the current root's atom.io store without creating a store or subscribing. |
|
|
107
|
+
|
|
108
|
+
Call setup helpers synchronously during component setup or owned mount callbacks. Capture their results for event handlers. Tokens are fixed for an instance; use an application key in a reactive child expression to replace a component when its token changes. Component props stay live when read through the props object; destructuring during setup takes a snapshot.
|
|
109
|
+
|
|
110
|
+
Arrays support keyed components and elements. Reordering preserves instances and nodes; removed ranges release subscriptions, events, refs, and cleanup callbacks. Application keys must be unique among siblings. Explicit keys are compared as strings; unkeyed positions occupy a separate namespace. Unkeyed arrays use positions. A key identifies a row in a reactive child collection; it is not an independent reactive binding.
|
|
111
|
+
|
|
112
|
+
HTML and SVG use native DOM properties and attributes, plus className/htmlFor aliases. Events use onClick/onInput-style names, with Capture suffixes and onDoubleClick support. Styles are CSS strings. Mutable atom values still invalidate their consumers; project primitive fields for precise DOM writes. Refs attach once per element instance.
|
|
113
|
+
|
|
114
|
+
HTML and SVG tags have element-specific attribute, event, and ref types. Event handlers receive native events with currentTarget typed as the attached element; target remains EventTarget because events can bubble from descendants. Ref callbacks receive the element on attachment and null on cleanup. Hyphenated custom tags use generic HTML attributes and HTMLElement refs and event targets. SVG presentation attributes use their literal markup spellings. Shared HTML/SVG tag names use HTML types because JSX cannot infer a namespace from parent elements.
|
|
115
|
+
|
|
116
|
+
## Store access
|
|
117
|
+
|
|
118
|
+
useStore returns the current root's atom.io RootStore directly. It is the same object supplied to render or hydrate, the selected Astro island store, or the implicit atom.io store when no store was supplied. Server rendering exposes the store selected for that render.
|
|
119
|
+
|
|
120
|
+
```tsx
|
|
121
|
+
import type { VNode } from "@atom.io/spa"
|
|
122
|
+
import { useStore } from "@atom.io/spa"
|
|
123
|
+
import { atom } from "atom.io"
|
|
124
|
+
import { getFromStore } from "atom.io/internal"
|
|
125
|
+
|
|
126
|
+
const countAtom = atom<number>({ key: `count`, default: 0 })
|
|
127
|
+
|
|
128
|
+
export function InspectCount(): VNode {
|
|
129
|
+
const store = useStore()
|
|
130
|
+
return (
|
|
131
|
+
<button
|
|
132
|
+
onClick={() => {
|
|
133
|
+
console.log(getFromStore(store, countAtom))
|
|
134
|
+
}}
|
|
135
|
+
>
|
|
136
|
+
Inspect current count
|
|
137
|
+
</button>
|
|
138
|
+
)
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Capture the store during component setup or an owned onMount callback, then pass it to store-aware atom.io operations or integrations. Getting the store creates no subscription. Direct reads such as getFromStore do not participate in SPA's dependency tracking; useValue and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
|
|
144
|
+
|
|
145
|
+
## Families
|
|
146
|
+
|
|
147
|
+
useValue, useSetter, useRef, and useTimeline accept a family token followed by its key. useLoadable accepts a family, key, and optional fallback. Keys retain their declared types, including tuples, numbers, booleans, and null. Members resolve in the component's store, so isolated roots can use the same family tokens independently.
|
|
148
|
+
|
|
149
|
+
```tsx
|
|
150
|
+
import type { VNode } from "@atom.io/spa"
|
|
151
|
+
import { useRef, useSetter, useTimeline, useValue } from "@atom.io/spa"
|
|
152
|
+
import { atomFamily, scopeFamily, timelineFamily } from "atom.io"
|
|
153
|
+
|
|
154
|
+
const countAtoms = atomFamily<number, string>({ key: `count`, default: 0 })
|
|
155
|
+
const buttonAtoms = atomFamily<HTMLButtonElement | null, string>({
|
|
156
|
+
key: `button`,
|
|
157
|
+
default: null,
|
|
158
|
+
})
|
|
159
|
+
const historyTimelines = timelineFamily<string>({
|
|
160
|
+
key: `history`,
|
|
161
|
+
scope: [scopeFamily(countAtoms, { timelineKey: (id) => id })],
|
|
162
|
+
})
|
|
163
|
+
|
|
164
|
+
export function FamilyCounter(props: { id: string }): VNode {
|
|
165
|
+
const count = useValue(countAtoms, props.id)
|
|
166
|
+
const setCount = useSetter(countAtoms, props.id)
|
|
167
|
+
const ref = useRef(buttonAtoms, props.id)
|
|
168
|
+
const history = useTimeline(historyTimelines, props.id)
|
|
169
|
+
return (
|
|
170
|
+
<section>
|
|
171
|
+
<button
|
|
172
|
+
ref={ref}
|
|
173
|
+
onClick={() => {
|
|
174
|
+
setCount((value) => value + 1)
|
|
175
|
+
}}
|
|
176
|
+
>
|
|
177
|
+
{count()}
|
|
178
|
+
</button>
|
|
179
|
+
<button
|
|
180
|
+
disabled={history().at === 0}
|
|
181
|
+
onClick={() => {
|
|
182
|
+
history().undo()
|
|
183
|
+
}}
|
|
184
|
+
>
|
|
185
|
+
Undo
|
|
186
|
+
</button>
|
|
187
|
+
</section>
|
|
188
|
+
)
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
The family and key are captured during setup and stay fixed for that component instance. To switch members, replace the component in a reactive child collection with a new application key. Ref ownership and subscription cleanup follow the member just as they do for individual tokens. useTransaction takes a transaction token; atom.io has no transaction-family token.
|
|
194
|
+
|
|
195
|
+
## Async state
|
|
196
|
+
|
|
197
|
+
```tsx
|
|
198
|
+
import type { VNode } from "@atom.io/spa"
|
|
199
|
+
import { useLoadable, useSetter } from "@atom.io/spa"
|
|
200
|
+
import type { Loadable } from "atom.io"
|
|
201
|
+
import { atom } from "atom.io"
|
|
202
|
+
|
|
203
|
+
const greetingAtom = atom<Loadable<string>, Error>({
|
|
204
|
+
key: `greeting`,
|
|
205
|
+
default: () => Promise.resolve(`Hello`),
|
|
206
|
+
catch: [Error],
|
|
207
|
+
})
|
|
208
|
+
|
|
209
|
+
export function Greeting(): VNode {
|
|
210
|
+
const greeting = useLoadable(greetingAtom, `Loading…`)
|
|
211
|
+
const setGreeting = useSetter(greetingAtom)
|
|
212
|
+
return (
|
|
213
|
+
<section aria-busy={greeting().loading}>
|
|
214
|
+
<p>{greeting().value}</p>
|
|
215
|
+
{greeting().error && <p role="alert">{greeting().error?.message}</p>}
|
|
216
|
+
<button
|
|
217
|
+
onClick={() => {
|
|
218
|
+
setGreeting(Promise.resolve(`Hello again`))
|
|
219
|
+
}}
|
|
220
|
+
>
|
|
221
|
+
Refresh
|
|
222
|
+
</button>
|
|
223
|
+
</section>
|
|
224
|
+
)
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Call useLoadable during setup and read its accessor inside JSX. It also accepts a readable family and fixed key, with an optional third fallback argument. Without a fallback, the accessor returns LOADING until it observes a settled value, then an object containing loading and value. Refreshes retain the last observed value while loading. Null, undefined, and the literal string LOADING are valid settled values.
|
|
230
|
+
|
|
231
|
+
With a fallback, the accessor always returns an object. The fallback is used for initial loading and for errors declared in the token's catch option; handled errors appear separately in error. During a retry after an error, the fallback and error remain visible until a new value settles. An explicitly supplied null or undefined counts as a fallback when the token's value type permits it. Without a fallback, handled errors appear in value. Unexpected errors follow atom.io's normal error handling.
|
|
232
|
+
|
|
233
|
+
Atom.io owns promise settlement and subscriptions. SPA adds no fetching, retries, cancellation, or suspense. Reads during setup are snapshots; calls inside JSX track state. Family keys are fixed for a component instance. Server rendering returns the current loading or settled view immediately and does not await promises.
|
|
234
|
+
|
|
235
|
+
## Rendering and ownership
|
|
236
|
+
|
|
237
|
+
The client exports render and hydrate. Both accept a setup callback, a host Element, and optional store, idPrefix, and onError options, and return dispose and flush methods. Updates coalesce in a microtask; flush drains them synchronously. Dispose is idempotent and removes only owned nodes. Cleanup continues after individual cleanup failures and aggregates errors. A failed computation disposes its root; asynchronous update failures reach onError, while explicit flush failures throw.
|
|
238
|
+
|
|
239
|
+
The separate server entrypoint exports renderToString with the same setup callback and store/ID options. Supply a request-specific store for SSR. Server rendering retains no subscriptions and runs owner cleanup. Hydration reuses matching server nodes and IDs, attaches events, and recreates subscriptions. It requires the same initial state, component structure, and valid HTML on both sides; mismatches throw rather than silently remounting. Use explicit tbody elements in tables. Controlled form properties are applied during hydration.
|
|
240
|
+
|
|
241
|
+
The production build omits development diagnostics and invalid-input checks; the development export condition enables them. Pure render computations must not write state. Promise children, async components, portals, suspense, error boundaries, style objects, and automatic token-as-child bindings are outside this first implementation. Applications handle asynchronous data through atom.io state and synchronous conditional JSX.
|
|
242
|
+
|
|
243
|
+
## Astro
|
|
244
|
+
|
|
245
|
+
The integration transforms .spa.tsx and .spa.jsx files by default, so another JSX renderer can coexist. Configure include to change this filter. Top-level functions containing JSX are branded by the compiler for renderer detection.
|
|
246
|
+
|
|
247
|
+
```ts
|
|
248
|
+
import spa from "@atom.io/spa/astro"
|
|
249
|
+
import { defineConfig } from "astro/config"
|
|
250
|
+
|
|
251
|
+
export default defineConfig({ integrations: [spa()] })
|
|
252
|
+
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Default islands share the normal implicit atom.io store in the browser. Module-scoped tokens, SPA hooks, and ordinary getState/setState calls all address the same graph. SSR shares a separate store within each request; concurrent requests never share values. Definitions imported after an earlier island started are installed into that request's store before the next island prepares. Server reads and writes must use the selected store (through SPA hooks or store-aware atom.io operations); free getState/setState calls still target the process-global implicit store.
|
|
256
|
+
|
|
257
|
+
The integration starts observing browser state before island preparation. Untouched initial islands hydrate their matching server DOM. Once application state changes or a shared client:only island starts, delayed islands mount fresh against the live graph. Astro ClientRouter navigation also makes newly introduced islands mount fresh, preserving existing browser values instead of replaying the incoming server snapshot. Mounted and persisted roots keep their subscriptions and DOM. This decision is conservative across the application: even an unrelated state change disables hydration for later roots. Ordinary defaults must still produce matching initial values; SPA does not serialize stores or repair nondeterministic renders.
|
|
258
|
+
|
|
259
|
+
Set a component's isolate property to true to opt into a private store copied from registered definitions. An optional createStore(props, context) factory supplies a custom RootStore or promise and retains a private preparation lifetime. Custom factories that return the same store are responsible for coordinating their hydration and cleanup. Keep atom definitions at module scope in either mode.
|
|
260
|
+
|
|
261
|
+
An optional prepareStore(store, props, context) callback initializes the selected store and may return a promise. SPA awaits it before component setup on the server and browser. Existing one-argument synchronous factories still work. Use serialized props or an independent transport such as resumability for server-produced initial data. Shared preparation must be safe to call for multiple islands; use context.application.get(key, initialize) to create an application resource once.
|
|
262
|
+
|
|
263
|
+
The context provides element (the browser astro-island host, undefined on the server), signal, and onCleanup for the individual island. Its application provides get, signal, onCleanup, and canResume for the shared lifetime. Browser application resources survive island removal and ClientRouter navigation; they end on a full page exit, with back/forward-cache suspension preserved. SSR application resources end after the response stream finishes or is cancelled. Private islands' application resources end with the island. Use application cleanup and cancellation for shared fetches or resumption scopes; use the outer context for resources owned by one island.
|
|
264
|
+
|
|
265
|
+
Register cleanup as resources are acquired, before awaiting work that might fail. Cleanup callbacks run in reverse order and all run even if one throws; callbacks registered after cancellation run immediately. Cancelling an island stops its wait and prevents a stale mount without cancelling shared application work. Producers must honor their owner's signal to stop I/O. The example below explicitly isolates its per-island data preparation:
|
|
266
|
+
|
|
267
|
+
```tsx
|
|
268
|
+
import type { VNode } from "@atom.io/spa"
|
|
269
|
+
import { useLoadable } from "@atom.io/spa"
|
|
270
|
+
import type { AstroStorePreparation } from "@atom.io/spa/astro"
|
|
271
|
+
import type { Loadable } from "atom.io"
|
|
272
|
+
import { atom } from "atom.io"
|
|
273
|
+
import { disposeFromStore, getFromStore, setIntoStore } from "atom.io/internal"
|
|
274
|
+
|
|
275
|
+
const greetingAtom = atom<Loadable<string>>({
|
|
276
|
+
key: `greeting`,
|
|
277
|
+
default: ``,
|
|
278
|
+
})
|
|
279
|
+
|
|
280
|
+
export default function Greeting(): VNode {
|
|
281
|
+
const greeting = useLoadable(greetingAtom, ``)
|
|
282
|
+
return <p>{greeting().value}</p>
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
const prepare: AstroStorePreparation<{ message: string }> = async (
|
|
286
|
+
store,
|
|
287
|
+
props,
|
|
288
|
+
context,
|
|
289
|
+
) => {
|
|
290
|
+
context.onCleanup(() => {
|
|
291
|
+
disposeFromStore(store, greetingAtom)
|
|
292
|
+
})
|
|
293
|
+
// Use your asynchronous data preparation here. SSR and the browser must
|
|
294
|
+
// observe the same initial value; context.element can provide a DOM sidecar.
|
|
295
|
+
setIntoStore(store, greetingAtom, Promise.resolve(props.message))
|
|
296
|
+
await getFromStore(store, greetingAtom)
|
|
297
|
+
}
|
|
298
|
+
Greeting.isolate = true
|
|
299
|
+
Greeting.prepareStore = prepare
|
|
300
|
+
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePreparation, and Island types are exported from @atom.io/spa/astro. Preparation runs before component setup, so use the context's cleanup registrar there; use SPA's onCleanup inside components. Preparation failures reject the Astro render or hydration operation, retaining cleanup errors alongside the original failure. The factory and preparation callback are awaited per render; component setup and the standalone renderToString API remain synchronous.
|
|
304
|
+
|
|
305
|
+
```tsx
|
|
306
|
+
import type { Child, VNode } from "@atom.io/spa"
|
|
307
|
+
import { onCleanup, useId, useSetter, useValue } from "@atom.io/spa"
|
|
308
|
+
import { atom, Silo } from "atom.io"
|
|
309
|
+
import { IMPLICIT } from "atom.io/internal"
|
|
310
|
+
|
|
311
|
+
const countAtom = atom<number>({ key: `count`, default: 0 })
|
|
312
|
+
export default function Counter(props: {
|
|
313
|
+
initial: number
|
|
314
|
+
children?: Child
|
|
315
|
+
slots?: Record<string, Child>
|
|
316
|
+
}): VNode {
|
|
317
|
+
const count = useValue(countAtom)
|
|
318
|
+
const setCount = useSetter(countAtom)
|
|
319
|
+
const id = useId()
|
|
320
|
+
onCleanup(() => {
|
|
321
|
+
/* Release imperative resources owned by this instance here. */
|
|
322
|
+
})
|
|
323
|
+
return (
|
|
324
|
+
<section aria-labelledby={id}>
|
|
325
|
+
<h2 id={id}>Counter</h2>
|
|
326
|
+
{props.slots?.[`heading`]}
|
|
327
|
+
{props.children}
|
|
328
|
+
<button
|
|
329
|
+
onClick={() => {
|
|
330
|
+
setCount((value) => value + 1)
|
|
331
|
+
}}
|
|
332
|
+
>
|
|
333
|
+
{count()}
|
|
334
|
+
</button>
|
|
335
|
+
</section>
|
|
336
|
+
)
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
// Astro calls this on the server and in the browser with the same serialized props.
|
|
340
|
+
Counter.createStore = (props: { initial: number }) => {
|
|
341
|
+
const silo = new Silo(
|
|
342
|
+
{ name: `counter-island`, lifespan: `ephemeral`, isProduction: true },
|
|
343
|
+
IMPLICIT.STORE,
|
|
344
|
+
)
|
|
345
|
+
silo.setState(countAtom, props.initial)
|
|
346
|
+
return silo.store
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
Astro client:load, client:idle, client:visible, client:media, and client:only use Astro's scheduling. The integration hydrates eligible initial server markup or renders fresh content and releases the root on astro:unmount. Default slot content arrives as children and named content through slots. Reserved astro-slot wrappers contain Astro's already-rendered HTML; never use their innerHTML escape hatch for untrusted strings.
|
|
352
|
+
|
|
353
|
+
Persisted islands receive live prop and slot updates without rerunning component setup or recreating their store. Repeated hydration calls during preparation share one factory and preparation invocation. New client mounts use the latest props and slots; hydration attaches to the original server tree first, then applies any changes received while preparing. The factory receives the initial props and runs only when an island is first mounted; put changing values in props rather than relying on the factory to run again.
|
|
354
|
+
|
|
355
|
+
The checked Astro fixture demonstrates default/named slots and custom independently initialized islands, including client:only. The spa-astro-ssr template demonstrates shared state, server-data resumption, delayed islands, and navigation without losing edits.
|
|
356
|
+
|
|
357
|
+
## Size and verification
|
|
358
|
+
|
|
359
|
+
The build audits every browser export, including the JSX runtime, from the built JavaScript. Atom.io is an external peer in the incremental measurement. Compiler, server, and integration code have separate entrypoints. The report also includes the complete client plus atom.io, the Astro client entrypoint, and the installed Preact version under the same bundling/minification settings. These are full exported surfaces, not equivalent application benchmarks.
|
|
360
|
+
|
|
361
|
+
The hard budget is under 3,400 bytes of ordinary level-9 gzip for the complete client export surface. Tsdown builds the package JavaScript and declarations, with separate production and development outputs that each share their runtime across entrypoints. The size audit then bundles the built exports with esbuild, minifies with Oxc, and measures compression using Node's gzip and Brotli implementations. The spa client measures 3,358 bytes with gzip. Actual application bundles add atom.io and compiler-generated application code.
|
|
362
|
+
|
|
363
|
+
Build output includes the minified audit entrypoint and machine-readable dist/size.json. These audit files are a bundled measurement; use the package exports in applications so the bundler preserves one runtime instance across entrypoints. Source tests exercise development behavior; the production test executes the audited minified artifact. Chromium checks exercise the actual Astro build, island isolation, hydration, keyed identity, focus/selection, SVG namespaces, and teardown. A fresh-cache Astro development check also covers mount hooks, shared state, and ClientRouter navigation.
|
|
364
|
+
|
|
365
|
+
```sh
|
|
366
|
+
pnpm --filter @atom.io/spa build
|
|
367
|
+
pnpm --filter @atom.io/spa cov
|
|
368
|
+
pnpm --filter @atom.io/spa-devtools cov
|
|
369
|
+
pnpm exec turbo run test:breakage:peers --filter=@atom.io/spa --filter=@atom.io/spa-devtools
|
|
370
|
+
pnpm --filter @atom.io/spa test:production
|
|
371
|
+
pnpm --filter @atom.io/spa exec playwright install chromium
|
|
372
|
+
pnpm --filter @atom.io/spa test:browser
|
|
373
|
+
pnpm --filter @atom.io/spa size
|
|
374
|
+
pnpm --filter @atom.io/spa readme:check
|
|
375
|
+
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
## Package checks
|
|
379
|
+
|
|
380
|
+
Breakage exercises the packed package in isolated, locked peer environments, including the coordinated atom.io workspace candidate. Until the first published release, Breakage reports a first-release baseline; these checks establish compatibility with the declared peers rather than a previous spa release. Coverage gates require 100% of statements, branches, functions, and lines across the package source.
|
|
381
|
+
|
|
382
|
+
Tonnage measures combined browser bundles containing SPA and atom.io, with shared modules counted once and unused exports removed. The synchronous recipes include atom creation, useValue, useSetter, and JSX; the client recipe adds render, the hydration recipe adds hydrate, and the Astro recipe adds the browser island adapter. The async recipe uses useLoadable with render and useSetter. The family recipe includes keyed state, refs, and timeline controls, plus atomFamily, timelineFamily, and scopeFamily. SPA declares atom.io as a peer dependency; these consumer-app measurements include it in every total. Application components, Astro scheduling code, CSS, declarations, and source maps are excluded. The full-client gzip budget above remains a separate, SPA-only audit.
|
|
383
|
+
|
|
384
|
+
## Browser serving sizes including atom.io
|
|
385
|
+
|
|
386
|
+
Usage example sizes bundle their entry files and tree-shake unused exports.
|
|
387
|
+
|
|
388
|
+
Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations, source maps, CSS, and other assets are excluded. Imported peer dependencies are bundled unless explicitly external, and shared modules are counted once per bundle.
|
|
389
|
+
|
|
390
|
+
| Recipe | Entry | Minified JS | Gzip JS |
|
|
391
|
+
| -------------------------------- | --------------------------------- | ----------: | -------: |
|
|
392
|
+
| Family app with refs and history | `tonnage-recipes/family-app.ts` | 61,387 B | 18,140 B |
|
|
393
|
+
| Async interactive client app | `tonnage-recipes/async-app.ts` | 39,798 B | 12,327 B |
|
|
394
|
+
| Interactive client app | `tonnage-recipes/client-app.ts` | 39,460 B | 12,178 B |
|
|
395
|
+
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 39,461 B | 12,178 B |
|
|
396
|
+
| Interactive Astro island | `tonnage-recipes/astro-island.ts` | 45,808 B | 14,152 B |
|
|
397
|
+
|
|
398
|
+
Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
|
|
399
|
+
|
|
400
|
+
## License
|
|
401
|
+
|
|
402
|
+
MPL-2.0 or later. See [LICENSE](./LICENSE).
|
package/README.mdx
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import { Tonnage } from "tonnage";
|
|
2
|
+
import config from "./tonnage.config.ts";
|
|
3
|
+
import StoreExample from "./exhibits/store.tsx" with { type: "code" };
|
|
4
|
+
import Families from "./exhibits/families.tsx" with { type: "code" };
|
|
5
|
+
import LoadableExample from "./exhibits/loadable.tsx" with { type: "code" };
|
|
6
|
+
import Point from "./exhibits/point.tsx" with { type: "code" };
|
|
7
|
+
import ViteConfig from "./exhibits/vite.config.ts" with { type: "code" };
|
|
8
|
+
import Main from "./exhibits/main.tsx" with { type: "code" };
|
|
9
|
+
import Types from "./exhibits/tsconfig.json" with { type: "code" };
|
|
10
|
+
import AstroConfig from "./exhibits/astro.config.ts" with { type: "code" };
|
|
11
|
+
import AsyncAstro from "./exhibits/async-astro.spa.tsx" with { type: "code" };
|
|
12
|
+
import Counter from "./exhibits/Counter.spa.tsx" with { type: "code" };
|
|
13
|
+
import Verify from "./exhibits/verify.sh" with { type: "code" };
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<img src="https://raw.githubusercontent.com/jeremybanka/atom.io/main/apps/atom.io.fyi/public/spa/icon-512.png" alt="SPA logo" width="160" height="160" />
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
# SPA
|
|
20
|
+
|
|
21
|
+
An experimental JSX framework whose state engine is atom.io. Components run once per mounted instance. Calls to accessors inside compiled JSX subscribe the affected DOM computations; atom.io updates those computations without rerunning component setup.
|
|
22
|
+
|
|
23
|
+
The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here. It has no independent state primitive, effect API, React hook dispatcher, or compatibility layer.
|
|
24
|
+
|
|
25
|
+
## A point, not two signals
|
|
26
|
+
|
|
27
|
+
<Point />
|
|
28
|
+
|
|
29
|
+
The point accessor returns the current object. Each JSX attribute reads its coordinate when evaluated. Both bindings depend on the point atom, and unchanged primitive results skip DOM writes. Reads during setup are snapshots; reads in event handlers are current and untracked. Shared derived state belongs in atom.io selectors.
|
|
30
|
+
|
|
31
|
+
## Vite
|
|
32
|
+
|
|
33
|
+
Add @atom.io/spa and atom.io to the application's dependencies. The spa plugin is required: the ordinary TypeScript JSX transform cannot preserve live expressions. It compiles expressions into lazy child computations and property getters; it also preserves spread precedence and live component props.
|
|
34
|
+
|
|
35
|
+
<ViteConfig />
|
|
36
|
+
|
|
37
|
+
<Types />
|
|
38
|
+
|
|
39
|
+
<Main />
|
|
40
|
+
|
|
41
|
+
The development plugin keeps SPA and atom.io outside dependency prebundling so renderer entrypoints, component hooks, and stores share one runtime, including Astro adapter environments. It uses full page reloads. Components and render computations are synchronous. Modern browsers with ES2022 and DOM Range support are the target.
|
|
42
|
+
|
|
43
|
+
## Component API
|
|
44
|
+
|
|
45
|
+
| API | Contract |
|
|
46
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
47
|
+
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
48
|
+
| useValue(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
|
|
49
|
+
| useSetter(token) | Return a stable atom.io writer. |
|
|
50
|
+
| useTimeline(token) | Return an accessor for at, length, undo, redo, clear, and available grouped transaction controls. |
|
|
51
|
+
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
52
|
+
| useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
|
|
53
|
+
| useId() | Allocate an instance-stable ID using the root's prefix. |
|
|
54
|
+
| onCleanup(callback) | Register synchronous teardown with the current owner. |
|
|
55
|
+
| onMount(callback) | Run once after attachment and ref publication; omitted during server rendering. |
|
|
56
|
+
| useStore() | Return the current root's atom.io store without creating a store or subscribing. |
|
|
57
|
+
|
|
58
|
+
Call setup helpers synchronously during component setup or owned mount callbacks. Capture their results for event handlers. Tokens are fixed for an instance; use an application key in a reactive child expression to replace a component when its token changes. Component props stay live when read through the props object; destructuring during setup takes a snapshot.
|
|
59
|
+
|
|
60
|
+
Arrays support keyed components and elements. Reordering preserves instances and nodes; removed ranges release subscriptions, events, refs, and cleanup callbacks. Application keys must be unique among siblings. Explicit keys are compared as strings; unkeyed positions occupy a separate namespace. Unkeyed arrays use positions. A key identifies a row in a reactive child collection; it is not an independent reactive binding.
|
|
61
|
+
|
|
62
|
+
HTML and SVG use native DOM properties and attributes, plus className/htmlFor aliases. Events use onClick/onInput-style names, with Capture suffixes and onDoubleClick support. Styles are CSS strings. Mutable atom values still invalidate their consumers; project primitive fields for precise DOM writes. Refs attach once per element instance.
|
|
63
|
+
|
|
64
|
+
HTML and SVG tags have element-specific attribute, event, and ref types. Event handlers receive native events with currentTarget typed as the attached element; target remains EventTarget because events can bubble from descendants. Ref callbacks receive the element on attachment and null on cleanup. Hyphenated custom tags use generic HTML attributes and HTMLElement refs and event targets. SVG presentation attributes use their literal markup spellings. Shared HTML/SVG tag names use HTML types because JSX cannot infer a namespace from parent elements.
|
|
65
|
+
|
|
66
|
+
## Store access
|
|
67
|
+
|
|
68
|
+
useStore returns the current root's atom.io RootStore directly. It is the same object supplied to render or hydrate, the selected Astro island store, or the implicit atom.io store when no store was supplied. Server rendering exposes the store selected for that render.
|
|
69
|
+
|
|
70
|
+
<StoreExample />
|
|
71
|
+
|
|
72
|
+
Capture the store during component setup or an owned onMount callback, then pass it to store-aware atom.io operations or integrations. Getting the store creates no subscription. Direct reads such as getFromStore do not participate in SPA's dependency tracking; useValue and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
|
|
73
|
+
|
|
74
|
+
## Families
|
|
75
|
+
|
|
76
|
+
useValue, useSetter, useRef, and useTimeline accept a family token followed by its key. useLoadable accepts a family, key, and optional fallback. Keys retain their declared types, including tuples, numbers, booleans, and null. Members resolve in the component's store, so isolated roots can use the same family tokens independently.
|
|
77
|
+
|
|
78
|
+
<Families />
|
|
79
|
+
|
|
80
|
+
The family and key are captured during setup and stay fixed for that component instance. To switch members, replace the component in a reactive child collection with a new application key. Ref ownership and subscription cleanup follow the member just as they do for individual tokens. useTransaction takes a transaction token; atom.io has no transaction-family token.
|
|
81
|
+
|
|
82
|
+
## Async state
|
|
83
|
+
|
|
84
|
+
<LoadableExample />
|
|
85
|
+
|
|
86
|
+
Call useLoadable during setup and read its accessor inside JSX. It also accepts a readable family and fixed key, with an optional third fallback argument. Without a fallback, the accessor returns LOADING until it observes a settled value, then an object containing loading and value. Refreshes retain the last observed value while loading. Null, undefined, and the literal string LOADING are valid settled values.
|
|
87
|
+
|
|
88
|
+
With a fallback, the accessor always returns an object. The fallback is used for initial loading and for errors declared in the token's catch option; handled errors appear separately in error. During a retry after an error, the fallback and error remain visible until a new value settles. An explicitly supplied null or undefined counts as a fallback when the token's value type permits it. Without a fallback, handled errors appear in value. Unexpected errors follow atom.io's normal error handling.
|
|
89
|
+
|
|
90
|
+
Atom.io owns promise settlement and subscriptions. SPA adds no fetching, retries, cancellation, or suspense. Reads during setup are snapshots; calls inside JSX track state. Family keys are fixed for a component instance. Server rendering returns the current loading or settled view immediately and does not await promises.
|
|
91
|
+
|
|
92
|
+
## Rendering and ownership
|
|
93
|
+
|
|
94
|
+
The client exports render and hydrate. Both accept a setup callback, a host Element, and optional store, idPrefix, and onError options, and return dispose and flush methods. Updates coalesce in a microtask; flush drains them synchronously. Dispose is idempotent and removes only owned nodes. Cleanup continues after individual cleanup failures and aggregates errors. A failed computation disposes its root; asynchronous update failures reach onError, while explicit flush failures throw.
|
|
95
|
+
|
|
96
|
+
The separate server entrypoint exports renderToString with the same setup callback and store/ID options. Supply a request-specific store for SSR. Server rendering retains no subscriptions and runs owner cleanup. Hydration reuses matching server nodes and IDs, attaches events, and recreates subscriptions. It requires the same initial state, component structure, and valid HTML on both sides; mismatches throw rather than silently remounting. Use explicit tbody elements in tables. Controlled form properties are applied during hydration.
|
|
97
|
+
|
|
98
|
+
The production build omits development diagnostics and invalid-input checks; the development export condition enables them. Pure render computations must not write state. Promise children, async components, portals, suspense, error boundaries, style objects, and automatic token-as-child bindings are outside this first implementation. Applications handle asynchronous data through atom.io state and synchronous conditional JSX.
|
|
99
|
+
|
|
100
|
+
## Astro
|
|
101
|
+
|
|
102
|
+
The integration transforms .spa.tsx and .spa.jsx files by default, so another JSX renderer can coexist. Configure include to change this filter. Top-level functions containing JSX are branded by the compiler for renderer detection.
|
|
103
|
+
|
|
104
|
+
<AstroConfig />
|
|
105
|
+
|
|
106
|
+
Default islands share the normal implicit atom.io store in the browser. Module-scoped tokens, SPA hooks, and ordinary getState/setState calls all address the same graph. SSR shares a separate store within each request; concurrent requests never share values. Definitions imported after an earlier island started are installed into that request's store before the next island prepares. Server reads and writes must use the selected store (through SPA hooks or store-aware atom.io operations); free getState/setState calls still target the process-global implicit store.
|
|
107
|
+
|
|
108
|
+
The integration starts observing browser state before island preparation. Untouched initial islands hydrate their matching server DOM. Once application state changes or a shared client:only island starts, delayed islands mount fresh against the live graph. Astro ClientRouter navigation also makes newly introduced islands mount fresh, preserving existing browser values instead of replaying the incoming server snapshot. Mounted and persisted roots keep their subscriptions and DOM. This decision is conservative across the application: even an unrelated state change disables hydration for later roots. Ordinary defaults must still produce matching initial values; SPA does not serialize stores or repair nondeterministic renders.
|
|
109
|
+
|
|
110
|
+
Set a component's isolate property to true to opt into a private store copied from registered definitions. An optional createStore(props, context) factory supplies a custom RootStore or promise and retains a private preparation lifetime. Custom factories that return the same store are responsible for coordinating their hydration and cleanup. Keep atom definitions at module scope in either mode.
|
|
111
|
+
|
|
112
|
+
An optional prepareStore(store, props, context) callback initializes the selected store and may return a promise. SPA awaits it before component setup on the server and browser. Existing one-argument synchronous factories still work. Use serialized props or an independent transport such as resumability for server-produced initial data. Shared preparation must be safe to call for multiple islands; use context.application.get(key, initialize) to create an application resource once.
|
|
113
|
+
|
|
114
|
+
The context provides element (the browser astro-island host, undefined on the server), signal, and onCleanup for the individual island. Its application provides get, signal, onCleanup, and canResume for the shared lifetime. Browser application resources survive island removal and ClientRouter navigation; they end on a full page exit, with back/forward-cache suspension preserved. SSR application resources end after the response stream finishes or is cancelled. Private islands' application resources end with the island. Use application cleanup and cancellation for shared fetches or resumption scopes; use the outer context for resources owned by one island.
|
|
115
|
+
|
|
116
|
+
Register cleanup as resources are acquired, before awaiting work that might fail. Cleanup callbacks run in reverse order and all run even if one throws; callbacks registered after cancellation run immediately. Cancelling an island stops its wait and prevents a stale mount without cancelling shared application work. Producers must honor their owner's signal to stop I/O. The example below explicitly isolates its per-island data preparation:
|
|
117
|
+
|
|
118
|
+
<AsyncAstro />
|
|
119
|
+
|
|
120
|
+
AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePreparation, and Island types are exported from @atom.io/spa/astro. Preparation runs before component setup, so use the context's cleanup registrar there; use SPA's onCleanup inside components. Preparation failures reject the Astro render or hydration operation, retaining cleanup errors alongside the original failure. The factory and preparation callback are awaited per render; component setup and the standalone renderToString API remain synchronous.
|
|
121
|
+
|
|
122
|
+
<Counter />
|
|
123
|
+
|
|
124
|
+
Astro client:load, client:idle, client:visible, client:media, and client:only use Astro's scheduling. The integration hydrates eligible initial server markup or renders fresh content and releases the root on astro:unmount. Default slot content arrives as children and named content through slots. Reserved astro-slot wrappers contain Astro's already-rendered HTML; never use their innerHTML escape hatch for untrusted strings.
|
|
125
|
+
|
|
126
|
+
Persisted islands receive live prop and slot updates without rerunning component setup or recreating their store. Repeated hydration calls during preparation share one factory and preparation invocation. New client mounts use the latest props and slots; hydration attaches to the original server tree first, then applies any changes received while preparing. The factory receives the initial props and runs only when an island is first mounted; put changing values in props rather than relying on the factory to run again.
|
|
127
|
+
|
|
128
|
+
The checked Astro fixture demonstrates default/named slots and custom independently initialized islands, including client:only. The spa-astro-ssr template demonstrates shared state, server-data resumption, delayed islands, and navigation without losing edits.
|
|
129
|
+
|
|
130
|
+
## Size and verification
|
|
131
|
+
|
|
132
|
+
The build audits every browser export, including the JSX runtime, from the built JavaScript. Atom.io is an external peer in the incremental measurement. Compiler, server, and integration code have separate entrypoints. The report also includes the complete client plus atom.io, the Astro client entrypoint, and the installed Preact version under the same bundling/minification settings. These are full exported surfaces, not equivalent application benchmarks.
|
|
133
|
+
|
|
134
|
+
The hard budget is under 3,400 bytes of ordinary level-9 gzip for the complete client export surface. Tsdown builds the package JavaScript and declarations, with separate production and development outputs that each share their runtime across entrypoints. The size audit then bundles the built exports with esbuild, minifies with Oxc, and measures compression using Node's gzip and Brotli implementations. The spa client measures 3,358 bytes with gzip. Actual application bundles add atom.io and compiler-generated application code.
|
|
135
|
+
|
|
136
|
+
Build output includes the minified audit entrypoint and machine-readable dist/size.json. These audit files are a bundled measurement; use the package exports in applications so the bundler preserves one runtime instance across entrypoints. Source tests exercise development behavior; the production test executes the audited minified artifact. Chromium checks exercise the actual Astro build, island isolation, hydration, keyed identity, focus/selection, SVG namespaces, and teardown. A fresh-cache Astro development check also covers mount hooks, shared state, and ClientRouter navigation.
|
|
137
|
+
|
|
138
|
+
<Verify />
|
|
139
|
+
|
|
140
|
+
## Package checks
|
|
141
|
+
|
|
142
|
+
Breakage exercises the packed package in isolated, locked peer environments, including the coordinated atom.io workspace candidate. Until the first published release, Breakage reports a first-release baseline; these checks establish compatibility with the declared peers rather than a previous spa release. Coverage gates require 100% of statements, branches, functions, and lines across the package source.
|
|
143
|
+
|
|
144
|
+
Tonnage measures combined browser bundles containing SPA and atom.io, with shared modules counted once and unused exports removed. The synchronous recipes include atom creation, useValue, useSetter, and JSX; the client recipe adds render, the hydration recipe adds hydrate, and the Astro recipe adds the browser island adapter. The async recipe uses useLoadable with render and useSetter. The family recipe includes keyed state, refs, and timeline controls, plus atomFamily, timelineFamily, and scopeFamily. SPA declares atom.io as a peer dependency; these consumer-app measurements include it in every total. Application components, Astro scheduling code, CSS, declarations, and source maps are excluded. The full-client gzip budget above remains a separate, SPA-only audit.
|
|
145
|
+
|
|
146
|
+
<Tonnage config={config} />
|
|
147
|
+
|
|
148
|
+
## License
|
|
149
|
+
|
|
150
|
+
MPL-2.0 or later. See [LICENSE](./LICENSE).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { t as AstroApplicationContext } from "./astro-shared-DkZaqX7L.js";
|
|
2
|
+
type Lifetime = {
|
|
3
|
+
signal: AbortSignal;
|
|
4
|
+
onCleanup(cleanup: () => void): () => void;
|
|
5
|
+
dispose(): void;
|
|
6
|
+
cancelled: Promise<undefined>;
|
|
7
|
+
};
|
|
8
|
+
type Application = Lifetime & AstroApplicationContext & {
|
|
9
|
+
canResume: boolean;
|
|
10
|
+
};
|
|
11
|
+
declare function applicationContext(): Application;
|
|
12
|
+
/** Called by the integration's early page script, before island preparation. */
|
|
13
|
+
export declare function browserApplication(document: Document): ReturnType<typeof applicationContext>;
|
|
14
|
+
export {};
|
|
15
|
+
//# sourceMappingURL=astro-application.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"astro-application.d.ts","names":[],"sources":["../src/astro-context.ts","../src/astro-application.ts"],"mappings":";KAKK;EACJ,QAAQ;EACR,UAAU;EACV;EACA,WAAW;;KAyCA,cAAc,WACzB;EAA4B;;iBACb,sBAAsB;;wBCzCtB,mBACf,UAAU,WACR,kBAAkB"}
|