@atom.io/spa 0.0.6 → 0.0.8
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 +282 -10
- package/README.mdx +65 -5
- package/dist/astro-application.d.ts +1 -1
- package/dist/astro-client.d.ts +1 -1
- package/dist/astro-client.js +2 -2
- package/dist/astro-resumability-client.d.ts +1 -1
- package/dist/astro-server.js +1 -1
- package/dist/{astro-shared-B9wvGIkk.d.ts → astro-shared-DZp1x8RQ.d.ts} +2 -2
- package/dist/{astro-shared-B9wvGIkk.d.ts.map → astro-shared-DZp1x8RQ.d.ts.map} +1 -1
- package/dist/astro.d.ts +1 -1
- package/dist/{capabilities-_zOwNJ-2.d.ts → capabilities-DNcnGRv_.d.ts} +7 -3
- package/dist/capabilities-DNcnGRv_.d.ts.map +1 -0
- package/dist/capabilities-nOIitQ-_.js.map +1 -1
- package/dist/client.min.js +1 -1
- package/dist/{core-DjFJ0aIJ.js → core-B4rJ0xdc.js} +22 -12
- package/dist/core-B4rJ0xdc.js.map +1 -0
- package/dist/development/astro-client.js +2 -2
- package/dist/development/astro-server.js +1 -1
- package/dist/development/capabilities-nOIitQ-_.js.map +1 -1
- package/dist/development/{core-DxPiKryn.js → core-BHA7I1nf.js} +24 -14
- package/dist/development/core-BHA7I1nf.js.map +1 -0
- package/dist/development/{dom-BWy4dDss.js → dom-DQ0M3rLL.js} +2 -2
- package/dist/development/{dom-BWy4dDss.js.map → dom-DQ0M3rLL.js.map} +1 -1
- package/dist/development/floating.js +1 -1
- package/dist/development/index.js +4 -4
- package/dist/development/konva.js +1 -1
- package/dist/development/motion.js +414 -25
- package/dist/development/motion.js.map +1 -1
- package/dist/development/renderer.js +1 -1
- package/dist/development/{server-renderer-C7lGVhpo.js → server-renderer-DCLoMdOX.js} +2 -2
- package/dist/development/{server-renderer-C7lGVhpo.js.map → server-renderer-DCLoMdOX.js.map} +1 -1
- package/dist/development/server.js +1 -1
- package/dist/development/{src-WSHJxR9b.js → src-DoQgCX-O.js} +2 -2
- package/dist/development/{src-WSHJxR9b.js.map → src-DoQgCX-O.js.map} +1 -1
- package/dist/development/three.js +76 -23
- package/dist/development/three.js.map +1 -1
- package/dist/{dom-BrPrxO97.js → dom-D8g3roX9.js} +2 -2
- package/dist/{dom-BrPrxO97.js.map → dom-D8g3roX9.js.map} +1 -1
- package/dist/floating.d.ts +1 -1
- package/dist/floating.js +1 -1
- package/dist/{index-BFIjI7gF.d.ts → index-BFnXIfOj.d.ts} +3 -3
- package/dist/{index-BFIjI7gF.d.ts.map → index-BFnXIfOj.d.ts.map} +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.js +4 -4
- package/dist/{jsx-runtime-BhiCZOYZ.d.ts → jsx-runtime-DQnpyT_g.d.ts} +2 -2
- package/dist/{jsx-runtime-BhiCZOYZ.d.ts.map → jsx-runtime-DQnpyT_g.d.ts.map} +1 -1
- package/dist/jsx-runtime.d.ts +1 -1
- package/dist/konva.d.ts +3 -3
- package/dist/konva.js +1 -1
- package/dist/motion.d.ts +39 -16
- package/dist/motion.d.ts.map +1 -1
- package/dist/motion.js +414 -25
- package/dist/motion.js.map +1 -1
- package/dist/renderer.d.ts +1 -1
- package/dist/renderer.js +1 -1
- package/dist/{server-renderer-D-uRg04V.js → server-renderer-D0rsFL_-.js} +2 -2
- package/dist/{server-renderer-D-uRg04V.js.map → server-renderer-D0rsFL_-.js.map} +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/server.js +1 -1
- package/dist/size.json +12 -12
- package/dist/{src-DWIqXCiz.js → src-Bme1kz2b.js} +2 -2
- package/dist/{src-DWIqXCiz.js.map → src-Bme1kz2b.js.map} +1 -1
- package/dist/three.d.ts +27 -8
- package/dist/three.d.ts.map +1 -1
- package/dist/three.js +76 -23
- package/dist/three.js.map +1 -1
- package/package.json +6 -5
- package/src/capabilities.ts +2 -0
- package/src/core.ts +26 -12
- package/src/index.ts +1 -0
- package/src/motion-layout.ts +363 -0
- package/src/motion-transition.ts +92 -0
- package/src/motion-tween.ts +19 -2
- package/src/motion.ts +207 -77
- package/src/three.ts +134 -39
- package/dist/capabilities-_zOwNJ-2.d.ts.map +0 -1
- package/dist/core-DjFJ0aIJ.js.map +0 -1
- package/dist/development/core-DxPiKryn.js.map +0 -1
package/README.md
CHANGED
|
@@ -168,6 +168,7 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
168
168
|
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
169
169
|
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
170
170
|
| useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
|
|
171
|
+
| useDisposal() | Return atom.io state disposal bound to the current root's store. |
|
|
171
172
|
| useSetter(token) | Return a stable atom.io writer. |
|
|
172
173
|
| useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
|
|
173
174
|
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
@@ -261,7 +262,7 @@ export function InspectCount(): SpaElement {
|
|
|
261
262
|
|
|
262
263
|
```
|
|
263
264
|
|
|
264
|
-
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.
|
|
265
|
+
For family-member disposal, useDisposal() captures this store and returns a bound disposal command; see [ambient UI state](#ambient-ui-state-and-ownership). Capture the store during component setup or an owned onMount callback, then pass it to other 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.
|
|
265
266
|
|
|
266
267
|
## Families
|
|
267
268
|
|
|
@@ -308,6 +309,127 @@ export function FamilyCounter(props: { id: string }): SpaElement {
|
|
|
308
309
|
|
|
309
310
|
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.
|
|
310
311
|
|
|
312
|
+
### Ambient UI state and ownership
|
|
313
|
+
|
|
314
|
+
Ambient state is useful for ephemeral UI flags that several components need to read or change, such as whether a popover is open. Define the family at module scope and give each popover an application identity. Its trigger and panel can bind to the same boolean without passing the value and setter through their parent.
|
|
315
|
+
|
|
316
|
+
This exhibit gives each toolbar its own formatting and keyboard-shortcut help popovers. Hiding formatting help removes its keyed instance and disposes its visibility state. Showing it again starts closed; the shortcuts popover and other toolbars keep their state:
|
|
317
|
+
|
|
318
|
+
```tsx
|
|
319
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
320
|
+
import {
|
|
321
|
+
onCleanup,
|
|
322
|
+
useDisposal,
|
|
323
|
+
useGetter,
|
|
324
|
+
useId,
|
|
325
|
+
useSetter,
|
|
326
|
+
} from "@atom.io/spa"
|
|
327
|
+
import { atomFamily } from "atom.io"
|
|
328
|
+
|
|
329
|
+
type HelpTopic = `formatting` | `shortcuts`
|
|
330
|
+
type PopoverIdentity = readonly [toolbar: string, topic: HelpTopic]
|
|
331
|
+
|
|
332
|
+
export const popoverOpenAtoms = atomFamily<boolean, PopoverIdentity>({
|
|
333
|
+
key: `popoverOpen`,
|
|
334
|
+
default: false,
|
|
335
|
+
})
|
|
336
|
+
export const formattingHelpVisibleAtoms = atomFamily<boolean, string>({
|
|
337
|
+
key: `formattingHelpVisible`,
|
|
338
|
+
default: true,
|
|
339
|
+
})
|
|
340
|
+
|
|
341
|
+
function HelpTrigger(props: {
|
|
342
|
+
identity: PopoverIdentity
|
|
343
|
+
panelId: string
|
|
344
|
+
}): SpaElement {
|
|
345
|
+
const getOpen = useGetter(popoverOpenAtoms, props.identity)
|
|
346
|
+
const setOpen = useSetter(popoverOpenAtoms, props.identity)
|
|
347
|
+
return (
|
|
348
|
+
<button
|
|
349
|
+
aria-controls={props.panelId}
|
|
350
|
+
aria-expanded={getOpen()}
|
|
351
|
+
aria-haspopup="dialog"
|
|
352
|
+
onClick={() => {
|
|
353
|
+
setOpen((open) => !open)
|
|
354
|
+
}}
|
|
355
|
+
>
|
|
356
|
+
{props.identity[1]} help
|
|
357
|
+
</button>
|
|
358
|
+
)
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
function HelpPanel(props: {
|
|
362
|
+
identity: PopoverIdentity
|
|
363
|
+
panelId: string
|
|
364
|
+
}): SpaElement {
|
|
365
|
+
const getOpen = useGetter(popoverOpenAtoms, props.identity)
|
|
366
|
+
return (
|
|
367
|
+
<div
|
|
368
|
+
id={props.panelId}
|
|
369
|
+
role="dialog"
|
|
370
|
+
aria-label={`${props.identity[1]} help`}
|
|
371
|
+
hidden={!getOpen()}
|
|
372
|
+
>
|
|
373
|
+
{props.identity[1] === `formatting`
|
|
374
|
+
? `Select text, then choose bold or italic from the toolbar.`
|
|
375
|
+
: `Use Ctrl+Z to undo and Ctrl+Shift+Z to redo.`}
|
|
376
|
+
</div>
|
|
377
|
+
)
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
function HelpPopover(props: { identity: PopoverIdentity }): SpaElement {
|
|
381
|
+
const identity = props.identity
|
|
382
|
+
const panelId = useId()
|
|
383
|
+
const dispose = useDisposal()
|
|
384
|
+
// This owner outlives both consumers of the ambient visibility state.
|
|
385
|
+
onCleanup(() => {
|
|
386
|
+
dispose(popoverOpenAtoms, identity)
|
|
387
|
+
})
|
|
388
|
+
return (
|
|
389
|
+
<section data-help={`${identity[0]}/${identity[1]}`}>
|
|
390
|
+
<HelpTrigger identity={identity} panelId={panelId} />
|
|
391
|
+
<HelpPanel identity={identity} panelId={panelId} />
|
|
392
|
+
</section>
|
|
393
|
+
)
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
export function HelpToolbar(props: { id: string }): SpaElement {
|
|
397
|
+
const toolbar = props.id
|
|
398
|
+
const getFormattingHelpVisible = useGetter(formattingHelpVisibleAtoms, toolbar)
|
|
399
|
+
const setFormattingHelpVisible = useSetter(formattingHelpVisibleAtoms, toolbar)
|
|
400
|
+
const dispose = useDisposal()
|
|
401
|
+
onCleanup(() => {
|
|
402
|
+
dispose(formattingHelpVisibleAtoms, toolbar)
|
|
403
|
+
})
|
|
404
|
+
return (
|
|
405
|
+
<nav aria-label={`${toolbar} help`}>
|
|
406
|
+
{(getFormattingHelpVisible()
|
|
407
|
+
? ([`formatting`, `shortcuts`] as const)
|
|
408
|
+
: ([`shortcuts`] as const)
|
|
409
|
+
).map((topic) => (
|
|
410
|
+
<HelpPopover key={topic} identity={[toolbar, topic]} />
|
|
411
|
+
))}
|
|
412
|
+
<button
|
|
413
|
+
onClick={() => {
|
|
414
|
+
setFormattingHelpVisible((visible) => !visible)
|
|
415
|
+
}}
|
|
416
|
+
>
|
|
417
|
+
{getFormattingHelpVisible() ? `Hide` : `Show`} formatting help
|
|
418
|
+
</button>
|
|
419
|
+
</nav>
|
|
420
|
+
)
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
The reconciliation key identifies a component among siblings. The family key identifies application state across the whole store: the tuple includes both the toolbar ID and help topic so separate toolbars do not share visibility by accident. The toolbar ID must be unique within that store. The renderer consumes key; pass the state identity as an ordinary prop.
|
|
426
|
+
|
|
427
|
+
Call useDisposal() without arguments during setup. It captures the current root's store and returns atom.io disposal, accepting either a family and key or an existing member token. Invoke it from an event handler or register it with onCleanup. It works with the implicit store, render/hydrate options.store, and isolated Astro stores without passing a disposal callback through props. Custom stores still need the module-scope definitions installed through Silo.install.
|
|
428
|
+
|
|
429
|
+
HelpPopover owns the visibility member shared by its trigger and panel, so it disposes that member after both consumers are removed. A single consumer must not dispose state that other live consumers still need. Shared session or application state belongs to the owner that knows when every consumer has finished. Standalone atoms persist for their store's lifetime; disposal removes family members, not standalone atoms.
|
|
430
|
+
|
|
431
|
+
Getter and setter bindings capture their family key during setup. Replacing a keyed instance changes its binding; changing an identity prop on an existing instance does not rebind it. Disposing a family member removes its stored value and resources; a later read recreates it from its default. Keep user-authored content in state whose owner matches its intended persistence, rather than treating it like a popover's transient visibility.
|
|
432
|
+
|
|
311
433
|
## Async state
|
|
312
434
|
|
|
313
435
|
```tsx
|
|
@@ -424,7 +546,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
|
|
|
424
546
|
|
|
425
547
|
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.
|
|
426
548
|
|
|
427
|
-
The hard budget is under 4,
|
|
549
|
+
The hard budget is under 4,400 bytes of ordinary level-9 gzip for the complete client export surface, including hydration recovery and its production diagnostics. 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.3 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
|
|
428
550
|
|
|
429
551
|
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.
|
|
430
552
|
|
|
@@ -456,11 +578,11 @@ Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations,
|
|
|
456
578
|
|
|
457
579
|
| Recipe | Entry | Minified JS | Gzip JS |
|
|
458
580
|
| -------------------------------- | --------------------------------- | ----------: | -------: |
|
|
459
|
-
| Family app with refs and history | `tonnage-recipes/family-app.ts` | 64,
|
|
460
|
-
| Async interactive client app | `tonnage-recipes/async-app.ts` | 42,
|
|
461
|
-
| Interactive client app | `tonnage-recipes/client-app.ts` | 42,
|
|
462
|
-
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 42,
|
|
463
|
-
| Interactive Astro island | `tonnage-recipes/astro-island.ts` | 48,
|
|
581
|
+
| Family app with refs and history | `tonnage-recipes/family-app.ts` | 64,279 B | 19,205 B |
|
|
582
|
+
| Async interactive client app | `tonnage-recipes/async-app.ts` | 42,722 B | 13,443 B |
|
|
583
|
+
| Interactive client app | `tonnage-recipes/client-app.ts` | 42,385 B | 13,297 B |
|
|
584
|
+
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 42,386 B | 13,295 B |
|
|
585
|
+
| Interactive Astro island | `tonnage-recipes/astro-island.ts` | 48,901 B | 15,328 B |
|
|
464
586
|
|
|
465
587
|
Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
|
|
466
588
|
|
|
@@ -545,8 +667,42 @@ export function Scene(): SpaElement {
|
|
|
545
667
|
|
|
546
668
|
```
|
|
547
669
|
|
|
670
|
+
Mesh accepts optional constructor args typed from Three.js, including custom BufferGeometry and a Material or material array. Resources supplied in args are borrowed: their application owner disposes them after all consumers finish. JSX geometry/material children and implicit Mesh defaults remain renderer-owned. Constructor args are fixed for the mounted instance; use a new reconciliation key to replace them.
|
|
671
|
+
|
|
548
672
|
Constructor args are fixed for an instance. To change them, replace the resource with a new key in a reactive child collection. Refs expose native objects. Owned geometries and materials are disposed on removal; textures passed through material properties remain borrowed. Canvas stops drawing and disposes its renderer on removal. The exported threeRenderer renders into a borrowed parent dedicated to its children without creating a WebGL renderer.
|
|
549
673
|
|
|
674
|
+
Canvas accepts rendererOptions for constructor-time settings such as alpha and powerPreference, or createRenderer to construct the renderer with the supplied canvas. Both paths are exclusively owned by Canvas: it disposes the renderer on removal or setup failure, and the factory must return a renderer using that canvas. Shared/borrowed renderers are not supported by this boundary; use threeRenderer for a separately owned renderer. Options and the factory are captured at mount; replace the keyed Canvas to reconstruct its context.
|
|
675
|
+
|
|
676
|
+
Use onCreated to configure tone mapping, output color space, scene background, or controls after the scene mounts and sizes, before the first draw. Return a cleanup callback for controls or other acquired resources. Numeric dpr selects a fixed positive ratio; a min/max tuple clamps devicePixelRatio and follows window resize events. The default remains 1. Width and height remain reactive positive CSS-pixel dimensions. Canvas updates its default perspective camera projection; supplied cameras are borrowed and retain their own projection. Use onResize to update an external perspective/orthographic camera explicitly. onFrame and pointer routing always use the current camera prop, with one frame loop using the installed Motion clock or requestAnimationFrame.
|
|
677
|
+
|
|
678
|
+
```tsx
|
|
679
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
680
|
+
import { BoxGeometry, Canvas, Mesh, MeshBasicMaterial } from "@atom.io/spa/three"
|
|
681
|
+
import { ACESFilmicToneMapping, SRGBColorSpace } from "three"
|
|
682
|
+
|
|
683
|
+
export function BoardCanvas(): SpaElement {
|
|
684
|
+
return (
|
|
685
|
+
<Canvas
|
|
686
|
+
width={800}
|
|
687
|
+
height={600}
|
|
688
|
+
dpr={[1, 2]}
|
|
689
|
+
rendererOptions={{ alpha: true, powerPreference: `high-performance` }}
|
|
690
|
+
onCreated={({ renderer, scene }) => {
|
|
691
|
+
renderer.toneMapping = ACESFilmicToneMapping
|
|
692
|
+
renderer.outputColorSpace = SRGBColorSpace
|
|
693
|
+
scene.background = null
|
|
694
|
+
}}
|
|
695
|
+
>
|
|
696
|
+
<Mesh>
|
|
697
|
+
<BoxGeometry />
|
|
698
|
+
<MeshBasicMaterial color="orange" />
|
|
699
|
+
</Mesh>
|
|
700
|
+
</Canvas>
|
|
701
|
+
)
|
|
702
|
+
}
|
|
703
|
+
|
|
704
|
+
```
|
|
705
|
+
|
|
550
706
|
Canvas defaults to a perspective camera at z = 5. Its optional camera prop borrows an external camera; a PerspectiveCamera child does not automatically become active. Width and height update the renderer and default camera. Canvas renders continuously and accepts an onFrame callback with scene, camera, renderer, delta seconds, and timestamp seconds. Controls, asset loading, and drawing on demand are outside this initial API.
|
|
551
707
|
|
|
552
708
|
### Three.js pointer events
|
|
@@ -611,7 +767,7 @@ export function MotionPanel(): SpaElement {
|
|
|
611
767
|
|
|
612
768
|
```
|
|
613
769
|
|
|
614
|
-
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
|
|
770
|
+
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 start at the animate target’s final value. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. DOM keyframe sequences and property-specific timing are supported as described below. Use motion:layout for layout changes and motion:layoutId for shared element transitions.
|
|
615
771
|
|
|
616
772
|
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.
|
|
617
773
|
|
|
@@ -656,7 +812,7 @@ export function SpringCube(): SpaElement {
|
|
|
656
812
|
|
|
657
813
|
```
|
|
658
814
|
|
|
659
|
-
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,
|
|
815
|
+
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,400 bytes.
|
|
660
816
|
|
|
661
817
|
### Exit animations and re-entry
|
|
662
818
|
|
|
@@ -709,7 +865,90 @@ During exit, reactive attributes, child reconciliation, user events, gestures, a
|
|
|
709
865
|
|
|
710
866
|
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.
|
|
711
867
|
|
|
712
|
-
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;
|
|
868
|
+
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; pop-layout positioning, variants, presence wrappers, and automatic reparenting remain outside its scope.
|
|
869
|
+
|
|
870
|
+
### Layout and shared identity
|
|
871
|
+
|
|
872
|
+
Register motionCapability from @atom.io/spa/motion once to enable animated properties, exits, HTML layout changes, and shared element transitions. All use the optional Motion peer; the base SPA runtime stays independent of Motion:
|
|
873
|
+
|
|
874
|
+
```tsx
|
|
875
|
+
import { render } from "@atom.io/spa"
|
|
876
|
+
import { motionCapability } from "@atom.io/spa/motion"
|
|
877
|
+
|
|
878
|
+
import { ReadinessBoard } from "./layout.tsx"
|
|
879
|
+
|
|
880
|
+
const host = document.querySelector(`#app`)!
|
|
881
|
+
const root = render(() => <ReadinessBoard />, host, {
|
|
882
|
+
capabilities: [
|
|
883
|
+
motionCapability({ layoutTransition: { duration: 0.3, ease: `easeInOut` } }),
|
|
884
|
+
],
|
|
885
|
+
})
|
|
886
|
+
|
|
887
|
+
export const disposeBoard = root.dispose
|
|
888
|
+
|
|
889
|
+
```
|
|
890
|
+
|
|
891
|
+
```tsx
|
|
892
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
893
|
+
import { useGetter, useSetter } from "@atom.io/spa"
|
|
894
|
+
import type {} from "@atom.io/spa/motion"
|
|
895
|
+
import { atom } from "atom.io"
|
|
896
|
+
|
|
897
|
+
const players = [`Ada`, `Grace`] as const
|
|
898
|
+
const readyPlayersAtom = atom<string[]>({ key: `readyPlayers`, default: [] })
|
|
899
|
+
|
|
900
|
+
function ReadinessGroup(props: { ready: boolean; match: string }): SpaElement {
|
|
901
|
+
const getReadyPlayers = useGetter(readyPlayersAtom)
|
|
902
|
+
const setReadyPlayers = useSetter(readyPlayersAtom)
|
|
903
|
+
return (
|
|
904
|
+
<section
|
|
905
|
+
motion:layout
|
|
906
|
+
style={`width:${getReadyPlayers().length ? 260 : 180}px;min-height:80px`}
|
|
907
|
+
>
|
|
908
|
+
<h2>{props.ready ? `Ready` : `Waiting`}</h2>
|
|
909
|
+
{players
|
|
910
|
+
.filter((player) => getReadyPlayers().includes(player) === props.ready)
|
|
911
|
+
.map((player) => (
|
|
912
|
+
<button
|
|
913
|
+
key={player}
|
|
914
|
+
motion:layout="position"
|
|
915
|
+
motion:layoutId={player}
|
|
916
|
+
motion:layoutGroup={props.match}
|
|
917
|
+
motion:exit={{ opacity: 0 }}
|
|
918
|
+
motion:transition={{ duration: 0.2 }}
|
|
919
|
+
onClick={() => {
|
|
920
|
+
setReadyPlayers((ready) =>
|
|
921
|
+
ready.includes(player)
|
|
922
|
+
? ready.filter((name) => name !== player)
|
|
923
|
+
: [...ready, player],
|
|
924
|
+
)
|
|
925
|
+
}}
|
|
926
|
+
>
|
|
927
|
+
{player}
|
|
928
|
+
</button>
|
|
929
|
+
))}
|
|
930
|
+
</section>
|
|
931
|
+
)
|
|
932
|
+
}
|
|
933
|
+
|
|
934
|
+
export function ReadinessBoard(): SpaElement {
|
|
935
|
+
return (
|
|
936
|
+
<>
|
|
937
|
+
<ReadinessGroup ready={false} match="match-1" />
|
|
938
|
+
<ReadinessGroup ready={true} match="match-1" />
|
|
939
|
+
</>
|
|
940
|
+
)
|
|
941
|
+
}
|
|
942
|
+
|
|
943
|
+
```
|
|
944
|
+
|
|
945
|
+
motion:layout enables position and size projection; position or size restricts the animated dimensions. motion:layoutId enables layout animation implicitly and carries a visual identity between outgoing/incoming nodes, while reconciliation keys continue to own component instances. Shared identities are isolated by root and by an explicit motion:layoutGroup on each shared node; group is not inherited. Use distinct group values for separate boards in one root. Reusing an ID within a group coordinates a shared transition, with the latest mounted member leading.
|
|
946
|
+
|
|
947
|
+
SPA snapshots registered targets before each synchronous update batch and projects after the DOM commits. Per-target ResizeObserver subscriptions also handle external size changes; no document-wide mutation observer or consumer measurement loop is needed. Mark scrolling layout ancestors with motion:layoutScroll. Nested projections preserve authored transforms and transform origins; Floating UI retains its independent translate positioning. Avoid multiple layout/projection owners or direct writes to a projected element's transform while the capability is active.
|
|
948
|
+
|
|
949
|
+
The default transition is a 0.3-second tween; the capability option layoutTransition sets defaults and motion:layoutTransition replaces them for a target. Use finite duration/delay values or settling spring parameters. Retargeting uses the current projection. Outgoing nodes remain available for shared handoff until replacements mount in the same batch. With Motion exits, layout follows the retained node's lifetime; keyed re-entry resumes the existing instance. Shared identity transfers appearance, not component state or DOM ownership, and nodes are not automatically reparented.
|
|
950
|
+
|
|
951
|
+
Reduced motion follows the user's preference by default; always and never options override it. Enabling reduced motion finishes projections immediately. Removal, fatal errors, and root disposal cancel projection work, disconnect observers/listeners, and restore owned attributes/styles. Server rendering emits no layout attributes or animation work. Layout is limited to owned HTML nodes; scene objects, SVG projection, pop-layout positioning, and cross-document handoff are unsupported.
|
|
713
952
|
|
|
714
953
|
### Floating overlays with Motion
|
|
715
954
|
|
|
@@ -811,3 +1050,36 @@ Position updates continue during Motion's retained exits, until physical disposa
|
|
|
811
1050
|
### Renderer extensions
|
|
812
1051
|
|
|
813
1052
|
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.
|
|
1053
|
+
|
|
1054
|
+
## Motion keyframes and property transitions
|
|
1055
|
+
|
|
1056
|
+
DOM motion targets accept scalar values or keyframe sequences of at least two values. A null first frame starts from the current animated value, which is useful when retargeting an interrupted sequence. Initial DOM targets remain scalar. Three position, rotation, and scale tuples retain their vector meaning; Konva and other scene targets remain scalar. Keyframe sequences use tweens by default; explicit springs support at most two frames. Reduced motion and initial:false resolve to the final frame.
|
|
1057
|
+
|
|
1058
|
+
Transition times are normalized, ordered values from 0 to 1 and must match the keyframe count. ease accepts a single named easing/cubic-bezier tuple or one easing for each interval. Top-level options are overridden by default options, then by properties\[propertyName], with missing fields inherited in that order. This allows independent timing per property and per element. Times and easing lengths must match the effective sequence, including exit targets; invalid combinations report a spa/motion diagnostic. Sequences share the existing interruption, gesture, keyed exit/re-entry, and disposal ownership.
|
|
1059
|
+
|
|
1060
|
+
```tsx
|
|
1061
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
1062
|
+
import type {} from "@atom.io/spa/motion"
|
|
1063
|
+
|
|
1064
|
+
export function TurnBanner(): SpaElement {
|
|
1065
|
+
return (
|
|
1066
|
+
<aside
|
|
1067
|
+
motion:animate={{
|
|
1068
|
+
x: [`-1500%`, `2%`, `4%`, `1500%`],
|
|
1069
|
+
skewX: [`-50deg`, `-5deg`, `-5deg`, `-50deg`],
|
|
1070
|
+
width: [`20vw`, `90vw`, `90vw`, `10vw`],
|
|
1071
|
+
opacity: [0, 1, 1, 0],
|
|
1072
|
+
}}
|
|
1073
|
+
motion:transition={{
|
|
1074
|
+
duration: 3,
|
|
1075
|
+
times: [0, 0.1, 0.77, 1],
|
|
1076
|
+
ease: [`circOut`, `linear`, `easeIn`],
|
|
1077
|
+
properties: { opacity: { times: [0, 0.2, 0.8, 1], ease: `linear` } },
|
|
1078
|
+
}}
|
|
1079
|
+
>
|
|
1080
|
+
Next turn
|
|
1081
|
+
</aside>
|
|
1082
|
+
)
|
|
1083
|
+
}
|
|
1084
|
+
|
|
1085
|
+
```
|
package/README.mdx
CHANGED
|
@@ -1,3 +1,12 @@
|
|
|
1
|
+
import StateLifetimes from "./exhibits/state-lifetimes.tsx" with {
|
|
2
|
+
type: "code",
|
|
3
|
+
};
|
|
4
|
+
import MotionKeyframes from "./exhibits/motion-keyframes.tsx" with {
|
|
5
|
+
type: "code",
|
|
6
|
+
};
|
|
7
|
+
import ConfigurableCanvas from "./exhibits/configurable-canvas.tsx" with {
|
|
8
|
+
type: "code",
|
|
9
|
+
};
|
|
1
10
|
import { Tonnage } from "tonnage";
|
|
2
11
|
import config from "./tonnage.config.ts";
|
|
3
12
|
import StoreExample from "./exhibits/store.tsx" with { type: "code" };
|
|
@@ -26,6 +35,8 @@ import MotionThree from "./exhibits/motion-three.tsx" with { type: "code" };
|
|
|
26
35
|
import InstallFloating from "./exhibits/install-floating.sh" with {
|
|
27
36
|
type: "code",
|
|
28
37
|
};
|
|
38
|
+
import LayoutExample from "./exhibits/layout.tsx" with { type: "code" };
|
|
39
|
+
import LayoutMain from "./exhibits/layout-main.tsx" with { type: "code" };
|
|
29
40
|
import FloatingMain from "./exhibits/floating-main.tsx" with { type: "code" };
|
|
30
41
|
import FloatingExample from "./exhibits/floating.tsx" with { type: "code" };
|
|
31
42
|
|
|
@@ -91,6 +102,7 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
91
102
|
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
92
103
|
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
93
104
|
| useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
|
|
105
|
+
| useDisposal() | Return atom.io state disposal bound to the current root's store. |
|
|
94
106
|
| useSetter(token) | Return a stable atom.io writer. |
|
|
95
107
|
| useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
|
|
96
108
|
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
@@ -118,7 +130,7 @@ useStore returns the current root's atom.io RootStore directly. It is the same o
|
|
|
118
130
|
|
|
119
131
|
<StoreExample />
|
|
120
132
|
|
|
121
|
-
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.
|
|
133
|
+
For family-member disposal, useDisposal() captures this store and returns a bound disposal command; see [ambient UI state](#ambient-ui-state-and-ownership). Capture the store during component setup or an owned onMount callback, then pass it to other 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.
|
|
122
134
|
|
|
123
135
|
## Families
|
|
124
136
|
|
|
@@ -128,6 +140,22 @@ useGetter, useSetter, useRef, and useTimeline accept a family token followed by
|
|
|
128
140
|
|
|
129
141
|
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.
|
|
130
142
|
|
|
143
|
+
### Ambient UI state and ownership
|
|
144
|
+
|
|
145
|
+
Ambient state is useful for ephemeral UI flags that several components need to read or change, such as whether a popover is open. Define the family at module scope and give each popover an application identity. Its trigger and panel can bind to the same boolean without passing the value and setter through their parent.
|
|
146
|
+
|
|
147
|
+
This exhibit gives each toolbar its own formatting and keyboard-shortcut help popovers. Hiding formatting help removes its keyed instance and disposes its visibility state. Showing it again starts closed; the shortcuts popover and other toolbars keep their state:
|
|
148
|
+
|
|
149
|
+
<StateLifetimes />
|
|
150
|
+
|
|
151
|
+
The reconciliation key identifies a component among siblings. The family key identifies application state across the whole store: the tuple includes both the toolbar ID and help topic so separate toolbars do not share visibility by accident. The toolbar ID must be unique within that store. The renderer consumes key; pass the state identity as an ordinary prop.
|
|
152
|
+
|
|
153
|
+
Call useDisposal() without arguments during setup. It captures the current root's store and returns atom.io disposal, accepting either a family and key or an existing member token. Invoke it from an event handler or register it with onCleanup. It works with the implicit store, render/hydrate options.store, and isolated Astro stores without passing a disposal callback through props. Custom stores still need the module-scope definitions installed through Silo.install.
|
|
154
|
+
|
|
155
|
+
HelpPopover owns the visibility member shared by its trigger and panel, so it disposes that member after both consumers are removed. A single consumer must not dispose state that other live consumers still need. Shared session or application state belongs to the owner that knows when every consumer has finished. Standalone atoms persist for their store's lifetime; disposal removes family members, not standalone atoms.
|
|
156
|
+
|
|
157
|
+
Getter and setter bindings capture their family key during setup. Replacing a keyed instance changes its binding; changing an identity prop on an existing instance does not rebind it. Disposing a family member removes its stored value and resources; a later read recreates it from its default. Keep user-authored content in state whose owner matches its intended persistence, rather than treating it like a popover's transient visibility.
|
|
158
|
+
|
|
131
159
|
## Async state
|
|
132
160
|
|
|
133
161
|
<LoadableExample />
|
|
@@ -180,7 +208,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
|
|
|
180
208
|
|
|
181
209
|
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.
|
|
182
210
|
|
|
183
|
-
The hard budget is under 4,
|
|
211
|
+
The hard budget is under 4,400 bytes of ordinary level-9 gzip for the complete client export surface, including hydration recovery and its production diagnostics. 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.3 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
|
|
184
212
|
|
|
185
213
|
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.
|
|
186
214
|
|
|
@@ -216,8 +244,16 @@ Import Canvas, Group, Mesh, PerspectiveCamera, AmbientLight, DirectionalLight, B
|
|
|
216
244
|
|
|
217
245
|
<ThreeExample />
|
|
218
246
|
|
|
247
|
+
Mesh accepts optional constructor args typed from Three.js, including custom BufferGeometry and a Material or material array. Resources supplied in args are borrowed: their application owner disposes them after all consumers finish. JSX geometry/material children and implicit Mesh defaults remain renderer-owned. Constructor args are fixed for the mounted instance; use a new reconciliation key to replace them.
|
|
248
|
+
|
|
219
249
|
Constructor args are fixed for an instance. To change them, replace the resource with a new key in a reactive child collection. Refs expose native objects. Owned geometries and materials are disposed on removal; textures passed through material properties remain borrowed. Canvas stops drawing and disposes its renderer on removal. The exported threeRenderer renders into a borrowed parent dedicated to its children without creating a WebGL renderer.
|
|
220
250
|
|
|
251
|
+
Canvas accepts rendererOptions for constructor-time settings such as alpha and powerPreference, or createRenderer to construct the renderer with the supplied canvas. Both paths are exclusively owned by Canvas: it disposes the renderer on removal or setup failure, and the factory must return a renderer using that canvas. Shared/borrowed renderers are not supported by this boundary; use threeRenderer for a separately owned renderer. Options and the factory are captured at mount; replace the keyed Canvas to reconstruct its context.
|
|
252
|
+
|
|
253
|
+
Use onCreated to configure tone mapping, output color space, scene background, or controls after the scene mounts and sizes, before the first draw. Return a cleanup callback for controls or other acquired resources. Numeric dpr selects a fixed positive ratio; a min/max tuple clamps devicePixelRatio and follows window resize events. The default remains 1. Width and height remain reactive positive CSS-pixel dimensions. Canvas updates its default perspective camera projection; supplied cameras are borrowed and retain their own projection. Use onResize to update an external perspective/orthographic camera explicitly. onFrame and pointer routing always use the current camera prop, with one frame loop using the installed Motion clock or requestAnimationFrame.
|
|
254
|
+
|
|
255
|
+
<ConfigurableCanvas />
|
|
256
|
+
|
|
221
257
|
Canvas defaults to a perspective camera at z = 5. Its optional camera prop borrows an external camera; a PerspectiveCamera child does not automatically become active. Width and height update the renderer and default camera. Canvas renders continuously and accepts an onFrame callback with scene, camera, renderer, delta seconds, and timestamp seconds. Controls, asset loading, and drawing on demand are outside this initial API.
|
|
222
258
|
|
|
223
259
|
### Three.js pointer events
|
|
@@ -240,7 +276,7 @@ Use motion:initial, motion:animate, motion:exit, motion:transition, motion:while
|
|
|
240
276
|
|
|
241
277
|
<MotionPanel />
|
|
242
278
|
|
|
243
|
-
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
|
|
279
|
+
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 start at the animate target’s final value. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. DOM keyframe sequences and property-specific timing are supported as described below. Use motion:layout for layout changes and motion:layoutId for shared element transitions.
|
|
244
280
|
|
|
245
281
|
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.
|
|
246
282
|
|
|
@@ -248,7 +284,7 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
|
|
|
248
284
|
|
|
249
285
|
<MotionThree />
|
|
250
286
|
|
|
251
|
-
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,
|
|
287
|
+
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,400 bytes.
|
|
252
288
|
|
|
253
289
|
### Exit animations and re-entry
|
|
254
290
|
|
|
@@ -268,7 +304,23 @@ During exit, reactive attributes, child reconciliation, user events, gestures, a
|
|
|
268
304
|
|
|
269
305
|
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.
|
|
270
306
|
|
|
271
|
-
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;
|
|
307
|
+
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; pop-layout positioning, variants, presence wrappers, and automatic reparenting remain outside its scope.
|
|
308
|
+
|
|
309
|
+
### Layout and shared identity
|
|
310
|
+
|
|
311
|
+
Register motionCapability from @atom.io/spa/motion once to enable animated properties, exits, HTML layout changes, and shared element transitions. All use the optional Motion peer; the base SPA runtime stays independent of Motion:
|
|
312
|
+
|
|
313
|
+
<LayoutMain />
|
|
314
|
+
|
|
315
|
+
<LayoutExample />
|
|
316
|
+
|
|
317
|
+
motion:layout enables position and size projection; position or size restricts the animated dimensions. motion:layoutId enables layout animation implicitly and carries a visual identity between outgoing/incoming nodes, while reconciliation keys continue to own component instances. Shared identities are isolated by root and by an explicit motion:layoutGroup on each shared node; group is not inherited. Use distinct group values for separate boards in one root. Reusing an ID within a group coordinates a shared transition, with the latest mounted member leading.
|
|
318
|
+
|
|
319
|
+
SPA snapshots registered targets before each synchronous update batch and projects after the DOM commits. Per-target ResizeObserver subscriptions also handle external size changes; no document-wide mutation observer or consumer measurement loop is needed. Mark scrolling layout ancestors with motion:layoutScroll. Nested projections preserve authored transforms and transform origins; Floating UI retains its independent translate positioning. Avoid multiple layout/projection owners or direct writes to a projected element's transform while the capability is active.
|
|
320
|
+
|
|
321
|
+
The default transition is a 0.3-second tween; the capability option layoutTransition sets defaults and motion:layoutTransition replaces them for a target. Use finite duration/delay values or settling spring parameters. Retargeting uses the current projection. Outgoing nodes remain available for shared handoff until replacements mount in the same batch. With Motion exits, layout follows the retained node's lifetime; keyed re-entry resumes the existing instance. Shared identity transfers appearance, not component state or DOM ownership, and nodes are not automatically reparented.
|
|
322
|
+
|
|
323
|
+
Reduced motion follows the user's preference by default; always and never options override it. Enabling reduced motion finishes projections immediately. Removal, fatal errors, and root disposal cancel projection work, disconnect observers/listeners, and restore owned attributes/styles. Server rendering emits no layout attributes or animation work. Layout is limited to owned HTML nodes; scene objects, SVG projection, pop-layout positioning, and cross-document handoff are unsupported.
|
|
272
324
|
|
|
273
325
|
### Floating overlays with Motion
|
|
274
326
|
|
|
@@ -302,3 +354,11 @@ Position updates continue during Motion's retained exits, until physical disposa
|
|
|
302
354
|
### Renderer extensions
|
|
303
355
|
|
|
304
356
|
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.
|
|
357
|
+
|
|
358
|
+
## Motion keyframes and property transitions
|
|
359
|
+
|
|
360
|
+
DOM motion targets accept scalar values or keyframe sequences of at least two values. A null first frame starts from the current animated value, which is useful when retargeting an interrupted sequence. Initial DOM targets remain scalar. Three position, rotation, and scale tuples retain their vector meaning; Konva and other scene targets remain scalar. Keyframe sequences use tweens by default; explicit springs support at most two frames. Reduced motion and initial:false resolve to the final frame.
|
|
361
|
+
|
|
362
|
+
Transition times are normalized, ordered values from 0 to 1 and must match the keyframe count. ease accepts a single named easing/cubic-bezier tuple or one easing for each interval. Top-level options are overridden by default options, then by properties[propertyName], with missing fields inherited in that order. This allows independent timing per property and per element. Times and easing lengths must match the effective sequence, including exit targets; invalid combinations report a spa/motion diagnostic. Sequences share the existing interruption, gesture, keyed exit/re-entry, and disposal ownership.
|
|
363
|
+
|
|
364
|
+
<MotionKeyframes />
|
package/dist/astro-client.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as Island, i as AstroStorePreparation } from "./astro-shared-
|
|
1
|
+
import { a as Island, i as AstroStorePreparation } from "./astro-shared-DZp1x8RQ.js";
|
|
2
2
|
type Props = Record<string, any>;
|
|
3
3
|
type Slots = Record<string, string>;
|
|
4
4
|
type Hydrator = (component: Island, props: Props, slots: Slots, metadata: {
|
package/dist/astro-client.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { browserApplication } from "./astro-application.js";
|
|
2
2
|
import { n as failPreparation, r as storeContext } from "./astro-context-OdlexHR4.js";
|
|
3
3
|
import { n as islandStore, t as island } from "./astro-shared-83hxw7-M.js";
|
|
4
|
-
import { c as onCleanup,
|
|
5
|
-
import { n as render, t as hydrate } from "./dom-
|
|
4
|
+
import { c as onCleanup, h as useGetter } from "./core-B4rJ0xdc.js";
|
|
5
|
+
import { n as render, t as hydrate } from "./dom-D8g3roX9.js";
|
|
6
6
|
import { IMPLICIT, createRegularAtomFamily, disposeFromStore, findInStore, getFromStore, setIntoStore } from "atom.io/internal";
|
|
7
7
|
// src/astro-client.ts
|
|
8
8
|
const roots = /* @__PURE__ */ new WeakMap();
|
package/dist/astro-server.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { n as failPreparation, r as storeContext } from "./astro-context-OdlexHR4.js";
|
|
2
2
|
import { t as requestApplication } from "./astro-request-DRKvDjsO.js";
|
|
3
3
|
import { n as islandStore, t as island } from "./astro-shared-83hxw7-M.js";
|
|
4
|
-
import { t as renderToStringWithReads } from "./server-renderer-
|
|
4
|
+
import { t as renderToStringWithReads } from "./server-renderer-D0rsFL_-.js";
|
|
5
5
|
// src/astro-server.ts
|
|
6
6
|
const createRenderer = (awaitState = false) => ({
|
|
7
7
|
name: `spa`,
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { o as Component, t as Capability } from "./capabilities-
|
|
1
|
+
import { o as Component, t as Capability } from "./capabilities-DNcnGRv_.js";
|
|
2
2
|
import { RootStore } from "atom.io/internal";
|
|
3
3
|
interface AstroApplicationContext {
|
|
4
4
|
/** Whether the application still represents its initial server snapshot. */
|
|
@@ -30,4 +30,4 @@ type Island<P = any> = Component<P> & {
|
|
|
30
30
|
prepareStore?: AstroStorePreparation<P>;
|
|
31
31
|
};
|
|
32
32
|
export { Island as a, AstroStorePreparation as i, AstroStoreContext as n, AstroStoreFactory as r, AstroApplicationContext as t };
|
|
33
|
-
//# sourceMappingURL=astro-shared-
|
|
33
|
+
//# sourceMappingURL=astro-shared-DZp1x8RQ.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"astro-shared-
|
|
1
|
+
{"version":3,"file":"astro-shared-DZp1x8RQ.d.ts","names":[],"sources":["../src/astro-shared.ts"],"mappings":";;UAOiB;;WAEP;WACA,QAAQ;EACjB,UAAU;;EAEV,IAAI,GAAG,cAAc,kBAAkB,IAAI;;UAE3B;;EAEhB,aAAa;;EAEb,SAAS;;EAET,QAAQ;;EAER,UAAU;;KAEC,kBAAkB,IAAI,wBACjC,OAAO,GACP,SAAS,sBACL,YAAY,QAAQ;KACb,sBAAsB,IAAI,wBACrC,OAAO,WACP,OAAO,GACP,SAAS,6BACE;KACA,OAAO,WAAW,UAAU;EACvC;;EAEA,wBAAwB;;EAExB;EACA,cAAc,kBAAkB;EAChC,eAAe,sBAAsB"}
|
package/dist/astro.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { SpaPluginOptions } from "./vite.js";
|
|
2
|
-
import { a as Island, i as AstroStorePreparation, n as AstroStoreContext, r as AstroStoreFactory, t as AstroApplicationContext } from "./astro-shared-
|
|
2
|
+
import { a as Island, i as AstroStorePreparation, n as AstroStoreContext, r as AstroStoreFactory, t as AstroApplicationContext } from "./astro-shared-DZp1x8RQ.js";
|
|
3
3
|
import { AstroIntegration } from "astro";
|
|
4
4
|
export default function integration(options?: SpaPluginOptions): AstroIntegration;
|
|
5
5
|
export type { AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePreparation, Island };
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { RootStore } from "atom.io/internal";
|
|
2
|
-
import { ReadableFamilyToken, ReadableToken, RegularAtomFamilyToken, RegularAtomToken, Setter, TimelineFamilyToken, TimelineManageable, TimelineToken, TransactionToken, ViewOf, WritableFamilyToken, WritableToken } from "atom.io";
|
|
2
|
+
import { ReadableFamilyToken, ReadableToken, RegularAtomFamilyToken, RegularAtomToken, Setter, TimelineFamilyToken, TimelineManageable, TimelineToken, TransactionToken, ViewOf, WritableFamilyToken, WritableToken, disposeState } from "atom.io";
|
|
3
3
|
import { Canonical } from "atom.io/foundations/canonical";
|
|
4
4
|
interface ExitHandle {
|
|
5
5
|
finished: Promise<void>;
|
|
@@ -71,6 +71,8 @@ interface Root extends Scope {
|
|
|
71
71
|
}
|
|
72
72
|
/** Return the atom.io store selected by the current root. */
|
|
73
73
|
declare function useStore(): RootStore;
|
|
74
|
+
/** Return atom.io disposal bound to the current root's store. */
|
|
75
|
+
declare function useDisposal(): typeof disposeState;
|
|
74
76
|
declare function onCleanup(cleanup: Cleanup): void;
|
|
75
77
|
declare function onMount(run: Cleanup): void;
|
|
76
78
|
declare function useId(): string;
|
|
@@ -113,10 +115,12 @@ interface CapabilityBinding {
|
|
|
113
115
|
}
|
|
114
116
|
interface Capability {
|
|
115
117
|
namespace: string;
|
|
118
|
+
/** Prepare a synchronous update batch and return its commit callback. */
|
|
119
|
+
beforeUpdate?(root: Root): Cleanup;
|
|
116
120
|
presence?(root: Root): PresenceCoordinator;
|
|
117
121
|
scheduleFrame?(callback: (time: number) => void): Cleanup;
|
|
118
122
|
/** SPA supplies ownership for integrations that measure after mount or report async errors. */
|
|
119
123
|
attach(target: CapabilityTarget, scope?: Scope): CapabilityBinding;
|
|
120
124
|
}
|
|
121
|
-
export {
|
|
122
|
-
//# sourceMappingURL=capabilities-
|
|
125
|
+
export { useStore as _, Children as a, SpaElement as c, onMount as d, useDisposal as f, useSetter as g, useRef as h, Accessor as i, TimelineControls as l, useId as m, CapabilityBinding as n, Component as o, useGetter as p, CapabilityTarget as r, RootOptions as s, Capability as t, onCleanup as u, useTimeline as v, useTransaction as y };
|
|
126
|
+
//# sourceMappingURL=capabilities-DNcnGRv_.d.ts.map
|