@atom.io/spa 0.0.5 → 0.0.7
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 +381 -10
- package/README.mdx +101 -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-request-DRKvDjsO.js.map +1 -1
- package/dist/astro-resumability-client.d.ts +1 -1
- package/dist/astro-server.js +1 -1
- package/dist/{astro-shared-DHIpjNIG.d.ts → astro-shared-DZp1x8RQ.d.ts} +2 -2
- package/dist/{astro-shared-DHIpjNIG.d.ts.map → astro-shared-DZp1x8RQ.d.ts.map} +1 -1
- package/dist/astro.d.ts +1 -1
- package/dist/astro.js +1 -1
- package/dist/{capabilities-BCtBG-ni.d.ts → capabilities-DNcnGRv_.d.ts} +11 -5
- package/dist/capabilities-DNcnGRv_.d.ts.map +1 -0
- package/dist/{capabilities-BkQ2i0vV.js → capabilities-nOIitQ-_.js} +6 -4
- package/dist/capabilities-nOIitQ-_.js.map +1 -0
- 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-request-DRKvDjsO.js.map +1 -1
- package/dist/development/astro-server.js +1 -1
- package/dist/development/astro.js +1 -1
- package/dist/development/{capabilities-BkQ2i0vV.js → capabilities-nOIitQ-_.js} +6 -4
- package/dist/development/capabilities-nOIitQ-_.js.map +1 -0
- package/dist/development/{core-DxPiKryn.js → core-BHA7I1nf.js} +24 -14
- package/dist/development/core-BHA7I1nf.js.map +1 -0
- package/dist/development/{dom-BytVV6Rp.js → dom-DQ0M3rLL.js} +11 -10
- package/dist/development/{dom-BytVV6Rp.js.map → dom-DQ0M3rLL.js.map} +1 -1
- package/dist/development/floating.js +148 -0
- package/dist/development/floating.js.map +1 -0
- package/dist/development/index.js +4 -4
- package/dist/development/jsx-runtime.js +2 -2
- package/dist/development/jsx-runtime.js.map +1 -1
- package/dist/development/konva.js +2 -2
- package/dist/development/motion.js +419 -25
- package/dist/development/motion.js.map +1 -1
- package/dist/development/renderer.js +2 -2
- package/dist/development/{server-renderer-CUQXh9oF.js → server-renderer-DCLoMdOX.js} +3 -3
- package/dist/development/{server-renderer-CUQXh9oF.js.map → server-renderer-DCLoMdOX.js.map} +1 -1
- package/dist/development/server.js +1 -1
- package/dist/{src-DWIqXCiz.js → development/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 +87 -31
- package/dist/development/three.js.map +1 -1
- package/dist/development/{vite-CSHoxzXU.js → vite-Bmyb6P5w.js} +32 -7
- package/dist/development/vite-Bmyb6P5w.js.map +1 -0
- package/dist/development/vite.js +1 -1
- package/dist/{dom-B5OxgHkr.js → dom-D8g3roX9.js} +11 -10
- package/dist/{dom-B5OxgHkr.js.map → dom-D8g3roX9.js.map} +1 -1
- package/dist/floating.d.ts +16 -0
- package/dist/floating.d.ts.map +1 -0
- package/dist/floating.js +148 -0
- package/dist/floating.js.map +1 -0
- package/dist/{index-DufwkB6W.d.ts → index-BFnXIfOj.d.ts} +3 -3
- package/dist/{index-DufwkB6W.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-DMDVr7A5.d.ts → jsx-runtime-DQnpyT_g.d.ts} +2 -2
- package/dist/{jsx-runtime-DMDVr7A5.d.ts.map → jsx-runtime-DQnpyT_g.d.ts.map} +1 -1
- package/dist/jsx-runtime.d.ts +1 -1
- package/dist/jsx-runtime.js +2 -2
- package/dist/jsx-runtime.js.map +1 -1
- package/dist/konva.d.ts +3 -3
- package/dist/konva.js +2 -2
- package/dist/motion.d.ts +39 -16
- package/dist/motion.d.ts.map +1 -1
- package/dist/motion.js +419 -25
- package/dist/motion.js.map +1 -1
- package/dist/renderer.d.ts +1 -1
- package/dist/renderer.js +2 -2
- package/dist/{server-renderer-DcU55e6s.js → server-renderer-D0rsFL_-.js} +3 -3
- package/dist/{server-renderer-DcU55e6s.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/{development/src-WSHJxR9b.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 +87 -31
- package/dist/three.js.map +1 -1
- package/dist/{vite-CSHoxzXU.js → vite-Bmyb6P5w.js} +32 -7
- package/dist/vite-Bmyb6P5w.js.map +1 -0
- package/dist/vite.js +1 -1
- package/package.json +18 -5
- package/src/astro-request.ts +1 -1
- package/src/capabilities.ts +11 -4
- package/src/compiler.ts +28 -9
- package/src/core.ts +26 -12
- package/src/dom.ts +12 -11
- package/src/floating.ts +234 -0
- package/src/index.ts +1 -0
- package/src/jsx-runtime.ts +4 -1
- 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 +215 -77
- package/src/presence.ts +1 -1
- package/src/three-events.ts +14 -10
- package/src/three.ts +134 -39
- package/dist/capabilities-BCtBG-ni.d.ts.map +0 -1
- package/dist/capabilities-BkQ2i0vV.js.map +0 -1
- package/dist/core-DjFJ0aIJ.js.map +0 -1
- package/dist/development/capabilities-BkQ2i0vV.js.map +0 -1
- package/dist/development/core-DxPiKryn.js.map +0 -1
- package/dist/development/vite-CSHoxzXU.js.map +0 -1
- package/dist/vite-CSHoxzXU.js.map +0 -1
package/README.md
CHANGED
|
@@ -57,6 +57,8 @@ export function PointEditor(): SpaElement {
|
|
|
57
57
|
|
|
58
58
|
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.
|
|
59
59
|
|
|
60
|
+
Component children follow the same getter contract as named props. A component declaring string children reads a string for both literal text and expression children, including an explicit children attribute. Read props.children inside compiled JSX or a tracked binding for reactive updates; setup reads capture a snapshot. Deliberately function-valued children remain functions, including render callbacks.
|
|
61
|
+
|
|
60
62
|
## Astro
|
|
61
63
|
|
|
62
64
|
Register the Astro integration, which compiles .tsx and .jsx components by default:
|
|
@@ -166,6 +168,7 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
166
168
|
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
167
169
|
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
168
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. |
|
|
169
172
|
| useSetter(token) | Return a stable atom.io writer. |
|
|
170
173
|
| useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
|
|
171
174
|
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
@@ -259,7 +262,7 @@ export function InspectCount(): SpaElement {
|
|
|
259
262
|
|
|
260
263
|
```
|
|
261
264
|
|
|
262
|
-
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.
|
|
263
266
|
|
|
264
267
|
## Families
|
|
265
268
|
|
|
@@ -306,6 +309,127 @@ export function FamilyCounter(props: { id: string }): SpaElement {
|
|
|
306
309
|
|
|
307
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.
|
|
308
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
|
+
|
|
309
433
|
## Async state
|
|
310
434
|
|
|
311
435
|
```tsx
|
|
@@ -422,7 +546,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
|
|
|
422
546
|
|
|
423
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.
|
|
424
548
|
|
|
425
|
-
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.
|
|
426
550
|
|
|
427
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.
|
|
428
552
|
|
|
@@ -454,11 +578,11 @@ Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations,
|
|
|
454
578
|
|
|
455
579
|
| Recipe | Entry | Minified JS | Gzip JS |
|
|
456
580
|
| -------------------------------- | --------------------------------- | ----------: | -------: |
|
|
457
|
-
| Family app with refs and history | `tonnage-recipes/family-app.ts` | 64,
|
|
458
|
-
| Async interactive client app | `tonnage-recipes/async-app.ts` | 42,
|
|
459
|
-
| Interactive client app | `tonnage-recipes/client-app.ts` | 42,
|
|
460
|
-
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 42,
|
|
461
|
-
| 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 |
|
|
462
586
|
|
|
463
587
|
Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
|
|
464
588
|
|
|
@@ -543,8 +667,42 @@ export function Scene(): SpaElement {
|
|
|
543
667
|
|
|
544
668
|
```
|
|
545
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
|
+
|
|
546
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.
|
|
547
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
|
+
|
|
548
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.
|
|
549
707
|
|
|
550
708
|
### Three.js pointer events
|
|
@@ -609,7 +767,7 @@ export function MotionPanel(): SpaElement {
|
|
|
609
767
|
|
|
610
768
|
```
|
|
611
769
|
|
|
612
|
-
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.
|
|
613
771
|
|
|
614
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.
|
|
615
773
|
|
|
@@ -654,7 +812,7 @@ export function SpringCube(): SpaElement {
|
|
|
654
812
|
|
|
655
813
|
```
|
|
656
814
|
|
|
657
|
-
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.
|
|
658
816
|
|
|
659
817
|
### Exit animations and re-entry
|
|
660
818
|
|
|
@@ -707,8 +865,221 @@ During exit, reactive attributes, child reconciliation, user events, gestures, a
|
|
|
707
865
|
|
|
708
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.
|
|
709
867
|
|
|
710
|
-
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.
|
|
952
|
+
|
|
953
|
+
### Floating overlays with Motion
|
|
954
|
+
|
|
955
|
+
The optional @atom.io/spa/floating entrypoint adapts @floating-ui/dom. Install Floating UI and Motion for this example, then register both capabilities on the root:
|
|
956
|
+
|
|
957
|
+
```sh
|
|
958
|
+
pnpm add @floating-ui/dom motion
|
|
959
|
+
|
|
960
|
+
```
|
|
961
|
+
|
|
962
|
+
```tsx
|
|
963
|
+
import { render } from "@atom.io/spa"
|
|
964
|
+
import { floatingCapability } from "@atom.io/spa/floating"
|
|
965
|
+
import { motionCapability } from "@atom.io/spa/motion"
|
|
966
|
+
|
|
967
|
+
import { FloatingDetails } from "./floating.tsx"
|
|
968
|
+
|
|
969
|
+
render(() => <FloatingDetails id="details" />, document.getElementById(`app`)!, {
|
|
970
|
+
capabilities: [floatingCapability(), motionCapability()],
|
|
971
|
+
})
|
|
972
|
+
|
|
973
|
+
```
|
|
974
|
+
|
|
975
|
+
Floating positions an HTML overlay using CSS translate. Motion can animate x, y, scale, rotation, and opacity on that same element through its separate transform property:
|
|
976
|
+
|
|
977
|
+
```tsx
|
|
978
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
979
|
+
import { useGetter, useId, useRef, useSetter } from "@atom.io/spa"
|
|
980
|
+
import { flip, offset, shift } from "@floating-ui/dom"
|
|
981
|
+
import { atomFamily } from "atom.io"
|
|
982
|
+
|
|
983
|
+
const floatingOpenAtoms = atomFamily<boolean, string>({
|
|
984
|
+
key: `floatingOpen`,
|
|
985
|
+
default: false,
|
|
986
|
+
})
|
|
987
|
+
const floatingTriggerAtoms = atomFamily<HTMLButtonElement | null, string>({
|
|
988
|
+
key: `floatingTrigger`,
|
|
989
|
+
default: null,
|
|
990
|
+
})
|
|
991
|
+
const middleware = [offset(8), flip(), shift({ padding: 8 })]
|
|
992
|
+
|
|
993
|
+
export function FloatingDetails(props: { id: string }): SpaElement {
|
|
994
|
+
const getOpen = useGetter(floatingOpenAtoms, props.id)
|
|
995
|
+
const setOpen = useSetter(floatingOpenAtoms, props.id)
|
|
996
|
+
const getTrigger = useGetter(floatingTriggerAtoms, props.id)
|
|
997
|
+
const attachTrigger = useRef(floatingTriggerAtoms, props.id)
|
|
998
|
+
const panelId = useId()
|
|
999
|
+
return (
|
|
1000
|
+
<>
|
|
1001
|
+
<button
|
|
1002
|
+
ref={attachTrigger}
|
|
1003
|
+
aria-expanded={getOpen()}
|
|
1004
|
+
aria-controls={panelId}
|
|
1005
|
+
onClick={() => {
|
|
1006
|
+
setOpen((value) => !value)
|
|
1007
|
+
}}
|
|
1008
|
+
>
|
|
1009
|
+
Details
|
|
1010
|
+
</button>
|
|
1011
|
+
{getOpen() && (
|
|
1012
|
+
<section
|
|
1013
|
+
key="details"
|
|
1014
|
+
id={panelId}
|
|
1015
|
+
aria-label="Details"
|
|
1016
|
+
style="width: 240px; margin: 0"
|
|
1017
|
+
floating:reference={getTrigger()}
|
|
1018
|
+
floating:placement="bottom-start"
|
|
1019
|
+
floating:middleware={middleware}
|
|
1020
|
+
motion:initial={{ opacity: 0, y: -4, scale: 0.98 }}
|
|
1021
|
+
motion:animate={{ opacity: 1, y: 0, scale: 1 }}
|
|
1022
|
+
motion:exit={{ opacity: 0, y: -4, scale: 0.98 }}
|
|
1023
|
+
>
|
|
1024
|
+
More information about this item.
|
|
1025
|
+
</section>
|
|
1026
|
+
)}
|
|
1027
|
+
</>
|
|
1028
|
+
)
|
|
1029
|
+
}
|
|
1030
|
+
|
|
1031
|
+
```
|
|
1032
|
+
|
|
1033
|
+
| Attribute | Behavior |
|
|
1034
|
+
| ------------------- | --------------------------------------------------------------------------------------------------- |
|
|
1035
|
+
| floating:reference | A DOM or virtual reference; null releases positioning. |
|
|
1036
|
+
| floating:placement | Floating UI placement, defaulting to bottom. |
|
|
1037
|
+
| floating:strategy | absolute or fixed, defaulting to absolute. |
|
|
1038
|
+
| floating:middleware | Standard Floating UI middleware such as offset, flip, and shift. |
|
|
1039
|
+
| floating:enabled | Defaults to true; set false when a mounted overlay is closed. |
|
|
1040
|
+
| floating:autoUpdate | Defaults to true; accepts observer options, or false for positioning only on SPA attribute updates. |
|
|
1041
|
+
|
|
1042
|
+
The capability waits for mount and ref publication before measuring, hides the overlay until its first position is available, and reconnects observers when its reference or observer options change. Updates from obsolete calculations are ignored. Server rendering omits floating attributes and starts no observers. Virtual references can supply getBoundingClientRect and an optional contextElement, as documented by Floating UI.
|
|
1043
|
+
|
|
1044
|
+
Give the overlay a fixed width or width: max-content and avoid margins so measurement remains stable. Floating owns position, left, top, and translate while enabled, and temporarily owns visibility until the first measurement. Do not animate translate through Motion or assign those positioning properties through another style writer on the same element. Floating restores original inline values and priorities when disabled, removed, or disposed. Keyboard behavior, focus management, dismissal, and top-layer mounting remain application responsibilities.
|
|
1045
|
+
|
|
1046
|
+
Reactive inline style changes preserve the current anchor position and Motion values while new measurements are pending. Temporary hiding uses !important until the first position is available, then restores the original inline visibility value and priority.
|
|
1047
|
+
|
|
1048
|
+
Position updates continue during Motion's retained exits, until physical disposal. If the reference itself moves through transforms, enable animationFrame in floating:autoUpdate. Run the package's example:floating script for a scrollable experiment with same-element scaling and rotation, moving anchors, viewport collisions, positioning strategies, and interrupted exits. Its test:browser:floating script checks actual Chromium geometry in both capability registration orders.
|
|
711
1049
|
|
|
712
1050
|
### Renderer extensions
|
|
713
1051
|
|
|
714
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
|
+
```
|