@atom.io/spa 0.0.2 → 0.0.4
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/README.md +144 -47
- package/README.mdx +37 -11
- package/dist/astro-application.d.ts +1 -1
- package/dist/astro-application.js +2 -2
- package/dist/astro-application.js.map +1 -1
- package/dist/astro-client.d.ts +1 -1
- package/dist/astro-client.js +4 -4
- package/dist/astro-client.js.map +1 -1
- package/dist/{astro-shared-DyzbUi6c.d.ts → astro-shared-CYSRrRr8.d.ts} +2 -2
- package/dist/{astro-shared-DyzbUi6c.d.ts.map → astro-shared-CYSRrRr8.d.ts.map} +1 -1
- package/dist/astro.d.ts +1 -1
- package/dist/capabilities-BkQ2i0vV.js +63 -0
- package/dist/capabilities-BkQ2i0vV.js.map +1 -0
- package/dist/{capabilities-yC9TsHDI.d.ts → capabilities-D3HObAIy.d.ts} +66 -11
- package/dist/capabilities-D3HObAIy.d.ts.map +1 -0
- package/dist/client.min.js +1 -1
- package/dist/{capabilities-BuZUQpiD.js → core-Bl1Ec1hY.js} +42 -79
- package/dist/core-Bl1Ec1hY.js.map +1 -0
- package/dist/development/astro-application.js +2 -2
- package/dist/development/astro-application.js.map +1 -1
- package/dist/development/astro-client.js +4 -4
- package/dist/development/astro-client.js.map +1 -1
- package/dist/development/capabilities-BkQ2i0vV.js +63 -0
- package/dist/development/capabilities-BkQ2i0vV.js.map +1 -0
- package/dist/development/{capabilities-DhOJmeoJ.js → core-DZFaOyTO.js} +42 -79
- package/dist/development/core-DZFaOyTO.js.map +1 -0
- package/dist/development/{dom-BKc6V_Kz.js → dom-Dwa2SFTn.js} +16 -7
- package/dist/development/dom-Dwa2SFTn.js.map +1 -0
- package/dist/development/index.js +4 -4
- package/dist/development/konva.js +25 -3
- package/dist/development/konva.js.map +1 -1
- package/dist/development/motion.js +392 -8
- package/dist/development/motion.js.map +1 -1
- package/dist/development/renderer.js +23 -10
- package/dist/development/renderer.js.map +1 -1
- package/dist/development/server.js +2 -1
- package/dist/development/server.js.map +1 -1
- package/dist/development/{src-Dh-d6w4y.js → src-BUtG4BgX.js} +4 -4
- package/dist/development/src-BUtG4BgX.js.map +1 -0
- package/dist/development/three.js +24 -10
- package/dist/development/three.js.map +1 -1
- package/dist/{dom-B2rm8o2L.js → dom-Cfj3GtQK.js} +16 -7
- package/dist/dom-Cfj3GtQK.js.map +1 -0
- package/dist/{index-BdwxmSKg.d.ts → index-YRZ79lN5.d.ts} +3 -3
- package/dist/{index-BdwxmSKg.d.ts.map → index-YRZ79lN5.d.ts.map} +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.js +4 -4
- package/dist/{jsx-runtime-CZU7F8Qz.d.ts → jsx-runtime-Q-UBV97Y.d.ts} +2 -2
- package/dist/{jsx-runtime-CZU7F8Qz.d.ts.map → jsx-runtime-Q-UBV97Y.d.ts.map} +1 -1
- package/dist/jsx-runtime.d.ts +1 -1
- package/dist/konva.d.ts +3 -3
- package/dist/konva.d.ts.map +1 -1
- package/dist/konva.js +25 -3
- package/dist/konva.js.map +1 -1
- package/dist/motion.d.ts +2 -1
- package/dist/motion.d.ts.map +1 -1
- package/dist/motion.js +392 -8
- package/dist/motion.js.map +1 -1
- package/dist/renderer.d.ts +3 -3
- package/dist/renderer.d.ts.map +1 -1
- package/dist/renderer.js +23 -10
- package/dist/renderer.js.map +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/server.js +2 -1
- package/dist/server.js.map +1 -1
- package/dist/size.json +12 -12
- package/dist/{src-BZxX4xbU.js → src-DvkUMuNW.js} +4 -4
- package/dist/src-DvkUMuNW.js.map +1 -0
- package/dist/three.d.ts +3 -3
- package/dist/three.d.ts.map +1 -1
- package/dist/three.js +24 -10
- package/dist/three.js.map +1 -1
- package/package.json +9 -7
- package/src/astro-application.ts +2 -2
- package/src/astro-client.ts +3 -3
- package/src/capabilities.ts +21 -2
- package/src/core.ts +66 -41
- package/src/dom.ts +35 -4
- package/src/index.ts +2 -2
- package/src/konva.ts +41 -14
- package/src/motion-tween.ts +106 -0
- package/src/motion.ts +122 -9
- package/src/presence.ts +324 -0
- package/src/renderer.ts +51 -14
- package/src/three-events.ts +13 -1
- package/src/three.ts +38 -15
- package/src/use-loadable.ts +3 -3
- package/dist/capabilities-BuZUQpiD.js.map +0 -1
- package/dist/capabilities-yC9TsHDI.d.ts.map +0 -1
- package/dist/development/capabilities-DhOJmeoJ.js.map +0 -1
- package/dist/development/dom-BKc6V_Kz.js.map +0 -1
- package/dist/development/src-Dh-d6w4y.js.map +0 -1
- package/dist/dom-B2rm8o2L.js.map +0 -1
- package/dist/src-BZxX4xbU.js.map +0 -1
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, serve
|
|
|
10
10
|
|
|
11
11
|
```tsx
|
|
12
12
|
import type { VNode } from "@atom.io/spa"
|
|
13
|
-
import { useId, useRef, useSetter
|
|
13
|
+
import { useGetter, useId, useRef, useSetter } from "@atom.io/spa"
|
|
14
14
|
import { atom } from "atom.io"
|
|
15
15
|
|
|
16
16
|
const pointAtom = atom<{ x: number; y: number }>({
|
|
@@ -23,7 +23,7 @@ const circleAtom = atom<SVGCircleElement | null>({
|
|
|
23
23
|
})
|
|
24
24
|
|
|
25
25
|
export function PointEditor(): VNode {
|
|
26
|
-
const
|
|
26
|
+
const getPoint = useGetter(pointAtom)
|
|
27
27
|
const setPoint = useSetter(pointAtom)
|
|
28
28
|
const circle = useRef(circleAtom)
|
|
29
29
|
const id = useId()
|
|
@@ -31,10 +31,10 @@ export function PointEditor(): VNode {
|
|
|
31
31
|
<section aria-labelledby={id}>
|
|
32
32
|
<h2 id={id}>Point</h2>
|
|
33
33
|
<svg viewBox="0 0 100 100">
|
|
34
|
-
<circle ref={circle} cx={
|
|
34
|
+
<circle ref={circle} cx={getPoint().x} cy={getPoint().y} r="3" />
|
|
35
35
|
</svg>
|
|
36
36
|
<output>
|
|
37
|
-
{
|
|
37
|
+
{getPoint().x}, {getPoint().y}
|
|
38
38
|
</output>
|
|
39
39
|
<button
|
|
40
40
|
onClick={() => {
|
|
@@ -49,7 +49,7 @@ export function PointEditor(): VNode {
|
|
|
49
49
|
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
The
|
|
52
|
+
Name the getter and setter after the atom: pointAtom uses getPoint and setPoint. The getPoint getter 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
53
|
|
|
54
54
|
## Vite
|
|
55
55
|
|
|
@@ -95,9 +95,9 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
95
95
|
| API | Contract |
|
|
96
96
|
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
97
97
|
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
98
|
-
|
|
|
98
|
+
| useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
|
|
99
99
|
| useSetter(token) | Return a stable atom.io writer. |
|
|
100
|
-
| useTimeline(token) | Return
|
|
100
|
+
| useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
|
|
101
101
|
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
102
102
|
| useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
|
|
103
103
|
| useId() | Allocate an instance-stable ID using the root's prefix. |
|
|
@@ -107,6 +107,55 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
107
107
|
|
|
108
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
109
|
|
|
110
|
+
useTimeline returns a TimelineControls object whose methods can be destructured during setup. getCursor and getLength read the current cursor position and recorded checkpoint count; calls inside JSX subscribe the computation, while calls during setup or in event handlers are untracked. undo, redo, and clear are stable commands. history.getTransaction() is a tracked reader that returns an object with optional undo and redo callbacks for the adjacent transaction groups. At a cursor between transactions, both callbacks may be present and target different groups. A missing callback means no transaction group is available in that direction; the reader returns an empty object when neither is available. Calling a returned callback travels its captured group across participating timelines where it remains at the relevant history head, leaving diverged timelines unchanged. Use history.getTransaction().undo?.() or history.getTransaction().redo?.() to retrieve and invoke the current action together.
|
|
111
|
+
|
|
112
|
+
```tsx
|
|
113
|
+
import type { VNode } from "@atom.io/spa"
|
|
114
|
+
import { useGetter, useTimeline, useTransaction } from "@atom.io/spa"
|
|
115
|
+
import { atom, timeline, transaction } from "atom.io"
|
|
116
|
+
|
|
117
|
+
const countAtom = atom<number>({ key: `count`, default: 0 })
|
|
118
|
+
const historyTimeline = timeline({ key: `history`, scope: [countAtom] })
|
|
119
|
+
const incrementTransaction = transaction<() => void>({
|
|
120
|
+
key: `increment`,
|
|
121
|
+
do: ({ get, set }) => {
|
|
122
|
+
set(countAtom, get(countAtom) + 1)
|
|
123
|
+
},
|
|
124
|
+
})
|
|
125
|
+
|
|
126
|
+
export function TimelineExample(): VNode {
|
|
127
|
+
const getCount = useGetter(countAtom)
|
|
128
|
+
const increment = useTransaction(incrementTransaction)
|
|
129
|
+
const history = useTimeline(historyTimeline)
|
|
130
|
+
return (
|
|
131
|
+
<section>
|
|
132
|
+
<output>
|
|
133
|
+
Count: {getCount()} (history: {history.getCursor()}/{history.getLength()}
|
|
134
|
+
)
|
|
135
|
+
</output>
|
|
136
|
+
<button onClick={increment}>Increment</button>
|
|
137
|
+
<button
|
|
138
|
+
disabled={history.getTransaction().undo === undefined}
|
|
139
|
+
onClick={() => {
|
|
140
|
+
history.getTransaction().undo?.()
|
|
141
|
+
}}
|
|
142
|
+
>
|
|
143
|
+
Undo transaction
|
|
144
|
+
</button>
|
|
145
|
+
<button
|
|
146
|
+
disabled={history.getTransaction().redo === undefined}
|
|
147
|
+
onClick={() => {
|
|
148
|
+
history.getTransaction().redo?.()
|
|
149
|
+
}}
|
|
150
|
+
>
|
|
151
|
+
Redo transaction
|
|
152
|
+
</button>
|
|
153
|
+
</section>
|
|
154
|
+
)
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
|
|
110
159
|
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
160
|
|
|
112
161
|
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.
|
|
@@ -140,15 +189,15 @@ export function InspectCount(): VNode {
|
|
|
140
189
|
|
|
141
190
|
```
|
|
142
191
|
|
|
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;
|
|
192
|
+
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; useGetter and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
|
|
144
193
|
|
|
145
194
|
## Families
|
|
146
195
|
|
|
147
|
-
|
|
196
|
+
useGetter, 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
197
|
|
|
149
198
|
```tsx
|
|
150
199
|
import type { VNode } from "@atom.io/spa"
|
|
151
|
-
import { useRef, useSetter, useTimeline
|
|
200
|
+
import { useGetter, useRef, useSetter, useTimeline } from "@atom.io/spa"
|
|
152
201
|
import { atomFamily, scopeFamily, timelineFamily } from "atom.io"
|
|
153
202
|
|
|
154
203
|
const countAtoms = atomFamily<number, string>({ key: `count`, default: 0 })
|
|
@@ -162,7 +211,7 @@ const historyTimelines = timelineFamily<string>({
|
|
|
162
211
|
})
|
|
163
212
|
|
|
164
213
|
export function FamilyCounter(props: { id: string }): VNode {
|
|
165
|
-
const
|
|
214
|
+
const getCount = useGetter(countAtoms, props.id)
|
|
166
215
|
const setCount = useSetter(countAtoms, props.id)
|
|
167
216
|
const ref = useRef(buttonAtoms, props.id)
|
|
168
217
|
const history = useTimeline(historyTimelines, props.id)
|
|
@@ -174,14 +223,9 @@ export function FamilyCounter(props: { id: string }): VNode {
|
|
|
174
223
|
setCount((value) => value + 1)
|
|
175
224
|
}}
|
|
176
225
|
>
|
|
177
|
-
{
|
|
226
|
+
{getCount()}
|
|
178
227
|
</button>
|
|
179
|
-
<button
|
|
180
|
-
disabled={history().at === 0}
|
|
181
|
-
onClick={() => {
|
|
182
|
-
history().undo()
|
|
183
|
-
}}
|
|
184
|
-
>
|
|
228
|
+
<button disabled={history.getCursor() === 0} onClick={history.undo}>
|
|
185
229
|
Undo
|
|
186
230
|
</button>
|
|
187
231
|
</section>
|
|
@@ -304,7 +348,7 @@ AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePrepara
|
|
|
304
348
|
|
|
305
349
|
```tsx
|
|
306
350
|
import type { Child, VNode } from "@atom.io/spa"
|
|
307
|
-
import { onCleanup, useId, useSetter
|
|
351
|
+
import { onCleanup, useGetter, useId, useSetter } from "@atom.io/spa"
|
|
308
352
|
import { atom, Silo } from "atom.io"
|
|
309
353
|
import { IMPLICIT } from "atom.io/internal"
|
|
310
354
|
|
|
@@ -314,7 +358,7 @@ export default function Counter(props: {
|
|
|
314
358
|
children?: Child
|
|
315
359
|
slots?: Record<string, Child>
|
|
316
360
|
}): VNode {
|
|
317
|
-
const
|
|
361
|
+
const getCount = useGetter(countAtom)
|
|
318
362
|
const setCount = useSetter(countAtom)
|
|
319
363
|
const id = useId()
|
|
320
364
|
onCleanup(() => {
|
|
@@ -330,7 +374,7 @@ export default function Counter(props: {
|
|
|
330
374
|
setCount((value) => value + 1)
|
|
331
375
|
}}
|
|
332
376
|
>
|
|
333
|
-
{
|
|
377
|
+
{getCount()}
|
|
334
378
|
</button>
|
|
335
379
|
</section>
|
|
336
380
|
)
|
|
@@ -358,7 +402,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
|
|
|
358
402
|
|
|
359
403
|
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
404
|
|
|
361
|
-
The hard budget is under
|
|
405
|
+
The hard budget is under 4,100 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 complete client export surface measures approximately 4.0 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
|
|
362
406
|
|
|
363
407
|
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
408
|
|
|
@@ -380,7 +424,7 @@ pnpm --filter @atom.io/spa readme:check
|
|
|
380
424
|
|
|
381
425
|
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.
|
|
382
426
|
|
|
383
|
-
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,
|
|
427
|
+
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, useGetter, 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.
|
|
384
428
|
|
|
385
429
|
## Browser serving sizes including atom.io
|
|
386
430
|
|
|
@@ -390,11 +434,11 @@ Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations,
|
|
|
390
434
|
|
|
391
435
|
| Recipe | Entry | Minified JS | Gzip JS |
|
|
392
436
|
| -------------------------------- | --------------------------------- | ----------: | -------: |
|
|
393
|
-
| Family app with refs and history | `tonnage-recipes/family-app.ts` |
|
|
394
|
-
| Async interactive client app | `tonnage-recipes/async-app.ts` |
|
|
395
|
-
| Interactive client app | `tonnage-recipes/client-app.ts` |
|
|
396
|
-
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` |
|
|
397
|
-
| Interactive Astro island | `tonnage-recipes/astro-island.ts` |
|
|
437
|
+
| Family app with refs and history | `tonnage-recipes/family-app.ts` | 63,696 B | 18,887 B |
|
|
438
|
+
| Async interactive client app | `tonnage-recipes/async-app.ts` | 42,121 B | 13,142 B |
|
|
439
|
+
| Interactive client app | `tonnage-recipes/client-app.ts` | 41,784 B | 12,981 B |
|
|
440
|
+
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 41,785 B | 12,981 B |
|
|
441
|
+
| Interactive Astro island | `tonnage-recipes/astro-island.ts` | 48,153 B | 14,977 B |
|
|
398
442
|
|
|
399
443
|
Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
|
|
400
444
|
|
|
@@ -412,7 +456,7 @@ Import Stage, Layer, Group, Rect, Circle, Ellipse, Line, Text, Image, Path, Star
|
|
|
412
456
|
|
|
413
457
|
```tsx
|
|
414
458
|
import type { VNode } from "@atom.io/spa"
|
|
415
|
-
import {
|
|
459
|
+
import { useGetter, useSetter } from "@atom.io/spa"
|
|
416
460
|
import { Circle, Layer, Stage } from "@atom.io/spa/konva"
|
|
417
461
|
import { atom } from "atom.io"
|
|
418
462
|
|
|
@@ -421,14 +465,14 @@ const pointAtom = atom<{ x: number; y: number }>({
|
|
|
421
465
|
default: { x: 100, y: 100 },
|
|
422
466
|
})
|
|
423
467
|
export function Editor(): VNode {
|
|
424
|
-
const
|
|
468
|
+
const getPoint = useGetter(pointAtom)
|
|
425
469
|
const setPoint = useSetter(pointAtom)
|
|
426
470
|
return (
|
|
427
471
|
<Stage width={800} height={600}>
|
|
428
472
|
<Layer>
|
|
429
473
|
<Circle
|
|
430
|
-
x={
|
|
431
|
-
y={
|
|
474
|
+
x={getPoint().x}
|
|
475
|
+
y={getPoint().y}
|
|
432
476
|
radius={25}
|
|
433
477
|
fill="coral"
|
|
434
478
|
draggable
|
|
@@ -451,7 +495,7 @@ Import Canvas, Group, Mesh, PerspectiveCamera, AmbientLight, DirectionalLight, B
|
|
|
451
495
|
|
|
452
496
|
```tsx
|
|
453
497
|
import type { VNode } from "@atom.io/spa"
|
|
454
|
-
import {
|
|
498
|
+
import { useGetter } from "@atom.io/spa"
|
|
455
499
|
import {
|
|
456
500
|
AmbientLight,
|
|
457
501
|
BoxGeometry,
|
|
@@ -464,14 +508,14 @@ import { atom } from "atom.io"
|
|
|
464
508
|
|
|
465
509
|
const colorAtom = atom<string>({ key: `color`, default: `coral` })
|
|
466
510
|
export function Scene(): VNode {
|
|
467
|
-
const
|
|
511
|
+
const getColor = useGetter(colorAtom)
|
|
468
512
|
return (
|
|
469
513
|
<Canvas width={800} height={600}>
|
|
470
514
|
<AmbientLight intensity={0.5} />
|
|
471
515
|
<DirectionalLight position={[3, 3, 3]} />
|
|
472
516
|
<Mesh rotation={[0.3, 0.5, 0]}>
|
|
473
517
|
<BoxGeometry args={[1, 1, 1]} />
|
|
474
|
-
<MeshStandardMaterial color={
|
|
518
|
+
<MeshStandardMaterial color={getColor()} />
|
|
475
519
|
</Mesh>
|
|
476
520
|
</Canvas>
|
|
477
521
|
)
|
|
@@ -509,22 +553,22 @@ render(() => <MotionPanel />, document.getElementById(`app`)!, {
|
|
|
509
553
|
|
|
510
554
|
```
|
|
511
555
|
|
|
512
|
-
Use motion:initial, motion:animate, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
|
|
556
|
+
Use motion:initial, motion:animate, motion:exit, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
|
|
513
557
|
|
|
514
558
|
```tsx
|
|
515
559
|
import type { VNode } from "@atom.io/spa"
|
|
516
|
-
import {
|
|
560
|
+
import { useGetter, useSetter } from "@atom.io/spa"
|
|
517
561
|
import { atom } from "atom.io"
|
|
518
562
|
|
|
519
563
|
const targetXAtom = atom<number>({ key: `targetX`, default: 0 })
|
|
520
564
|
export function MotionPanel(): VNode {
|
|
521
|
-
const
|
|
522
|
-
const
|
|
565
|
+
const getTargetX = useGetter(targetXAtom)
|
|
566
|
+
const setTargetX = useSetter(targetXAtom)
|
|
523
567
|
return (
|
|
524
568
|
<section>
|
|
525
569
|
<button
|
|
526
570
|
onClick={() => {
|
|
527
|
-
|
|
571
|
+
setTargetX((value) => (value === 0 ? 200 : 0))
|
|
528
572
|
}}
|
|
529
573
|
>
|
|
530
574
|
Move
|
|
@@ -532,7 +576,7 @@ export function MotionPanel(): VNode {
|
|
|
532
576
|
<sliding-panel
|
|
533
577
|
style="display: block; width: 120px; padding: 16px; background: coral"
|
|
534
578
|
motion:initial={{ opacity: 0, x: -100 }}
|
|
535
|
-
motion:animate={{ opacity: 1, x:
|
|
579
|
+
motion:animate={{ opacity: 1, x: getTargetX() }}
|
|
536
580
|
motion:transition={{ type: `spring`, stiffness: 180, damping: 22 }}
|
|
537
581
|
motion:whileHover={{ scale: 1.05 }}
|
|
538
582
|
motion:whileTap={{ scale: 0.95 }}
|
|
@@ -545,7 +589,7 @@ export function MotionPanel(): VNode {
|
|
|
545
589
|
|
|
546
590
|
```
|
|
547
591
|
|
|
548
|
-
Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation,
|
|
592
|
+
Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation, and variant propagation are outside this initial API.
|
|
549
593
|
|
|
550
594
|
Motion respects the user's reduced-motion preference by default, including changes while mounted. The capability's reducedMotion option can be user, always, or never. Owner cleanup stops animations and releases effects, gesture handlers, and media-query listeners. Removing the capability properties releases that node's binding. Avoid assigning the same property through both native attributes/styles and motion targets: motion owns the properties it animates.
|
|
551
595
|
|
|
@@ -553,7 +597,7 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
|
|
|
553
597
|
|
|
554
598
|
```tsx
|
|
555
599
|
import type { VNode } from "@atom.io/spa"
|
|
556
|
-
import {
|
|
600
|
+
import { useGetter } from "@atom.io/spa"
|
|
557
601
|
import {
|
|
558
602
|
BoxGeometry,
|
|
559
603
|
Canvas,
|
|
@@ -568,12 +612,12 @@ const targetXAtom = atom<number>({
|
|
|
568
612
|
})
|
|
569
613
|
// Mount under a root with capabilities: [motionCapability()].
|
|
570
614
|
export function SpringCube(): VNode {
|
|
571
|
-
const
|
|
615
|
+
const getTargetX = useGetter(targetXAtom)
|
|
572
616
|
return (
|
|
573
617
|
<Canvas>
|
|
574
618
|
<Mesh
|
|
575
619
|
motion:initial={{ position: [-1, 0, 0], scale: 0 }}
|
|
576
|
-
motion:animate={{ position: [
|
|
620
|
+
motion:animate={{ position: [getTargetX(), 0, 0], scale: 1 }}
|
|
577
621
|
motion:transition={{ type: `spring`, stiffness: 180, damping: 22 }}
|
|
578
622
|
motion:whileHover={{ scale: 1.2 }}
|
|
579
623
|
motion:whileTap={{ scale: 0.8 }}
|
|
@@ -590,8 +634,61 @@ export function SpringCube(): VNode {
|
|
|
590
634
|
|
|
591
635
|
```
|
|
592
636
|
|
|
593
|
-
When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine
|
|
637
|
+
When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine or retention coordinator. Presence hooks add approximately 300 bytes of gzip to the released 3.7 kB client surface; the optional Motion entrypoint owns the retention machinery. The full client budget is 4,100 bytes.
|
|
638
|
+
|
|
639
|
+
### Exit animations and re-entry
|
|
640
|
+
|
|
641
|
+
Declare motion:exit on an element, custom tag, Konva node, or Three.js scene node. Conditional or keyed removal starts that target from its current Motion values. No presence wrapper is required. Register motionCapability as above.
|
|
642
|
+
|
|
643
|
+
```tsx
|
|
644
|
+
import type { VNode } from "@atom.io/spa"
|
|
645
|
+
import { useGetter, useSetter } from "@atom.io/spa"
|
|
646
|
+
import { atom } from "atom.io"
|
|
647
|
+
|
|
648
|
+
const visibleAtom = atom<boolean>({ key: `visible`, default: true })
|
|
649
|
+
export function DismissiblePanel(): VNode {
|
|
650
|
+
const getVisible = useGetter(visibleAtom)
|
|
651
|
+
const setVisible = useSetter(visibleAtom)
|
|
652
|
+
return (
|
|
653
|
+
<section>
|
|
654
|
+
<button
|
|
655
|
+
onClick={() => {
|
|
656
|
+
setVisible((value) => !value)
|
|
657
|
+
}}
|
|
658
|
+
>
|
|
659
|
+
Toggle panel
|
|
660
|
+
</button>
|
|
661
|
+
{getVisible() && (
|
|
662
|
+
<sliding-panel
|
|
663
|
+
key="panel"
|
|
664
|
+
motion:initial={{ opacity: 0, y: 12 }}
|
|
665
|
+
motion:animate={{ opacity: 1, y: 0 }}
|
|
666
|
+
motion:exit={{ opacity: 0, y: -12 }}
|
|
667
|
+
motion:transition={{ type: `spring`, stiffness: 180, damping: 22 }}
|
|
668
|
+
>
|
|
669
|
+
The same instance returns if toggled before its exit completes.
|
|
670
|
+
</sliding-panel>
|
|
671
|
+
)}
|
|
672
|
+
</section>
|
|
673
|
+
)
|
|
674
|
+
}
|
|
675
|
+
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
In the repository, the runnable source lives in [examples/motion](https://github.com/jeremybanka/atom.io/tree/main/packages/spa/examples/motion), including its standalone Vite entrypoint and visual recorder. Run the package’s example:motion script to start it locally.
|
|
679
|
+
|
|
680
|
+
Try the [motion sandbox](https://atom.io.fyi/spa-motion-lab) to interrupt a 2s tween at adjustable speeds, inspect rendered positions and velocities, scrub the captured sequence, or export PNG and JSON evidence.
|
|
681
|
+
|
|
682
|
+
SPA retains the entire removed subtree until all its exit targets finish, including independently exiting descendants adopted by an exiting ancestor. Native nodes, scene attachments, refs, subscriptions, renderers, geometries, and materials remain owned until final disposal. When keyed Mesh resources are replaced, the incoming geometry and material attach immediately; outgoing resources remain owned through their exits without occupying those attachment slots. Removing a resource without a replacement keeps it attached until its exit finishes. Replacing resources does not render a crossfade between them. Siblings keep their instances; retained ranges keep their previous position. A target without an exit is removed immediately unless another exit retains its enclosing subtree.
|
|
683
|
+
|
|
684
|
+
Returning the same key and component or element type before disposal cancels the exit and resumes the original instance against the latest props and state. Setup, mount callbacks, and refs do not run again. Motion keeps the current animated values and spring velocity. Moving numeric tweens also preserve velocity, including matching CSS units and scene tuple components: the first 20% of the new duration brakes to rest, then the remaining 80% returns smoothly to the latest animate target. Interrupted tweens begin immediately and use this return curve instead of restarting their authored delay or easing. Fresh tweens keep their authored timing, and zero-duration or reduced-motion updates remain immediate. Discrete and nonnumeric styles retain Motion’s native interpolation. Reusing a key with an incompatible type creates a separate instance; the old generation finishes independently. Keys have meaning within their original child collection. Reordering or reparenting into another collection does not transfer ownership.
|
|
685
|
+
|
|
686
|
+
During exit, reactive attributes, child reconciliation, user events, gestures, and user onSceneFrame/onFrame callbacks pause. Renderer frame infrastructure continues drawing animated scenes. DOM nodes become inert, aria-hidden, and unavailable to pointer input; owned focus is blurred and is not automatically restored on return. Konva nodes stop listening and cancel both pending and active drags, including descendant drags when an ancestor exits. Re-entry restores the authored draggable settings; a fresh press is required to start dragging again. Three.js objects leave picking and release active pointer interaction state. Re-entry restores their prior interaction settings and handlers.
|
|
687
|
+
|
|
688
|
+
Exit props and transition settings are read at logical removal; later state changes do not retarget an exiting subtree. Exits use the same transition as animate, defaulting to a spring. Explicit durations, visualDuration, and delays must be finite and nonnegative; velocity must be finite, bounce must be in the range \[0, 1), and stiffness, damping, mass, restDelta, and restSpeed must be finite and positive so exits can settle. Reduced motion skips retention; enabling it during an exit completes that exit. Server rendering omits capability attributes and never starts exits; hydration attaches them for later removals.
|
|
689
|
+
|
|
690
|
+
Root disposal and fatal errors bypass exits, stop active work, and release resources immediately. Stale animation completions cannot dispose a revived instance. This API covers exit retention and cancellation; layout/pop-layout animation, variants, presence wrappers, and automatic reparenting remain outside its scope.
|
|
594
691
|
|
|
595
692
|
### Renderer extensions
|
|
596
693
|
|
|
597
|
-
The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
|
|
694
|
+
The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. Its children callback receives the parent, all owned children including retained exits, and the active children in that collection. Single resource slots can use active children for replacement while retaining ownership of outgoing resources. Children of an exiting parent keep their attachments until disposal. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
|
package/README.mdx
CHANGED
|
@@ -2,6 +2,7 @@ import { Tonnage } from "tonnage";
|
|
|
2
2
|
import config from "./tonnage.config.ts";
|
|
3
3
|
import StoreExample from "./exhibits/store.tsx" with { type: "code" };
|
|
4
4
|
import Families from "./exhibits/families.tsx" with { type: "code" };
|
|
5
|
+
import TimelineExample from "./exhibits/timeline.tsx" with { type: "code" };
|
|
5
6
|
import LoadableExample from "./exhibits/loadable.tsx" with { type: "code" };
|
|
6
7
|
import Point from "./exhibits/point.tsx" with { type: "code" };
|
|
7
8
|
import ViteConfig from "./exhibits/vite.config.ts" with { type: "code" };
|
|
@@ -15,6 +16,7 @@ import KonvaExample from "./exhibits/konva.spa.tsx" with { type: "code" };
|
|
|
15
16
|
import ThreeExample from "./exhibits/three.spa.tsx" with { type: "code" };
|
|
16
17
|
import MotionPanel from "./exhibits/motion.spa.tsx" with { type: "code" };
|
|
17
18
|
import MotionMain from "./exhibits/motion-main.tsx" with { type: "code" };
|
|
19
|
+
import MotionExit from "./exhibits/motion-exit.spa.tsx" with { type: "code" };
|
|
18
20
|
import MotionThree from "./exhibits/motion-three.spa.tsx" with { type: "code" };
|
|
19
21
|
|
|
20
22
|
<p align="center">
|
|
@@ -31,7 +33,7 @@ The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, serve
|
|
|
31
33
|
|
|
32
34
|
<Point />
|
|
33
35
|
|
|
34
|
-
The
|
|
36
|
+
Name the getter and setter after the atom: pointAtom uses getPoint and setPoint. The getPoint getter 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.
|
|
35
37
|
|
|
36
38
|
## Vite
|
|
37
39
|
|
|
@@ -50,9 +52,9 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
50
52
|
| API | Contract |
|
|
51
53
|
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
52
54
|
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
53
|
-
|
|
|
55
|
+
| useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
|
|
54
56
|
| useSetter(token) | Return a stable atom.io writer. |
|
|
55
|
-
| useTimeline(token) | Return
|
|
57
|
+
| useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
|
|
56
58
|
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
57
59
|
| useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
|
|
58
60
|
| useId() | Allocate an instance-stable ID using the root's prefix. |
|
|
@@ -62,6 +64,10 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
62
64
|
|
|
63
65
|
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.
|
|
64
66
|
|
|
67
|
+
useTimeline returns a TimelineControls object whose methods can be destructured during setup. getCursor and getLength read the current cursor position and recorded checkpoint count; calls inside JSX subscribe the computation, while calls during setup or in event handlers are untracked. undo, redo, and clear are stable commands. history.getTransaction() is a tracked reader that returns an object with optional undo and redo callbacks for the adjacent transaction groups. At a cursor between transactions, both callbacks may be present and target different groups. A missing callback means no transaction group is available in that direction; the reader returns an empty object when neither is available. Calling a returned callback travels its captured group across participating timelines where it remains at the relevant history head, leaving diverged timelines unchanged. Use history.getTransaction().undo?.() or history.getTransaction().redo?.() to retrieve and invoke the current action together.
|
|
68
|
+
|
|
69
|
+
<TimelineExample />
|
|
70
|
+
|
|
65
71
|
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.
|
|
66
72
|
|
|
67
73
|
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.
|
|
@@ -74,11 +80,11 @@ useStore returns the current root's atom.io RootStore directly. It is the same o
|
|
|
74
80
|
|
|
75
81
|
<StoreExample />
|
|
76
82
|
|
|
77
|
-
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;
|
|
83
|
+
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; useGetter and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
|
|
78
84
|
|
|
79
85
|
## Families
|
|
80
86
|
|
|
81
|
-
|
|
87
|
+
useGetter, 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.
|
|
82
88
|
|
|
83
89
|
<Families />
|
|
84
90
|
|
|
@@ -136,7 +142,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
|
|
|
136
142
|
|
|
137
143
|
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.
|
|
138
144
|
|
|
139
|
-
The hard budget is under
|
|
145
|
+
The hard budget is under 4,100 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 complete client export surface measures approximately 4.0 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
|
|
140
146
|
|
|
141
147
|
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.
|
|
142
148
|
|
|
@@ -146,7 +152,7 @@ Build output includes the minified audit entrypoint and machine-readable dist/si
|
|
|
146
152
|
|
|
147
153
|
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.
|
|
148
154
|
|
|
149
|
-
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,
|
|
155
|
+
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, useGetter, 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.
|
|
150
156
|
|
|
151
157
|
<Tonnage config={config} />
|
|
152
158
|
|
|
@@ -192,11 +198,11 @@ Import motionCapability from @atom.io/spa/motion and register it explicitly in r
|
|
|
192
198
|
|
|
193
199
|
<MotionMain />
|
|
194
200
|
|
|
195
|
-
Use motion:initial, motion:animate, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
|
|
201
|
+
Use motion:initial, motion:animate, motion:exit, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
|
|
196
202
|
|
|
197
203
|
<MotionPanel />
|
|
198
204
|
|
|
199
|
-
Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation,
|
|
205
|
+
Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation, and variant propagation are outside this initial API.
|
|
200
206
|
|
|
201
207
|
Motion respects the user's reduced-motion preference by default, including changes while mounted. The capability's reducedMotion option can be user, always, or never. Owner cleanup stops animations and releases effects, gesture handlers, and media-query listeners. Removing the capability properties releases that node's binding. Avoid assigning the same property through both native attributes/styles and motion targets: motion owns the properties it animates.
|
|
202
208
|
|
|
@@ -204,8 +210,28 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
|
|
|
204
210
|
|
|
205
211
|
<MotionThree />
|
|
206
212
|
|
|
207
|
-
When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine
|
|
213
|
+
When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine or retention coordinator. Presence hooks add approximately 300 bytes of gzip to the released 3.7 kB client surface; the optional Motion entrypoint owns the retention machinery. The full client budget is 4,100 bytes.
|
|
214
|
+
|
|
215
|
+
### Exit animations and re-entry
|
|
216
|
+
|
|
217
|
+
Declare motion:exit on an element, custom tag, Konva node, or Three.js scene node. Conditional or keyed removal starts that target from its current Motion values. No presence wrapper is required. Register motionCapability as above.
|
|
218
|
+
|
|
219
|
+
<MotionExit />
|
|
220
|
+
|
|
221
|
+
In the repository, the runnable source lives in [examples/motion](https://github.com/jeremybanka/atom.io/tree/main/packages/spa/examples/motion), including its standalone Vite entrypoint and visual recorder. Run the package’s example:motion script to start it locally.
|
|
222
|
+
|
|
223
|
+
Try the [motion sandbox](https://atom.io.fyi/spa-motion-lab) to interrupt a 2s tween at adjustable speeds, inspect rendered positions and velocities, scrub the captured sequence, or export PNG and JSON evidence.
|
|
224
|
+
|
|
225
|
+
SPA retains the entire removed subtree until all its exit targets finish, including independently exiting descendants adopted by an exiting ancestor. Native nodes, scene attachments, refs, subscriptions, renderers, geometries, and materials remain owned until final disposal. When keyed Mesh resources are replaced, the incoming geometry and material attach immediately; outgoing resources remain owned through their exits without occupying those attachment slots. Removing a resource without a replacement keeps it attached until its exit finishes. Replacing resources does not render a crossfade between them. Siblings keep their instances; retained ranges keep their previous position. A target without an exit is removed immediately unless another exit retains its enclosing subtree.
|
|
226
|
+
|
|
227
|
+
Returning the same key and component or element type before disposal cancels the exit and resumes the original instance against the latest props and state. Setup, mount callbacks, and refs do not run again. Motion keeps the current animated values and spring velocity. Moving numeric tweens also preserve velocity, including matching CSS units and scene tuple components: the first 20% of the new duration brakes to rest, then the remaining 80% returns smoothly to the latest animate target. Interrupted tweens begin immediately and use this return curve instead of restarting their authored delay or easing. Fresh tweens keep their authored timing, and zero-duration or reduced-motion updates remain immediate. Discrete and nonnumeric styles retain Motion’s native interpolation. Reusing a key with an incompatible type creates a separate instance; the old generation finishes independently. Keys have meaning within their original child collection. Reordering or reparenting into another collection does not transfer ownership.
|
|
228
|
+
|
|
229
|
+
During exit, reactive attributes, child reconciliation, user events, gestures, and user onSceneFrame/onFrame callbacks pause. Renderer frame infrastructure continues drawing animated scenes. DOM nodes become inert, aria-hidden, and unavailable to pointer input; owned focus is blurred and is not automatically restored on return. Konva nodes stop listening and cancel both pending and active drags, including descendant drags when an ancestor exits. Re-entry restores the authored draggable settings; a fresh press is required to start dragging again. Three.js objects leave picking and release active pointer interaction state. Re-entry restores their prior interaction settings and handlers.
|
|
230
|
+
|
|
231
|
+
Exit props and transition settings are read at logical removal; later state changes do not retarget an exiting subtree. Exits use the same transition as animate, defaulting to a spring. Explicit durations, visualDuration, and delays must be finite and nonnegative; velocity must be finite, bounce must be in the range [0, 1), and stiffness, damping, mass, restDelta, and restSpeed must be finite and positive so exits can settle. Reduced motion skips retention; enabling it during an exit completes that exit. Server rendering omits capability attributes and never starts exits; hydration attaches them for later removals.
|
|
232
|
+
|
|
233
|
+
Root disposal and fatal errors bypass exits, stop active work, and release resources immediately. Stale animation completions cannot dispose a revived instance. This API covers exit retention and cancellation; layout/pop-layout animation, variants, presence wrappers, and automatic reparenting remain outside its scope.
|
|
208
234
|
|
|
209
235
|
### Renderer extensions
|
|
210
236
|
|
|
211
|
-
The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
|
|
237
|
+
The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. Its children callback receives the parent, all owned children including retained exits, and the active children in that collection. Single resource slots can use active children for replacement while retaining ownership of outgoing resources. Children of an exiting parent keep their attachments until disposal. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { t as applicationContext } from "./astro-context-OdlexHR4.js";
|
|
2
|
-
import { IMPLICIT, withdraw } from "atom.io/internal";
|
|
2
|
+
import { IMPLICIT, subscribeToStateSubject, withdraw } from "atom.io/internal";
|
|
3
3
|
// src/astro-application.ts
|
|
4
4
|
const applications = /* @__PURE__ */ new WeakMap();
|
|
5
5
|
/** Called by the integration's early page script, before island preparation. */
|
|
@@ -21,7 +21,7 @@ function browserApplication(document) {
|
|
|
21
21
|
if (store.valueMap.has(token.key)) changed();
|
|
22
22
|
subscriptions.get(token.key)?.();
|
|
23
23
|
const state = withdraw(store, token);
|
|
24
|
-
subscriptions.set(token.key, state
|
|
24
|
+
subscriptions.set(token.key, subscribeToStateSubject(state, `spa:bootstrap`, changed));
|
|
25
25
|
};
|
|
26
26
|
for (const state of [
|
|
27
27
|
...store.atoms.values(),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"astro-application.js","names":[],"sources":["../src/astro-application.ts"],"sourcesContent":["import type { ReadableToken } from \"atom.io\"\nimport { IMPLICIT, withdraw } from \"atom.io/internal\"\n\nimport { applicationContext } from \"./astro-context.ts\"\n\nconst applications = new WeakMap<\n\tDocument,\n\tReturnType<typeof applicationContext>\n>()\n\n/** Called by the integration's early page script, before island preparation. */\nexport function browserApplication(\n\tdocument: Document,\n): ReturnType<typeof applicationContext> {\n\tlet application = applications.get(document)\n\tif (application) return application\n\tapplication = applicationContext()\n\tconst app = application\n\tconst store = IMPLICIT.STORE\n\tconst originalDefault = store.runDefault\n\tapplications.set(document, app)\n\tconst changed = () => {\n\t\tapp.canResume = false\n\t}\n\tconst internal = (key: string) => key.startsWith(`🔍 spa islands`)\n\tconst subscriptions = new Map<string, () => void>()\n\tconst watch = (token: ReadableToken<unknown, any, any>) => {\n\t\tif (internal(token.key)) return\n\t\tif (store.valueMap.has(token.key)) changed()\n\t\tsubscriptions.get(token.key)?.()\n\t\tconst state = withdraw(store, token)\n\t\tsubscriptions.set(\n\t\t\ttoken.key,\n\t\t\
|
|
1
|
+
{"version":3,"file":"astro-application.js","names":[],"sources":["../src/astro-application.ts"],"sourcesContent":["import type { ReadableToken } from \"atom.io\"\nimport { IMPLICIT, subscribeToStateSubject, withdraw } from \"atom.io/internal\"\n\nimport { applicationContext } from \"./astro-context.ts\"\n\nconst applications = new WeakMap<\n\tDocument,\n\tReturnType<typeof applicationContext>\n>()\n\n/** Called by the integration's early page script, before island preparation. */\nexport function browserApplication(\n\tdocument: Document,\n): ReturnType<typeof applicationContext> {\n\tlet application = applications.get(document)\n\tif (application) return application\n\tapplication = applicationContext()\n\tconst app = application\n\tconst store = IMPLICIT.STORE\n\tconst originalDefault = store.runDefault\n\tapplications.set(document, app)\n\tconst changed = () => {\n\t\tapp.canResume = false\n\t}\n\tconst internal = (key: string) => key.startsWith(`🔍 spa islands`)\n\tconst subscriptions = new Map<string, () => void>()\n\tconst watch = (token: ReadableToken<unknown, any, any>) => {\n\t\tif (internal(token.key)) return\n\t\tif (store.valueMap.has(token.key)) changed()\n\t\tsubscriptions.get(token.key)?.()\n\t\tconst state = withdraw(store, token)\n\t\tsubscriptions.set(\n\t\t\ttoken.key,\n\t\t\tsubscribeToStateSubject(state, `spa:bootstrap`, changed),\n\t\t)\n\t}\n\tfor (const state of [\n\t\t...store.atoms.values(),\n\t\t...store.readonlySelectors.values(),\n\t\t...store.writableSelectors.values(),\n\t])\n\t\twatch(state)\n\tconst removed = (token: ReadableToken<unknown, any, any>) => {\n\t\tif (!internal(token.key)) {\n\t\t\tchanged()\n\t\t\tsubscriptions.get(token.key)?.()\n\t\t\tsubscriptions.delete(token.key)\n\t\t}\n\t}\n\tconst events = [\n\t\tstore.on.atomCreation.subscribe(`spa:bootstrap`, watch),\n\t\tstore.on.selectorCreation.subscribe(`spa:bootstrap`, watch),\n\t\tstore.on.atomDisposal.subscribe(`spa:bootstrap`, removed),\n\t\tstore.on.selectorDisposal.subscribe(`spa:bootstrap`, removed),\n\t\tstore.on.transactionCommit.subscribe(`spa:bootstrap`, changed),\n\t]\n\tdocument.addEventListener(`astro:before-swap`, changed)\n\tconst pagehide = (event: PageTransitionEvent) => {\n\t\tif (!event.persisted) app.dispose()\n\t}\n\tdocument.defaultView?.addEventListener(`pagehide`, pagehide)\n\tapp.onCleanup(() => {\n\t\tfor (const unsubscribe of subscriptions.values()) unsubscribe()\n\t\tfor (const unsubscribe of events) unsubscribe()\n\t\tdocument.removeEventListener(`astro:before-swap`, changed)\n\t\tdocument.defaultView?.removeEventListener(`pagehide`, pagehide)\n\t\tstore.runDefault = originalDefault\n\t\tapplications.delete(document)\n\t})\n\treturn app\n}\n"],"mappings":";;;AAKA,MAAM,+BAAe,IAAI,QAGvB;;AAGF,SAAgB,mBACf,UACwC;CACxC,IAAI,cAAc,aAAa,IAAI,QAAQ;CAC3C,IAAI,aAAa,OAAO;CACxB,cAAc,mBAAmB;CACjC,MAAM,MAAM;CACZ,MAAM,QAAQ,SAAS;CACvB,MAAM,kBAAkB,MAAM;CAC9B,aAAa,IAAI,UAAU,GAAG;CAC9B,MAAM,gBAAgB;EACrB,IAAI,YAAY;CACjB;CACA,MAAM,YAAY,QAAgB,IAAI,WAAW,gBAAgB;CACjE,MAAM,gCAAgB,IAAI,IAAwB;CAClD,MAAM,SAAS,UAA4C;EAC1D,IAAI,SAAS,MAAM,GAAG,GAAG;EACzB,IAAI,MAAM,SAAS,IAAI,MAAM,GAAG,GAAG,QAAQ;EAC3C,cAAc,IAAI,MAAM,GAAG,CAAC,GAAG;EAC/B,MAAM,QAAQ,SAAS,OAAO,KAAK;EACnC,cAAc,IACb,MAAM,KACN,wBAAwB,OAAO,iBAAiB,OAAO,CACxD;CACD;CACA,KAAK,MAAM,SAAS;EACnB,GAAG,MAAM,MAAM,OAAO;EACtB,GAAG,MAAM,kBAAkB,OAAO;EAClC,GAAG,MAAM,kBAAkB,OAAO;CACnC,GACC,MAAM,KAAK;CACZ,MAAM,WAAW,UAA4C;EAC5D,IAAI,CAAC,SAAS,MAAM,GAAG,GAAG;GACzB,QAAQ;GACR,cAAc,IAAI,MAAM,GAAG,CAAC,GAAG;GAC/B,cAAc,OAAO,MAAM,GAAG;EAC/B;CACD;CACA,MAAM,SAAS;EACd,MAAM,GAAG,aAAa,UAAU,iBAAiB,KAAK;EACtD,MAAM,GAAG,iBAAiB,UAAU,iBAAiB,KAAK;EAC1D,MAAM,GAAG,aAAa,UAAU,iBAAiB,OAAO;EACxD,MAAM,GAAG,iBAAiB,UAAU,iBAAiB,OAAO;EAC5D,MAAM,GAAG,kBAAkB,UAAU,iBAAiB,OAAO;CAC9D;CACA,SAAS,iBAAiB,qBAAqB,OAAO;CACtD,MAAM,YAAY,UAA+B;EAChD,IAAI,CAAC,MAAM,WAAW,IAAI,QAAQ;CACnC;CACA,SAAS,aAAa,iBAAiB,YAAY,QAAQ;CAC3D,IAAI,gBAAgB;EACnB,KAAK,MAAM,eAAe,cAAc,OAAO,GAAG,YAAY;EAC9D,KAAK,MAAM,eAAe,QAAQ,YAAY;EAC9C,SAAS,oBAAoB,qBAAqB,OAAO;EACzD,SAAS,aAAa,oBAAoB,YAAY,QAAQ;EAC9D,MAAM,aAAa;EACnB,aAAa,OAAO,QAAQ;CAC7B,CAAC;CACD,OAAO;AACR"}
|
package/dist/astro-client.d.ts
CHANGED