@solidrt/core 0.0.57 → 0.0.59

package/src/types.d.ts

@@ -461,6 +461,23 @@ export interface LineGeometryProps extends PositionProps {
 /** A cubic-bezier timing curve: a CSS name or [x1, y1, x2, y2] control values. */
 export type TransitionCurve = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number]
 
+/**
+ * The object form of `from`/`exit`: the endpoint value plus that
+ * direction's own motion, so an ease-out enter pairs with an ease-in exit
+ * instead of playing the entry's curve backwards. Every field but `value`
+ * is optional and falls back to the entry's (`delay` included, so a
+ * staggered list needs no change), except that naming a `curve` or a
+ * `bounce` decides the kind outright: `{ value: 0, curve: "ease-in" }` on a
+ * spring entry is a tween of the entry's duration.
+ */
+export interface TransitionEndpoint {
+  value: number | string
+  duration?: number
+  curve?: TransitionCurve
+  bounce?: number
+  delay?: number
+}
+
 /**
  * A perceptual spring - the default kind: a bare `{ duration }` is a
  * critically damped spring. `duration` (ms) is the perceptual settling
@@ -479,20 +496,26 @@ export interface TransitionSpring {
    * Mount-time enter animation: at the element's first attach the property
    * snaps to this value and animates to the value it mounted with. Numbers
    * for the scalar properties; the color property takes a CSS color string
-   * or packed number. Per-property entries only (not under `all`); a later
-   * move or reorder re-runs nothing.
+   * or packed number, or a {@link TransitionEndpoint} giving the enter its
+   * own curve, duration, bounce or delay. Per-property entries only (not
+   * under `all`); a later move or reorder re-runs nothing.
    */
-  from?: number | string
+  from?: number | string | TransitionEndpoint
   /**
-   * Removal exit animation: an unmounted element stays visible, animates
-   * the property to this value (honoring `delay`), and is freed when its
-   * exit animations settle. Same value forms as `from`, per-property only.
-   * A move never plays it, the exiting element is hit-test invisible, its
-   * whole subtree stays painted with it, and no onTransitionEnd fires (the
-   * component is already disposed). An attached element keeps its layout
-   * slot until the exit finishes.
+   * Removal exit animation: when an element unmounts, every `exit`
+   * declared on it or under it animates its property to this value
+   * (honoring `delay`), and the unmounted element stays visible, subtree
+   * and all, until the last of them settles, then frees. Same value forms
+   * as `from`, per-property only. A move never plays it, the exiting
+   * subtree is hit-test invisible, and no onTransitionEnd fires (the
+   * components are already disposed). An exiting element leaves the layout
+   * flow at once: its siblings reflow as if it were gone, and it is painted
+   * at its last box, which follows its parent's moves but not the parent's
+   * own reflow. The {@link TransitionEndpoint} form gives the exit its own
+   * motion: an ease-out enter reads wrong played backwards, so pair it with
+   * `exit: { value, curve: "ease-in" }`.
    */
-  exit?: number | string
+  exit?: number | string | TransitionEndpoint
 }
 
 /**
@@ -511,20 +534,26 @@ export interface TransitionTween {
    * Mount-time enter animation: at the element's first attach the property
    * snaps to this value and animates to the value it mounted with. Numbers
    * for the scalar properties; the color property takes a CSS color string
-   * or packed number. Per-property entries only (not under `all`); a later
-   * move or reorder re-runs nothing.
+   * or packed number, or a {@link TransitionEndpoint} giving the enter its
+   * own curve, duration, bounce or delay. Per-property entries only (not
+   * under `all`); a later move or reorder re-runs nothing.
    */
-  from?: number | string
+  from?: number | string | TransitionEndpoint
   /**
-   * Removal exit animation: an unmounted element stays visible, animates
-   * the property to this value (honoring `delay`), and is freed when its
-   * exit animations settle. Same value forms as `from`, per-property only.
-   * A move never plays it, the exiting element is hit-test invisible, its
-   * whole subtree stays painted with it, and no onTransitionEnd fires (the
-   * component is already disposed). An attached element keeps its layout
-   * slot until the exit finishes.
+   * Removal exit animation: when an element unmounts, every `exit`
+   * declared on it or under it animates its property to this value
+   * (honoring `delay`), and the unmounted element stays visible, subtree
+   * and all, until the last of them settles, then frees. Same value forms
+   * as `from`, per-property only. A move never plays it, the exiting
+   * subtree is hit-test invisible, and no onTransitionEnd fires (the
+   * components are already disposed). An exiting element leaves the layout
+   * flow at once: its siblings reflow as if it were gone, and it is painted
+   * at its last box, which follows its parent's moves but not the parent's
+   * own reflow. The {@link TransitionEndpoint} form gives the exit its own
+   * motion: an ease-out enter reads wrong played backwards, so pair it with
+   * `exit: { value, curve: "ease-in" }`.
    */
-  exit?: number | string
+  exit?: number | string | TransitionEndpoint
 }
 
 /**
@@ -571,9 +600,12 @@ export type TransitionPropName =
   | "radius"
   | "color"
 
-/** Payload of onTransitionEnd: which animated property finished. */
+/**
+ * Payload of onTransitionEnd: which animated property finished. `"layout"`
+ * is the layout slide settling on its box.
+ */
 export interface TransitionEndEvent {
-  property: TransitionPropName
+  property: TransitionPropName | "layout"
 }
 
 export interface TransitionProps {
@@ -610,6 +642,20 @@ export interface TransitionProps {
          * lifecycle are unaffected. Adds on top of a per-entry `delay`.
          */
         stagger?: number
+        /**
+         * Layout slide: when a layout moves this element (a row removed
+         * above it, one inserted, a `<For>` reorder, a resize), it slides
+         * from where it was painted to its new box on this motion instead
+         * of jumping, and is hit-tested where it is drawn. A reflow
+         * mid-slide retargets (a spring keeps its velocity). Its first
+         * layout, a reparent and a `display: none` toggle snap. The slide is
+         * parent-relative: a parent that moves carries its children at
+         * once, so declare it on every level that should glide. `true`
+         * borrows the `all` entry's motion (an error without one); `all`
+         * alone never slides. Position only today: a size change snaps.
+         * Settles with onTransitionEnd property `"layout"`.
+         */
+        layout?: Omit<TransitionSpring, "from" | "exit"> | Omit<TransitionTween, "from" | "exit"> | TransitionShorthand | boolean
       } & {
         [P in TransitionPropName]?: Transition
       })

package/src/video.ts

@@ -41,7 +41,7 @@ export type VideoStream = {
 }
 
 /**
- * Opens a video file (MP4, H.264 + AAC) and exposes it as reactive signals:
+ * Opens a video file (MP4, VP9 + AAC) and exposes it as reactive signals:
  * read texture() in JSX and the frames appear once playback starts. Closes
  * automatically when the reactive owner is disposed (e.g. the component
  * unmounts). For imperative use, call open() from "flux:video" directly.

package/src/window.ts

@@ -2,18 +2,152 @@ import { createSignal, getOwner, onCleanup, onSettled, runWithOwner, flush } fro
 import { requestFrame, setPointerLock } from "flux:rendertree"
 import { renderFrame } from "srt:render"
 import { on, once } from "srt:events"
-import { exit } from "srt:app"
+import { exit as nativeExit, background as nativeBackground } from "srt:app"
+import { platform } from "flux:process"
 import { getEventHandler, focusedNode, setFocus, activateTextInput, setInterestRoot } from "./core"
 import { scanForOrphans, getNodePath } from "./renderer"
 
+// ------ Lifecycle hooks ----------------
+
+// A suspend or quit handler; the runtime waits for a returned promise.
+export type LifecycleHandler = () => void | Promise<void>
+
+// How long exit() waits for the quit handlers before leaving anyway. The
+// platform-initiated ends (window close, Android onDestroy) are bounded by the
+// runtime's own deadline instead; this one only keeps a hung handler from
+// pinning an app that asked to leave.
+const EXIT_HOOK_DEADLINE_MS = 2000
+
+let suspendHandlers: LifecycleHandler[] = []
+let quitHandlers: LifecycleHandler[] = []
+// The suspend dispatch still in flight, if any: a quit that follows a
+// suspend (a finishing Android activity runs onPause, then onDestroy) waits
+// for it before its own handlers, so the persist that suspend started lands
+// before the process ends.
+let pendingSuspend: Promise<void> | null = null
+
+function registerLifecycle(list: LifecycleHandler[], fn: LifecycleHandler) {
+  list.push(fn)
+  let cleanup = () => {
+    let i = list.lastIndexOf(fn)
+    if (i >= 0) list.splice(i, 1)
+  }
+  if (getOwner()) onCleanup(cleanup)
+  return cleanup
+}
+
+// Runs every handler (a throw counts as a rejected promise) and settles once
+// all of them have, logging the failures: one handler's error must not cut
+// another's write short.
+function settleHandlers(name: string, list: LifecycleHandler[]): Promise<void> {
+  let results = [...list].map((fn) => {
+    try {
+      return Promise.resolve(fn())
+    } catch (err) {
+      return Promise.reject(err)
+    }
+  })
+  return Promise.allSettled(results).then((settled) => {
+    for (let r of settled) {
+      if (r.status === "rejected") console.error(`Error in ${name} handler:`, r.reason)
+    }
+  })
+}
+
+function dispatchSuspend(): Promise<void> {
+  let p = settleHandlers("onSuspend", suspendHandlers).finally(() => {
+    if (pendingSuspend === p) pendingSuspend = null
+  })
+  pendingSuspend = p
+  return p
+}
+
+function dispatchQuit(): Promise<void> {
+  let inflight = pendingSuspend ?? Promise.resolve()
+  return inflight.then(() => settleHandlers("onQuit", quitHandlers))
+}
+
+// The runtime asks through the event bus and waits for `done()`: the
+// platform is held open (or its close budget spent) until then, so this must
+// answer exactly once, whatever the handlers do. Subscribed at module load:
+// core is always present, and a hook nobody listens to would leave the
+// runtime waiting out its deadline on every close.
+on("suspend", (e: { done: () => void }) => {
+  dispatchSuspend().then(e.done, e.done)
+})
+on("quit", (e: { done: () => void }) => {
+  dispatchQuit().then(e.done, e.done)
+})
+
+/**
+ * Calls `fn` when the app is being suspended and may be killed without
+ * further notice: the user switches away on Android or iOS (the platform's
+ * "will enter background" moment). Never fires on desktop, where a minimized
+ * app is not killed. This is the moment to persist session state - a file, a
+ * database row, an HTTP request - so a later launch can pick the session up;
+ * the runtime holds the platform open and waits for a returned promise, up to
+ * its deadline (about ten seconds, platform-dependent), then lets the
+ * platform proceed. Nothing decides for you whether to restore afterwards;
+ * that is the app's call.
+ *
+ * Returns a cleanup function; also auto-cleans within an owned scope.
+ */
+export function onSuspend(fn: LifecycleHandler) {
+  return registerLifecycle(suspendHandlers, fn)
+}
+
+/**
+ * Calls `fn` when this app instance is ending: `exit()` (including the
+ * default action of an unprevented `back` on desktop), the desktop window
+ * closing, the Android activity finishing. Not when the app goes to the
+ * background (`background()`, or back at the root on Android). Not a last chance to save - on mobile the
+ * suspend hook has already run, and a user who quits usually does not want
+ * a session kept - but the place for work that needs a real close, and the
+ * runtime waits for a returned promise up to its deadline (well under a
+ * second on Android, where the platform's close budget is fixed; a couple of
+ * seconds on desktop). A force quit or a crash gives no signal on any
+ * platform.
+ *
+ * Returns a cleanup function; also auto-cleans within an owned scope.
+ */
+export function onQuit(fn: LifecycleHandler) {
+  return registerLifecycle(quitHandlers, fn)
+}
+
+/**
+ * Ends the current app: back to the player in a dev client, quitting when
+ * standalone or at the player itself (on Android the activity finishes, so
+ * the next launch starts fresh). The default action of an unprevented `back`
+ * event on desktop; call it directly to exit programmatically, e.g. after
+ * intercepting back for an unsaved-changes dialog. Runs the `onQuit`
+ * handlers first and leaves once their promises settle (or the deadline
+ * passes); returns immediately.
+ */
+export function exit() {
+  let deadline = new Promise<void>((resolve) => setTimeout(resolve, EXIT_HOOK_DEADLINE_MS))
+  Promise.race([dispatchQuit(), deadline]).then(nativeExit, nativeExit)
+}
+
 /**
- * Leaves the current app, unconditionally: back to the player in a dev
- * client, quitting when standalone or at the player itself (on Android the
- * client backgrounds instead of dying). The default action of an unprevented
- * `back` event; call it directly to exit programmatically, e.g. after
- * intercepting back for an unsaved-changes dialog.
+ * Leaves the current app without ending it: back to the player in a dev
+ * client; otherwise the OS takes the app to the background - on Android the
+ * task moves behind the others with the process kept, on desktop the window
+ * minimizes. The default action of an unprevented `back` event on Android,
+ * where that is what the system itself does at the root of an app. No
+ * `onQuit` runs (the app is not ending); `onSuspend` fires on Android on the
+ * way, as for any background.
  */
-export { exit }
+export function background() {
+  nativeBackground()
+}
+
+// The default action of an unprevented back event: what the platform itself
+// does at the root of an app. Android backgrounds (since Android 12);
+// everywhere else back at the root ends the app.
+function backDefault() {
+  if (platform === "android") background()
+  else exit()
+}
 
 // ------ Pointer routing -----------------
 
@@ -301,8 +435,10 @@ let backHandlers: ((e: BackEvent) => void)[] = []
  * desktop dev chord). Call `e.preventDefault()` when back means in-app
  * navigation right now (close a modal, previous screen); unprevented, the
  * event passes to the handler registered before this one, and if none of them
- * prevents it either, to the default action: exit(). Apps without a handler
- * exit on back everywhere, which is the correct zero-effort default.
+ * prevents it either, to the default action: what the platform does at the
+ * root of an app - `background()` on Android, `exit()` elsewhere. Apps
+ * without a handler get the platform's behavior, which is the correct
+ * zero-effort default.
  *
  * Handlers form a stack: the most recently registered runs first and the first
  * to prevent ends the dispatch, so each screen or overlay owns one step of the
@@ -516,7 +652,7 @@ export function attachWindow(nodeId: number) {
       // Top of the stack down, stopping as soon as one takes the event.
       let stack = [...backHandlers]
       for (let i = stack.length - 1; i >= 0 && !prevented; i--) stack[i]!(e)
-      if (!prevented) exit()
+      if (!prevented) backDefault()
     })
 
     unsubTextInput = on("textInput", (e: any) => {