targetj 1.0.257 → 1.0.258

package/README.md

@@ -1,13 +1,17 @@
-# TargetJS: State as Destination, Code Order as UI Sequence
+# TargetJS: State Includes the Journey
 
-### Most frameworks are great at rendering state. TargetJS is designed for the journey between states.
+**Code order defines the UI sequence.**
+
+Most frameworks are great at rendering state. TargetJS is designed for the journey between states.
 
 **[targetjs.io](https://targetjs.io)** 
 [![MIT LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/livetrails/targetjs/blob/main/LICENSE) 
 [![Stars](https://img.shields.io/github/stars/livetrails/targetjs.svg)](https://github.com/livetrails/targetjs/stargazers)
 [![npm version](https://img.shields.io/npm/v/targetj.svg)](https://www.npmjs.com/package/targetj)
 
-TargetJS is a JavaScript UI framework that replaces the "State → Render" model with "State → Transition → Render". Transitions are part of state, which means they can adapt dynamically, be serialized mid-transition, and resume when the UI is restored.
+TargetJS is a JavaScript UI framework that replaces the "State → Render" model with "State → Transition → Render".
+
+Transitions are part of the state itself. This allows the entire UI, including an animation in progress, to be captured and later restored from the exact point at which it was saved.
 
 TargetJS also lets code order directly define the UI sequence. UI, transitions, API calls, event handling, and state are unified into self-contained Targets that chain together through Code-Ordered Reactivity.
 
@@ -16,15 +20,15 @@ It can be used as a full-featured framework or as a lightweight library alongsid
 
 ## What problems TargetJS solves
 
-**UI frameworks model the final result, not transition**
+**UI frameworks model the final result, not the transition**
 
 Traditional frameworks model the UI as a function of state: change state, re-render the UI. When state changes from A → B, the UI immediately jumps to B. The framework doesn’t naturally represent the journey from A → B. But modern, rich user experiences are more like: A → transition → B.
 
-TargetJS treats state as a destination. Values are not only assigned. They can be approached over time through configurable steps. This makes transitions a native part of state change. TargetJS also delivers CSS-level transition efficiency.
+TargetJS makes that transition part of the state change itself. Values are not limited to being assigned immediately. They can move toward their destination over configurable steps, intervals, and easing. Transitions therefore become a native part of the UI model rather than effects added after rendering. TargetJS also delivers CSS-level transition efficiency.
 
-More importantly, it unlocks a new level of flexibility. Because a target has its own lifecycle, its transitions can adapt dynamically. For example, pausing when an element leaves the screen or changing speed on scroll.
+Because each Target has its own lifecycle, transitions can also adapt dynamically. For example, pausing when an element leaves the screen or changing speed on scroll.
 
-And since the transition is part of the state, it can be serialized. This means a transition can survive a page flip and resume when the UI is restored.
+Since the transition belongs to the runtime state, the UI can be captured while a transition is in progress. That state can later be restored, allowing the transition to resume from the point at which it was saved.
 
 **Fragmentation across multiple mental models**
 
@@ -47,11 +51,12 @@ With its compact style, TargetJS makes the journey from A → B explicit and eff
 ## 🚀 Why TargetJS?
 
 1. Unified State: One single state. Transitions are state too.
-1. Adaptive Transitions: Transitions can pause, resume, change speed, and respond to input. They can also be serialized and continue, for instance, after a page flip.
+1. Adaptive Transitions: Transitions can pause, resume, change speed, and respond to input.
+1. Restorable UI: Capture the UI during a transition and later resume the complete state including the transition from the saved point.
 1. UI as Sequence: Code describes the UI story from top to bottom, just like the user experiences the interaction: "When this finishes, do that."
 1. Ultra-Compact: Minimal code, with no coordination variables.
 1. Zero Boilerplate Async: Targets handle waiting for nested asynchronous operations automatically.
-1. Animation by Default: High-performance animations are baked into the logic.
+1. Animation by Default: Turn value into high-performance animations simply by adding `steps`.
 
 ## ⚡ Quick Start (30 Seconds)
 
@@ -71,28 +76,36 @@ bounce → move → turn red → log
 
 Notice how the code reads in the same order as the UI sequence. The `$$` suffix makes each target wait for all preceding targets to complete.
 
-There is only one state, and transitions are part of that state. Although not shown here, the state can also be serialized mid-transition, for example, during a page flip and restored when the UI remounts.
+There is only one state, and the transitions are part of that state. Click the square while it is animating to save its current state. Click it again to restore the state and resume the animation from the exact point at which it was saved.
 
 ```javascript
-import { App } from "targetj";
+import { App, state } from "targetj";
 
 App({
   width: 100,
   height: 100,
   backgroundColor: "blue",
+  cursor: "pointer",
 
-  // Starts immediately: bounce.
-  scale: { value: [0.5, 1.2, 1], steps: 24, interval: 12 },
+  // Starts immediately.
+  scale: { value: [0.5, 1.2, 1], steps: 100 },
 
-  // Waits for scale to finish, then moves right.
-  x$$: { value: [0, 180], steps: 40, interval: 8 },
+  // $$ waits for the previous target to finish.
+  x$$: { value: [0, 180], steps: 100 },
 
-  // Waits for x to finish, then turns red.
-  backgroundColor$$: { value: "crimson", steps: 30, interval: 8 },
+  backgroundColor$$: {
+    value: "crimson",
+    steps: 100
+  },
 
-  // Waits for the color change to finish.
   done$$() {
     console.log("Sequence complete");
+  },
+
+  // Click once to save the state.
+  // Click again to restore it including animation progress.
+  onClick() {
+    state().toggle();
   }
 }).mount("#app");
 ```
@@ -140,15 +153,15 @@ A target can also be defined as an object with optional controls that manage its
 
 ### Compact Execution Syntax
 
-Target names can include special symbols that define when they execute. This provides a compact alternative to implementing the same behavior with callbacks.
+Target names can include special suffixes that determine when they execute. This provides a compact alternative to coordinating the same behavior with callbacks.
 
-| Symbol | Name | Behavior |
-|------|------|------|
-| `name` | Standard | Runs immediately in the order it appears. |
-| `name$` | Reactive | Runs every time the previous sibling target updates. Equivalent to using `on<PropertyName>Step()` or `onValueChange()` to activate the next target . |
-| `name$$` | Deferred | Runs only after the entire preceding target chain, including children, animations, and API calls, completes. Equivalent to using `onComplete()` to activate the next target. |
-| `_name` | Inactive | Does not run automatically. Trigger it manually with `.activateTarget()`. Equivalent to `{ active: false }`. |
+| Syntax   | Name     | Behavior                                                                                                                                                             |
+| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`   | Standard | Runs immediately in code order unless `active` is `false`.                                                                                                           |
+| `name$`  | Reactive | Runs whenever the preceding sibling Target updates. Similar to activating the next Target from `onValueChange()` or `on<PropertyName>Step()`.                        |
+| `name$$` | Deferred | Runs after the entire preceding Target chain—including children, animations, and API calls—has completed. Similar to activating the next Target from `onComplete()`. |
 
+To prevent a Target from running automatically, set `active: false` and activate it later with `.activateTarget()`.
 
 ## Examples: Like Button → Animated Like (in 3 Steps)
 
@@ -567,6 +580,8 @@ These targets update CSS properties and transforms:
 
 These can be animated simply by adding `steps`.
 
+For custom CSS, use the `css` Target.
+
 **Structure**
 
 These targets define the structure of the interface:

package/build/App.js

@@ -285,57 +285,61 @@ var getPager = function getPager() {
   var _tApp5;
   return (_tApp5 = tApp) === null || _tApp5 === void 0 ? void 0 : _tApp5.pager;
 };
-var state = function state() {
-  var _tApp6;
-  return (_tApp6 = tApp) === null || _tApp6 === void 0 ? void 0 : _tApp6.stateManager;
-};
 var getLoader = function getLoader() {
-  var _tApp7;
-  return (_tApp7 = tApp) === null || _tApp7 === void 0 ? void 0 : _tApp7.loader;
+  var _tApp6;
+  return (_tApp6 = tApp) === null || _tApp6 === void 0 ? void 0 : _tApp6.loader;
 };
 var fetch = function fetch(tmodel, url, query, cacheId) {
-  var _tApp8;
-  return (_tApp8 = tApp) === null || _tApp8 === void 0 || (_tApp8 = _tApp8.loader) === null || _tApp8 === void 0 ? void 0 : _tApp8.fetch(tmodel, url, query, cacheId);
+  var _tApp7;
+  return (_tApp7 = tApp) === null || _tApp7 === void 0 || (_tApp7 = _tApp7.loader) === null || _tApp7 === void 0 ? void 0 : _tApp7.fetch(tmodel, url, query, cacheId);
 };
 var fetchImage = function fetchImage(tmodel, src, cacheId) {
-  var _tApp9;
-  return (_tApp9 = tApp) === null || _tApp9 === void 0 || (_tApp9 = _tApp9.loader) === null || _tApp9 === void 0 ? void 0 : _tApp9.fetchImage(tmodel, src, cacheId);
+  var _tApp8;
+  return (_tApp8 = tApp) === null || _tApp8 === void 0 || (_tApp8 = _tApp8.loader) === null || _tApp8 === void 0 ? void 0 : _tApp8.fetchImage(tmodel, src, cacheId);
 };
 var getManager = function getManager() {
-  var _tApp10;
-  return (_tApp10 = tApp) === null || _tApp10 === void 0 ? void 0 : _tApp10.manager;
+  var _tApp9;
+  return (_tApp9 = tApp) === null || _tApp9 === void 0 ? void 0 : _tApp9.manager;
 };
 var getTargetManager = function getTargetManager() {
-  var _tApp11;
-  return (_tApp11 = tApp) === null || _tApp11 === void 0 ? void 0 : _tApp11.targetManager;
+  var _tApp10;
+  return (_tApp10 = tApp) === null || _tApp10 === void 0 ? void 0 : _tApp10.targetManager;
 };
 var getAnimationManager = function getAnimationManager() {
-  var _tApp12;
-  return (_tApp12 = tApp) === null || _tApp12 === void 0 ? void 0 : _tApp12.animationManager;
+  var _tApp11;
+  return (_tApp11 = tApp) === null || _tApp11 === void 0 ? void 0 : _tApp11.animationManager;
 };
 var getRunScheduler = function getRunScheduler() {
-  var _tApp13;
-  return (_tApp13 = tApp) === null || _tApp13 === void 0 ? void 0 : _tApp13.runScheduler;
+  var _tApp12;
+  return (_tApp12 = tApp) === null || _tApp12 === void 0 ? void 0 : _tApp12.runScheduler;
 };
 var getLocationManager = function getLocationManager() {
-  var _tApp14;
-  return (_tApp14 = tApp) === null || _tApp14 === void 0 ? void 0 : _tApp14.locationManager;
+  var _tApp13;
+  return (_tApp13 = tApp) === null || _tApp13 === void 0 ? void 0 : _tApp13.locationManager;
 };
 var getScreenWidth = function getScreenWidth() {
-  var _tApp$tRoot$val, _tApp15;
-  return (_tApp$tRoot$val = (_tApp15 = tApp) === null || _tApp15 === void 0 || (_tApp15 = _tApp15.tRoot) === null || _tApp15 === void 0 ? void 0 : _tApp15.val('screenWidth')) !== null && _tApp$tRoot$val !== void 0 ? _tApp$tRoot$val : 0;
+  var _tApp$tRoot$val, _tApp14;
+  return (_tApp$tRoot$val = (_tApp14 = tApp) === null || _tApp14 === void 0 || (_tApp14 = _tApp14.tRoot) === null || _tApp14 === void 0 ? void 0 : _tApp14.val('screenWidth')) !== null && _tApp$tRoot$val !== void 0 ? _tApp$tRoot$val : 0;
 };
 var getScreenHeight = function getScreenHeight() {
-  var _tApp$tRoot$val2, _tApp16;
-  return (_tApp$tRoot$val2 = (_tApp16 = tApp) === null || _tApp16 === void 0 || (_tApp16 = _tApp16.tRoot) === null || _tApp16 === void 0 ? void 0 : _tApp16.val('screenHeight')) !== null && _tApp$tRoot$val2 !== void 0 ? _tApp$tRoot$val2 : 0;
+  var _tApp$tRoot$val2, _tApp15;
+  return (_tApp$tRoot$val2 = (_tApp15 = tApp) === null || _tApp15 === void 0 || (_tApp15 = _tApp15.tRoot) === null || _tApp15 === void 0 ? void 0 : _tApp15.val('screenHeight')) !== null && _tApp$tRoot$val2 !== void 0 ? _tApp$tRoot$val2 : 0;
 };
 var getVisibles = function getVisibles() {
-  var _tApp17;
-  return (_tApp17 = tApp) === null || _tApp17 === void 0 || (_tApp17 = _tApp17.manager) === null || _tApp17 === void 0 ? void 0 : _tApp17.getVisibles();
+  var _tApp16;
+  return (_tApp16 = tApp) === null || _tApp16 === void 0 || (_tApp16 = _tApp16.manager) === null || _tApp16 === void 0 ? void 0 : _tApp16.getVisibles();
 };
 var getResizeLastUpdate = function getResizeLastUpdate() {
+  var _tApp17;
+  return (_tApp17 = tApp) === null || _tApp17 === void 0 ? void 0 : _tApp17.resizeLastUpdate;
+};
+var state = function state() {
   var _tApp18;
-  return (_tApp18 = tApp) === null || _tApp18 === void 0 ? void 0 : _tApp18.resizeLastUpdate;
+  var manager = (_tApp18 = tApp) === null || _tApp18 === void 0 ? void 0 : _tApp18.stateManager;
+  if (!manager) {
+    throw new Error("TargetJS state manager is not initialized.");
+  }
+  return manager;
 };
 var getTModelById = function getTModelById(id) {
   return App.tmodelIdMap[id];