@torpor/view 0.4.18 → 1.0.1

package/README.md

@@ -2,14 +2,22 @@
 
 Torpor's view library, for writing and mounting components.
 
-🚧 WARNING: WORK IN PROGRESS 🚧
-
 ## Installation
 
-Use `npm` (or your preferred package manager) to add Torpor to your project:
+You almost certainly want to use [torpor/build](../build), Torpor's
+full-stack framework, to build a site with Torpor:
+
+```bash
+npm init @torpor/build@latest my-project
+cd my-project
+npm install
+npm run dev
+```
+
+Otherwise, you can add Torpor's view layer directly to your project:
 
 ```bash
-npm install torpor
+npm install @torpor/view
 ```
 
 ## Features
@@ -25,7 +33,7 @@ npm install torpor
   - `@if` statement
   - `@for` loop
   - `@switch` statement
-  - `@await` statement for loading data from an async function
+  - `@await` async boundary (with `with` branch) for loading `$async` getters
   - And
     - `@replace` to re-run a section when a property changes
     - `@const` to declare a const variable in markup
@@ -37,7 +45,7 @@ npm install torpor
   - `$watch` to create a proxy that updates UI on property changes
   - `$cache` to cache proxy getter values that are expensive to update
   - `$run` to create an effect that is re-run when its dependencies change
-  - `$mount` to create an effect that runs after a component has been mounted
+  - `$onmount` to run a function once, after a component has been mounted
   - And
     - `$unwrap` to get the target object from the proxy
     - `$peek` to get the value of a target object without re-running effects on change
@@ -54,7 +62,7 @@ npm install torpor
 
 ### Not yet
 
-- Animation
+- Animation (beyond the in/out transitions above)
 
 ## A component
 
@@ -66,10 +74,16 @@ export default function Component($props: { name: string }) {
     // Use the $watch function to declare reactive state
     let $state = $watch({
         count: 0,
+        guessVersion: 0,
         get isEven() {
             return this.count % 2 === 0
         },
-        tasks: []
+        tasks: [],
+        // An async getter: $async tracks the promise and suspends reads until
+        // it resolves. Reading guessVersion makes it re-fetch on "Guess again".
+        get guesser() {
+            return $async(() => guessNumber($state.guessVersion === 0 ? 1000 : 500))
+        }
     })
 
     // Use the $run function to declare an effect that runs whenever its dependent state changes
@@ -80,7 +94,6 @@ export default function Component($props: { name: string }) {
     })
 
     // This is an async function
-    $state.guesser = guessNumber(1000)
     async function guessNumber(ms) {
         ...
     }
@@ -147,17 +160,19 @@ export default function Component($props: { name: string }) {
             </div>
 
             <h2>Await statements</h2>
-            <p>There is a construct for await/then/catch.</p>
+            <p>Read $async getters inside @await blocks; use @try/@catch for errors.</p>
             <div class="demo">
                 <p>Think of a number between 1 and 10...</p>
-                @await ($state.guesser) {
-                    <p>Hmm...</p>
-                } then (number) {
-                    <p>Is it {number}?</p>
+                @try {
+                    @await {
+                        <p>Is it {$state.guesser}?</p>
+                    } with {
+                        <p>Hmm...</p>
+                    }
                 } catch (ex) {
                     <p class="error">Something went wrong: {ex}!</p>
                 }
-                <button onclick={() => $state.guesser = guessNumber(500)}>
+                <button onclick={() => $state.guessVersion++}>
                     Guess again
                 </button>
             </div>
@@ -232,9 +247,19 @@ function TaskItem() {
 ## Mounting
 
 ```
-import mount from "torpor/view/mount";
+import { mount } from "@torpor/view";
 import Main from "./Main.torp";
 
 const root = document.getElementById("root");
 mount(root, Main);
 ```
+
+`mount` also takes optional props and slots:
+
+```
+mount(root, Main, { name: "World" });
+```
+
+Components can also be compiled for server side rendering (the `ServerComponent`
+type in `@torpor/view/ssr`), with `hydrate` and `unmount` from the main module
+taking over on the client.

package/dist/Cleanup-D0wvGW5d.d.cts

@@ -0,0 +1,9 @@
+//#region src/types/Cleanup.d.ts
+/**
+ * A function that may be returned from an effect, and is run before the effect
+ * is run or destroyed
+ */
+type Cleanup = () => void;
+//#endregion
+export { Cleanup as t };
+//# sourceMappingURL=Cleanup-D0wvGW5d.d.cts.map

package/dist/Cleanup-D0wvGW5d.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cleanup-D0wvGW5d.d.cts","names":[],"sources":["../src/types/Cleanup.ts"],"mappings":";;;;;KAIK"}

package/dist/Cleanup-D0wvGW5d.d.mts

@@ -0,0 +1,9 @@
+//#region src/types/Cleanup.d.ts
+/**
+ * A function that may be returned from an effect, and is run before the effect
+ * is run or destroyed
+ */
+type Cleanup = () => void;
+//#endregion
+export { Cleanup as t };
+//# sourceMappingURL=Cleanup-D0wvGW5d.d.mts.map

package/dist/Cleanup-D0wvGW5d.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cleanup-D0wvGW5d.d.mts","names":[],"sources":["../src/types/Cleanup.ts"],"mappings":";;;;;KAIK"}

package/dist/Component-0MH0zd-m.d.cts

@@ -0,0 +1,11 @@
+//#region src/types/SlotRender.d.ts
+type SlotRender = ($sparent: ParentNode, $sanchor: Node | null, $slot?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>) => void;
+//#endregion
+//#region src/types/Component.d.ts
+/**
+ * A component that can be mounted or hydrated
+ */
+type Component = ($parent: ParentNode, $anchor: Node | null, $props?: any, $context?: Record<PropertyKey, any>, $slots?: Record<string, SlotRender>) => void;
+//#endregion
+export { SlotRender as n, Component as t };
+//# sourceMappingURL=Component-0MH0zd-m.d.cts.map

package/dist/Component-0MH0zd-m.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Component-0MH0zd-m.d.cts","names":[],"sources":["../src/types/SlotRender.ts","../src/types/Component.ts"],"mappings":";KAAK,cACJ,UAAU,YACV,UAAU,aACV,QAAQ,OAAO,mBACf,WAAW,OAAO;;;;;;KCCd,aACJ,SAAS,YACT,SAAS,aAIT,cACA,WAAW,OAAO,mBAClB,SAAS,eAAe"}

package/dist/Component-0MH0zd-m.d.mts

@@ -0,0 +1,11 @@
+//#region src/types/SlotRender.d.ts
+type SlotRender = ($sparent: ParentNode, $sanchor: Node | null, $slot?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>) => void;
+//#endregion
+//#region src/types/Component.d.ts
+/**
+ * A component that can be mounted or hydrated
+ */
+type Component = ($parent: ParentNode, $anchor: Node | null, $props?: any, $context?: Record<PropertyKey, any>, $slots?: Record<string, SlotRender>) => void;
+//#endregion
+export { SlotRender as n, Component as t };
+//# sourceMappingURL=Component-0MH0zd-m.d.mts.map

package/dist/Component-0MH0zd-m.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Component-0MH0zd-m.d.mts","names":[],"sources":["../src/types/SlotRender.ts","../src/types/Component.ts"],"mappings":";KAAK,cACJ,UAAU,YACV,UAAU,aACV,QAAQ,OAAO,mBACf,WAAW,OAAO;;;;;;KCCd,aACJ,SAAS,YACT,SAAS,aAIT,cACA,WAAW,OAAO,mBAClB,SAAS,eAAe"}

package/dist/Effect-BTKurOpr.d.mts

@@ -0,0 +1,381 @@
+import { t as Cleanup } from "./Cleanup-D0wvGW5d.mjs";
+//#region src/types/constants.d.ts
+/**
+ * The type of a Signal object.
+ */
+declare const SIGNAL_TYPE = 0;
+/**
+ * The type of a Computed object.
+ */
+declare const COMPUTED_TYPE = 1;
+/**
+ * The type of an Effect object.
+ */
+declare const EFFECT_TYPE = 2;
+//#endregion
+//#region src/types/ProxySignal.d.ts
+/**
+ * A value that causes dependent Computeds and Effects to be re-run. Our signals
+ * are implemented as object properties.
+ */
+interface ProxySignal {
+  /**
+   * SIGNAL.
+   */
+  type: typeof SIGNAL_TYPE;
+  /**
+   * The first Computed or Effect that is triggered when this property is changed.
+   */
+  firstTarget: Subscription | null;
+  /**
+   * When signals have been changed in a batch, this is the next changed signal.
+   */
+  nextSignalToUpdate: ProxySignal | null;
+  /**
+   * The name of the property, for debugging.
+   */
+  name?: string;
+}
+//#endregion
+//#region src/types/Subscription.d.ts
+/**
+ * A subscription that connects a source Signal or Computed to a target Computed
+ * or Effect.
+ */
+interface Subscription {
+  /**
+   * The source Signal or Computed.
+   */
+  source: ProxySignal | Computed;
+  /**
+   * The target Computed or Effect.
+   */
+  target: Computed | Effect;
+  /**
+   * The next source subscription. After the targets have been re-run, we run
+   * through sources to remove any that weren't re-used.
+   */
+  nextSource: Subscription | null;
+  /**
+   * The next target subscription. When the source is changed, we run through
+   * targets to mark them dirty and possibly re-run them.
+   */
+  nextTarget: Subscription | null;
+  /**
+   * The previous target subscription. We remove subscriptions by looping
+   * through the sources list, so we only need to know the next source, but we
+   * need to know both the next and previous targets to properly update the
+   * targets list.
+   */
+  previousTarget: Subscription | null;
+  /**
+   * Whether this subscription is active. At the start of a re-run, all
+   * subscriptions are marked inactive and marked active if re-used. If not
+   * re-used, they are removed after the run.
+   */
+  active: boolean;
+  /**
+   * Whether the subscription's target may need to be recalculated (if any of
+   * its sources have changed).
+   */
+  recalc: boolean;
+  /**
+   * The name of the subscription, for debugging.
+   */
+  name?: string;
+}
+//#endregion
+//#region src/types/Computed.d.ts
+/**
+ * A computed value that is lazily refreshed when accessed from an Effect or
+ * another Computed. Our computed values are implemented as property getter
+ * functions.
+ */
+interface Computed<T = any> {
+  /**
+   * COMPUTED.
+   */
+  type: typeof COMPUTED_TYPE;
+  /**
+   * True if this computed was created by `$async` (an async getter whose run
+   * returns a Promise and suspends readers until it resolves). False for
+   * plain `$cache` computeds. `$refresh` targets only `isAsync` computeds,
+   * so re-running a `$cache` getter (which would recompute a sync value for
+   * no reason) never happens.
+   */
+  isAsync: boolean;
+  /**
+   * The cached, computed value.
+   */
+  value: T;
+  /**
+   * The getter function to run to access this computed's value.
+   */
+  run: () => T;
+  /**
+   * The first signal or computed that causes this effect to be run.
+   */
+  firstSource: Subscription | null;
+  /**
+   * The first computed or effect that is triggered when this property is changed.
+   */
+  firstTarget: Subscription | null;
+  /**
+   * Whether the computed may need to be recalculated (if any of its sources
+   * have changed). We store this on the computed (as well as its
+   * subscription) so we don't have to check the sources every time (which may
+   * be expensive).
+   */
+  recalc: boolean;
+  /**
+   * Used to track cycles.
+   */
+  running: boolean;
+  /**
+   * True if the computed encountered an exception in its last run.
+   */
+  didError: boolean;
+  /**
+   * True if the computed's last run returned a pending Promise. Set by
+   * `$async`; read by the proxy get trap to suspend readers. Cleared when
+   * the promise resolves (or rejects), at which point dependents are
+   * propagated through the reactive graph.
+   */
+  didSuspend: boolean;
+  /**
+   * Generation counter for `$async`'s stale-resolve guard. Each run of an
+   * `$async` computed increments this; the `.then` handler captures the
+   * generation and ignores resolves from stale (previous) runs. Unused by
+   * plain `$cache` computeds.
+   */
+  generation: number;
+  /**
+   * True once an `$async` computed's promise has resolved or rejected at
+   * least once. Used by `$pending` to distinguish a first load (never
+   * resolved) from a refresh. Monotonic — once true it stays true across
+   * subsequent re-suspends. Unused by plain `$cache` computeds.
+   */
+  hasResolved: boolean;
+  /**
+   * True when the last settled result of an `$async` computed was a
+   * rejection. Set by the `.then` reject handler, cleared by the resolve
+   * handler, which also clears `staleValue` — a retry-after-error
+   * re-suspend must not hand the previous error to readers as "stale
+   * content" (it renders as a raw value, bypassing the error boundary).
+   * Unused by plain `$cache` computeds.
+   */
+  lastErrored: boolean;
+  /**
+   * True when the current suspend is a "bare refresh" — a re-fetch with no
+   * tracked dependency change, i.e. a silent `$refresh(fn, { silent: true })`
+   * (background revalidation), per ASYNC.md §7.4's quiet-on-refresh rule.
+   * `$pending` reads this to stay quiet (return `false`) on silent refreshes,
+   * matching Solid's stale-while-revalidate default.
+   *
+   * Captured at suspend time inside `$async`'s run: a suspend is quiet iff
+   * the computed has resolved before (`hasResolved`) AND the run was NOT
+   * source-driven (`recalc === false`, i.e. not triggered by `checkComputed`
+   * and not a loud `$refresh`). First loads are always loud (`hasResolved`
+   * is false); dependency-change refreshes and loud `$refresh` calls are
+   * always loud (`recalc` is true).
+   */
+  suspendQuiet: boolean;
+  /**
+   * The previously resolved value, retained across a refresh suspend for
+   * stale-while-revalidate (ASYNC.md §6.2). Maintained by `$async`'s
+   * generation-guarded settle handlers — set on resolve, cleared on
+   * rejection — so it always holds the last RESOLVED value, never a
+   * superseded run's in-flight promise (rapid prop changes would otherwise
+   * render "[object Promise]"). Read by `suspendRead` so readers keep
+   * displaying the old value instead of a placeholder while the new promise
+   * is in flight. `undefined` on first load (never resolved) and for plain
+   * `$cache` computeds (which never suspend, so `suspendRead` is never
+   * reached for them).
+   */
+  staleValue: any;
+  /**
+   * A subscription to roll back to when recursively updating signal targets.
+   */
+  rollback: Subscription | null;
+  /**
+   * The name of the computed property, for debugging.
+   */
+  name?: string;
+}
+//#endregion
+//#region src/types/ErrorBoundary.d.ts
+/**
+ * An error boundary created by `t_run_try` (`@try`/`@catch` groups and
+ * top-level `@error` blocks). Stored on the boundary's `Region` so that
+ * `routeEffectError` can find the nearest enclosing boundary by walking the
+ * region chain from a failing effect's owning region.
+ */
+interface ErrorBoundary {
+  /**
+   * The error to render in the catch branch: set either by a synchronous
+   * build throw (handled internally by `runTry`) or by an effect error
+   * routed from `triggerEffects`.
+   */
+  error: any;
+  /**
+   * True when an effect error has been routed here and the boundary's
+   * effect needs to (re-)render the catch branch with `error`.
+   */
+  hasError: boolean;
+  /**
+   * The boundary's control effect. Re-run by `routeEffectError` to render
+   * the catch branch for a routed error.
+   */
+  effect: Effect | null;
+  /**
+   * Source signals held while the catch branch is showing, so the boundary
+   * re-runs (and re-attempts the try branch) when they change. Captured
+   * from the routed erroring effect's subscriptions — reads wrapped in
+   * nested `$run` effects (text/attribute interpolation) are tracked by
+   * those effects, not the boundary, so without holding them the catch
+   * branch would never recover.
+   */
+  heldSignals: (ProxySignal | Computed)[] | null;
+}
+//#endregion
+//#region src/types/Region.d.ts
+interface Region {
+  startNode: ChildNode | null;
+  endNode: ChildNode | null;
+  previousRegion: Region | null;
+  nextRegion: Region | null;
+  depth: number;
+  /**
+   * Animations that are currently running in the region, and which need to
+   * awaited or canceled before it is removed
+   */
+  animations: Set<Animation> | null;
+  /**
+   * The name of the region, for debugging.
+   */
+  name?: string;
+  /**
+   * Effects that are owned by this region.
+   */
+  effects: Effect[];
+  /**
+   * Set by `t_run_try` (`@try`/`@catch` groups and top-level `@error`
+   * blocks) when a catch/error branch exists. `routeEffectError` walks the
+   * region chain from a failing effect's owning region and routes the error
+   * to the nearest boundary.
+   */
+  errorBoundary?: ErrorBoundary;
+  /**
+   * Generation counter used by `runControl` to detect stale effects. Each
+   * `t_run_control` call increments this; effects from previous calls check
+   * it and skip execution if they're no longer current. Set ad-hoc today;
+   * declared here so the casts can be dropped.
+   */
+  generation?: number;
+  /**
+   * Set by `clearRegion` when a region is released but may be reused,
+   * forcing the next `t_run_branch` to re-render even at the same branch
+   * index.
+   */
+  recreate?: boolean;
+}
+//#endregion
+//#region src/types/Effect.d.ts
+/**
+ * An effect that is run and re-run when the properties it depends on change.
+ */
+interface Effect {
+  /**
+   * EFFECT.
+   */
+  type: typeof EFFECT_TYPE;
+  /**
+   *
+   * @returns An optional cleanup function, to run when the effect is re-run or disposed.
+   */
+  run: () => Cleanup | void;
+  /**
+   * The optional cleanup function that may have been returned from the run function.
+   */
+  cleanup: Cleanup | void;
+  /**
+   * The first signal or computed that causes this effect to be run.
+   */
+  firstSource: Subscription | null;
+  nextEffect: Effect | null;
+  /**
+   * The number of children of this effect.
+   */
+  extent: number;
+  /**
+   * True while the effect is linked into the current run queue. Reset as
+   * soon as the effect is processed, so a signal write later in the same
+   * flush — or during the effect's own run — can correctly re-queue it.
+   */
+  queued: boolean;
+  /**
+   * True if the effect encountered an exception in its last run.
+   */
+  didError: boolean;
+  /**
+   * True if the effect's last run read a suspended (`didSuspend`) computed.
+   * Set by the proxy get trap's suspend-taint propagation and reset at the
+   * start of each run. Read by `triggerEffects` to detect a crash that may
+   * have been caused by a pending value.
+   */
+  didSuspend: boolean;
+  /**
+   * The suspended computeds read during the effect's current (or last
+   * failed) run, recorded by `suspendRead`. Cleared at the start of each
+   * run. Read by `triggerEffects` when a run throws with no error boundary
+   * to handle it: the effect is re-subscribed to these so the promise's
+   * resolve re-runs it, turning a crash on a pending read's `undefined`
+   * into a self-healing one-off error instead of a permanently dead
+   * effect.
+   */
+  suspendSources?: Set<Computed> | null;
+  /**
+   * The name of the effect, for debugging.
+   */
+  name?: string;
+  /**
+   * The region that was active when this effect was created, and which
+   * owns its cleanup. Used by `routeEffectError` to walk to the nearest
+   * enclosing error boundary.
+   */
+  region?: Region | null;
+  /**
+   * The effect's source signals, captured just before `clearSources` runs
+   * after a failed run (see `runEffect`). Read by `routeEffectError` so an
+   * error boundary can hold the subscriptions needed for recovery.
+   */
+  errorSources?: (ProxySignal | Computed)[] | null;
+  /**
+   * True when this effect wraps a `$onmount`/`onmount` callback (created by
+   * `flushMountEffects`). Mount callbacks run once per region mount and
+   * must NOT be force re-run by the keyed-list reconciler's
+   * `rerunEffectsOnRegion` — doing so would re-fire `onmount` on every item
+   * update. Their bodies are also run untracked, so they never gain signal
+   * subscriptions and never re-run reactively.
+   */
+  isMountEffect?: boolean;
+  /**
+   * When set, a bitmask of the `@for` loop-variable positions that this
+   * effect's body reads (computed at compile time by scanning for
+   * substituted data-bag paths). Bit N corresponds to the Nth for-var.
+   * Used by `rerunRegionEffects` on the no-proxy keyed-list path to skip
+   * effects that don't depend on any of the changed for-vars via a single
+   * bitwise AND.
+   *
+   * - `undefined`: dependency info not available — re-run unconditionally
+   *   (backward-compatible behaviour for effects emitted outside the
+   *   for-body builders, e.g. mount-time animations).
+   * - `0`: the effect reads no for-vars at all — skip on any field change
+   *   (it has its own signal subscriptions for other reactive state).
+   * - `> 0`: re-run only when `(forVarMask & changedMask) !== 0`.
+   */
+  forVarMask?: number;
+}
+//#endregion
+export { ProxySignal as i, Region as n, Computed as r, Effect as t };
+//# sourceMappingURL=Effect-BTKurOpr.d.mts.map

package/dist/Effect-BTKurOpr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Effect-BTKurOpr.d.mts","names":[],"sources":["../src/types/constants.ts","../src/types/ProxySignal.ts","../src/types/Subscription.ts","../src/types/Computed.ts","../src/types/ErrorBoundary.ts","../src/types/Region.ts","../src/types/Effect.ts"],"mappings":";;;;;cAGa;;;;cAKA;;;;cAKA;;;;;;;UCNY;;;;EAIxB,aAAa;;;;EAKb,aAAa;;;;EAKb,oBAAoB;;;;EAKpB;;;;;;;;UClBwB;;;;EAIxB,QAAQ,cAAc;;;;EAKtB,QAAQ,WAAW;;;;;EAMnB,YAAY;;;;;EAMZ,YAAY;;;;;;;EAQZ,gBAAgB;;;;;;EAOhB;;;;;EAMA;;;;EAKA;;;;;;;;;UC/CwB,SAAS;;;;EAIjC,aAAa;;;;;;;;EASb;;;;EAKA,OAAO;;;;EAKP,WAAW;;;;EAKX,aAAa;;;;EAKb,aAAa;;;;;;;EAQb;;;;EAKA;;;;EAKA;;;;;;;EAQA;;;;;;;EAQA;;;;;;;EAQA;;;;;;;;;EAUA;;;;;;;;;;;;;;;EAgBA;;;;;;;;;;;;;EAcA;;;;EAKA,UAAU;;;;EAKV;;;;;;;;;;UC3HwB;;;;;;EAMxB;;;;;EAMA;;;;;EAMA,QAAQ;;;;;;;;;EAUR,cAAc,cAAc;;;;UCnCJ;EACxB,WAAW;EACX,SAAS;EAET,gBAAgB;EAChB,YAAY;EACZ;;;;;EAMA,YAAY,IAAI;;;;EAKhB;;;;EAKA,SAAS;;;;;;;EAQT,gBAAgB;;;;;;;EAQhB;;;;;;EAOA;;;;;;;UCtCwB;;;;EAIxB,aAAa;;;;;EAMb,WAAW;;;;EAKX,SAAS;;;;EAKT,aAAa;EAKb,YAAY;;;;EAKZ;;;;;;EAOA;;;;EAKA;;;;;;;EAQA;;;;;;;;;;EAWA,iBAAiB,IAAI;;;;EAKrB;;;;;;EAOA,SAAS;;;;;;EAOT,gBAAgB,cAAc;;;;;;;;;EAU9B;;;;;;;;;;;;;;;;EAiBA"}