targetj 1.0.224 → 1.0.226

package/README.md

@@ -1,4 +1,4 @@
-# TargetJS: UI Development as a Sequence
+# TargetJS: State as Destination, UI as Sequence
 
 **[targetjs.io](https://targetjs.io)** 
 [![MIT LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/livetrails/targetjs/blob/main/LICENSE) 
@@ -10,19 +10,31 @@ TargetJS is a high-performance JavaScript UI framework with ultra-compact syntax
 It can be used as a full-featured framework or as a lightweight library alongside other frameworks. It is also a highly performant web framework, as shown in the [framework benchmark](https://krausest.github.io/js-framework-benchmark/current.html).
 
 
-## The Philosophy Behind TargetJS
+## What problems TargetJS solves
 
-Traditional frameworks model the UI as a function of state: change state, re-render the UI. When state changes from A to B, the UI immediately jumps to B. The framework doesn’t naturally represent the *journey* from A to B. But modern, rich user experiences are journeys, not jumps. They are built on sequences that unfold over time. For example:
+**UI frameworks model the final result, not transition**
 
-> Click → Animate button → Chain secondary animation → Fetch data → Render list → Animate items → Pause → Animate an important item
+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 is built for this reality. Instead of managing complex flags, your code structure mirrors these sequences directly.
+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 rather than an afterthought. TargetJS also delivers CSS-level transition efficiency.
 
-It achieves this through Targets. A Target is a self-contained unit that merges data (fields) and logic (methods) into a single reactive block. Each Target has its own internal state, timing, and lifecycle, acting like a living cell within your app. By simply ordering them in your code, you create complex asynchronous workflows without async/await or .then() chains. 
+**Fragmentation across multiple mental models**
 
-In addition, efficient animation is built directly into the framework using the Web Animations API, delivering CSS-level efficiency.
+In many applications, state, animation, events, loading, timing, and callbacks are all handled through separate concepts or APIs. This creates glue code and a mental split between them.
 
-By adopting a compact style, TargetJS makes the journey from A to B efficient and explicit, with significantly less code than traditional frameworks.
+TargetJS unifies them under one concept and one model. Methods and fields are unified and both become reactive units with their own state, lifecycle, timing, execution conditions, looping, and callbacks. This shifts fields from passive values to active participants, reducing boilerplate and keeping application logic consolidated.
+
+**UI sequences are difficult to trace in code**
+
+UIs often follow sequences like this:
+
+Click → animate button → fetch data → render results → animate items → highlight one item
+
+In traditional code, that sequence is often scattered across different places such as event handlers, effects, promises, and callbacks.
+
+TargetJS code order and target reactivity allow the implementation to more closely mirror the actual UI sequence.
+
+With its compact style, TargetJS makes the journey from A → B efficient and explicit, with significantly less code than traditional frameworks.
 
 ## ⚡ Quick Start (30 Seconds)
 
@@ -48,17 +60,39 @@ App({
 }).mount("#app");
 ```
 
-## Understanding TargetJS Syntax
+## Targets
+
+In TargetJS, targets are the fundamental unit of behavior. 
+Methods, properties, and objects are internally transformed into targets that the framework schedules and executes.
+
 
-These symbols tell the framework **when** a target should run.
+### Execution Syntax
 
-| Symbol   | Name     | Behavior                                                                                                                 |
-| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------|
-| `name`   | Standard | Runs immediately in the order it appears.                                                                                |
-| `name$`  | Reactive | Runs every time the previous sibling target runs.                                                                    |
-| `name$$` | Deferred | Runs only after the entire preceding target chain including children, animations, and API calls has fully completed. |
-| `_name`  | Inactive | Does not run automatically. Trigger it manually via `.activateTarget()`.                                                 |
- 
+Target names can include special symbols that determine **when they execute**.
+
+| Symbol | Name | Behavior |
+|------|------|------|
+| `name` | Standard | Runs immediately in the order it appears. |
+| `name$` | Reactive | Runs every time the previous sibling target runs. |
+| `name$$` | Deferred | Runs only after the entire preceding target chain (including children, animations, and API calls) completes. |
+| `_name` | Inactive | Does not run automatically. Trigger it manually via `.activateTarget()`. |
+
+
+### Target Controls
+
+A target can also be defined as an object with optional controls that manage its lifecycle and execution.
+
+| Property | Description |
+|------|------|
+| `value` | The data or function that determines the target's state. |
+| `steps` | Turns a value change into an animation. |
+| `interval` | Delay (ms) between steps or executions. |
+| `cycles` | Number of times the target repeats. |
+| `loop` | Boolean form of repetition for continuous execution. |
+| `enabledOn` | Determines whether the target is enabled for execution. |
+| `easing` | Predefined easing function controlling how values update over steps. |
+| `onComplete` | Callback triggered when this target (and its children) finishes. |
+| `onValueChange` | Callback triggered when the target emits a new value. |
 
 ## Examples: Like Button → Animated Like (in 3 Steps)
 
@@ -114,14 +148,9 @@ App({
   heart$$: {  // Wait for the button animation to finish, THEN add and animate the heart.
     html: "♥", color: "crimson", fontSize: 20,
     fly() {
-      const cx = this.getCenterX(), cy = this.getCenterY();
-      this.setTarget({
-        opacity: { value: [0, 1, 1, 0.8, 0.1], steps: 20 },
-        scale:   { value: [0.8, 1.4, 1.1, 0.9, 0.8], steps: 20 },
-        rotate:  { value: [0, 12, -8, 6, 0], steps: 20 },
-        x:       { value: [cx, cx + 22, cx - 16, cx + 10, cx], steps: 30 },
-        y:       { value: [cy - 8, cy - 70, cy - 90, cy - 120, cy - 150], steps: 30 }
-      });
+      const cx = (this.parent.getWidth() - this.getWidth()) / 2;
+      this.setTarget('x', { value: [cx, cx + 22, cx - 16, cx + 10, cx ], steps: 50, cycles: 2 }); // Repeat it twice
+      this.setTarget('y', { value: [0, -120], steps: 400 });
     }
   }  
 }).mount("#likeButton");
@@ -152,14 +181,9 @@ App({
   heart$$: {
     html: "♥", color: "crimson", fontSize: 20,
     fly() {
-      const cx = this.getCenterX(), cy = this.getCenterY();
-      this.setTarget({
-        opacity: { value: [0, 1, 1, 0.8, 0.1], steps: 20 },
-        scale:   { value: [0.8, 1.4, 1.1, 0.9, 0.8], steps: 20 },
-        rotate:  { value: [0, 12, -8, 6, 0], steps: 20 },
-        x:       { value: [cx, cx + 22, cx - 16, cx + 10, cx], steps: 30 },
-        y:       { value: [cy - 8, cy - 70, cy - 90, cy - 120, cy - 150], steps: 30 }
-      });
+      const cx = (this.parent.getWidth() - this.getWidth()) / 2;
+      this.setTarget('x', { value: [cx, cx + 22, cx - 16, cx + 10, cx ], steps: 50, cycles: 2 }); // Repeat it twice
+      this.setTarget('y', { value: [0, -120], steps: 400 });
     }
   },
   fetch$$: { method: "POST", id: 123, url: "/api/like" }, // Wait for the heart to finish, THEN fetch
@@ -182,7 +206,6 @@ Each target has its own state and lifecycle. Targets execute automatically in th
 1. Deeper Examples:
     - [Loading Five Users Example](#loading-five-users-example)
     - [Infinite Loading and Scrolling Example](#infinite-loading-and-scrolling-example)
-1. [Target Methods](#target-methods)
 1. [Special Target Names](#special-target-names)
 1. [How to Debug in TargetJS](#how-to-debug-in-targetjs)
 1. [Documentation](#documentation)
@@ -334,7 +357,7 @@ App({
     gap: 10,
     fetch: {
         interval: 1000,
-        cycles: 4,
+        cycles: 5,
         value(i) { return `https://targetjs.io/api/randomUser?id=user${i}`; }
     },
     child$() {   
@@ -411,7 +434,7 @@ App({
   },
   wave$$: {
     interval: 30,
-    cycles() { return this.visibleChildren.length - 1; },
+    cycles() { return this.visibleChildren.length; },
     value(i) {
       const child = this.visibleChildren[i];
       child.setTarget("scale", { value: [1, 1.06, 1], steps: 18 });
@@ -431,46 +454,42 @@ App({
 ```
 ---
 
-## Technical Reference
-
-### Target Methods
-
-Every target can be an object with these optional controls:
-
-1. **value**
-The data or function that determines the target's state.
+## Special Target Names
 
-1. **steps**
-Turns a value change into an animation (e.g., steps: 20).
+Some target names have built-in meaning and interact directly with the DOM, layout system, or browser events.  
+Because these behaviors are expressed as targets, they still participate in the same execution system and dependency flows as any other target.
 
-1. **interval**
-The delay (ms) between steps or executions.
+**Styles**
 
-1. **cycles**
-How many times to repeat the target.
+These targets update CSS properties and transforms:
 
-1. **onComplete**
-Callback when this target (and its children) finishes.
+- `width`, `height`
+- `opacity`
+- `x`, `y`, `z`
+- `rotate`, `rotateX`, `rotateY`, `rotateZ`
+- `scale`
+- `backgroundColor`, `color`
 
-1. **enabledOn**
-Determines whether the target is enabled for execution.
+These can be animated simply by adding `steps`.
 
-1. **loop**
-Managed the repetition of target execution. Similar to `cycles` but uses boolean instead.
+**Structure**
 
-1. **easing**
-A string that defines a predefined easing function that controls how the actual value is updated in relation to the steps.
+These targets define the structure of the interface:
 
-1. **onValueChange**
-This callback is triggered when `value` emits a new value.
+- `children` or `addChildren` – adds new children each time the target executes
+- `html` – inner HTML content, often simple text
+- `element` – specify the DOM element type (e.g., `div`, `canvas`)
 
-### Special Target Names
+**Events**
 
-TargetJS maps directly to the DOM for zero-friction styling. For example:
+These targets respond to browser events:
 
-- **Styles**: `width`, `height`, `opacity`, `x`, `y`, `rotate`, `scale`, `backgroundColor`.
-- **Structure**: `html`, `children`, `element`, `domHolder`.
-- **Events**: `onClick`, `onScroll`, `onKey`, `onVisibleChildrenChange`, `onResize`.
+- `onClick`
+- `onScroll`
+- `onKey`
+- `onResize`
+- `onEnter` / `onLeave`
+- `onVisibleChildrenChange`
 
 ## How to Debug in TargetJS
 

package/build/Bracket.js

@@ -157,9 +157,28 @@ var Bracket = exports.Bracket = /*#__PURE__*/function (_TModel) {
   }, {
     key: "shouldCalculateChildren",
     value: function shouldCalculateChildren() {
-      var result = this.isVisible() && this.getDirtyLayout() !== false || this.currentStatus === 'new' || this.isNowVisible;
-      this.currentStatus = undefined;
-      return result;
+      if (this.currentStatus === 'new' || this.isNowVisible) {
+        var visibleChild = this.getChildren().find(function (child) {
+          return child.calcVisibility();
+        });
+        this.currentStatus = undefined;
+        if (visibleChild) {
+          this.currentStatus = 'new';
+          var parent = this.parent;
+          while (parent && parent.type === 'BI') {
+            parent.currentStatus = 'new';
+            parent = parent.parent;
+          }
+        }
+        return true;
+      }
+      if (this.getDirtyLayout() === false) {
+        return false;
+      }
+      if (this.isVisible()) {
+        return true;
+      }
+      return false;
     }
   }, {
     key: "getDirtyLayout",

package/build/LoadingManager.js

@@ -124,16 +124,11 @@ var LoadingManager = exports.LoadingManager = /*#__PURE__*/function () {
     value: function getTModelKey(tmodel, targetName) {
       return "".concat(document.URL, "_").concat(tmodel.oid, "_").concat(targetName);
     }
-  }, {
-    key: "getLoadTargetName",
-    value: function getLoadTargetName(targetName) {
-      return "load-".concat(targetName);
-    }
   }, {
     key: "addToTModelKeyMap",
     value: function addToTModelKeyMap(tmodel, targetName, fetchId, cacheId) {
       var key = this.getTModelKey(tmodel, targetName);
-      var loadTargetName = this.getLoadTargetName(targetName);
+      var loadTargetName = _TUtil.TUtil.getLoadTargetName(targetName);
       var loadingComplete = this.isLoadingComplete(tmodel, targetName);
       if (loadingComplete || !this.tmodelKeyMap[key]) {
         var _this$tmodelKeyMap, _this$tmodelKeyMap$ke;
@@ -215,7 +210,7 @@ var LoadingManager = exports.LoadingManager = /*#__PURE__*/function () {
       if (!modelEntry) {
         return false;
       }
-      var loadTargetName = this.getLoadTargetName(targetName);
+      var loadTargetName = _TUtil.TUtil.getLoadTargetName(targetName);
       var targetValue = tmodel.val(loadTargetName);
       return Array.isArray(targetValue) && _TUtil.TUtil.isDefined(targetValue[modelEntry.activeIndex]);
     }
@@ -227,7 +222,7 @@ var LoadingManager = exports.LoadingManager = /*#__PURE__*/function () {
       if (!tmodelEntry || tmodelEntry.accessIndex >= tmodelEntry.resultCount) {
         return undefined;
       }
-      var loadTargetName = this.getLoadTargetName(prevTargetName);
+      var loadTargetName = _TUtil.TUtil.getLoadTargetName(prevTargetName);
       var targetValue = tmodel.val(loadTargetName);
       var result;
       if (targetValue) {
@@ -290,7 +285,7 @@ var LoadingManager = exports.LoadingManager = /*#__PURE__*/function () {
           targetName = _ref.targetName;
         var key = _this4.getTModelKey(tmodel, targetName);
         var tmodelEntry = _this4.tmodelKeyMap[key];
-        var loadTargetName = _this4.getLoadTargetName(targetName);
+        var loadTargetName = _TUtil.TUtil.getLoadTargetName(targetName);
         if (!tmodelEntry || !tmodelEntry.fetchMap[fetchId]) {
           return;
         }
@@ -300,12 +295,12 @@ var LoadingManager = exports.LoadingManager = /*#__PURE__*/function () {
         }));
         var targetResults = tmodel.val(loadTargetName);
         if (targetResults) {
-          if (!targetResults[fetchEntry.order]) {
+          if (!_TUtil.TUtil.isDefined(targetResults[fetchEntry.order])) {
             tmodelEntry.resultCount++;
           }
           targetResults[fetchEntry.order] = res.result;
         }
-        tmodel.val(targetName, (targetResults === null || targetResults === void 0 ? void 0 : targetResults.length) === 1 && tmodel.getTargetCycles(targetName) <= 1 ? targetResults[0] : targetResults);
+        tmodel.val(targetName, res.result);
         var newStatus = _this4.calculateTargetStatus(tmodel, targetName);
         tmodel.setTargetStatus(targetName, newStatus);
         tmodel.setLastUpdate(targetName);
@@ -332,7 +327,7 @@ var LoadingManager = exports.LoadingManager = /*#__PURE__*/function () {
           targetName = _ref2.targetName;
         var key = _this5.getTModelKey(tmodel, targetName);
         var tmodelEntry = _this5.tmodelKeyMap[key];
-        var loadTargetName = _this5.getLoadTargetName(targetName);
+        var loadTargetName = _TUtil.TUtil.getLoadTargetName(targetName);
         if (!tmodelEntry || !tmodelEntry.fetchMap[fetchId]) {
           return;
         }
@@ -345,12 +340,12 @@ var LoadingManager = exports.LoadingManager = /*#__PURE__*/function () {
         };
         var targetResults = tmodel.val(loadTargetName);
         if (targetResults) {
-          if (!targetResults[fetchEntry.order]) {
+          if (!_TUtil.TUtil.isDefined(targetResults[fetchEntry.order])) {
             tmodelEntry.resultCount++;
           }
           targetResults[fetchEntry.order] = res;
         }
-        tmodel.val(targetName, (targetResults === null || targetResults === void 0 ? void 0 : targetResults.length) === 1 && tmodel.getTargetCycles(targetName) <= 1 ? targetResults[0] : targetResults);
+        tmodel.val(targetName, res);
         tmodelEntry.errorCount++;
         _this5.callOnErrorHandler(tmodel, targetName);
         var newStatus = _this5.calculateTargetStatus(tmodel, targetName);

package/build/LocationManager.js

@@ -236,9 +236,6 @@ var LocationManager = exports.LocationManager = /*#__PURE__*/function () {
                 if (child.isDomIsland()) {
                   _this.domIslandSet.add(child);
                 }
-                if (child.shouldBeBracketed() && !_TUtil.TUtil.isDefined(child.getDomParent().targets['onWindowScroll'])) {
-                  child.getDomParent().addTarget('onWindowScroll', '');
-                }
                 viewport.setLocation();
                 if (viewport.isOverflow()) {
                   viewport.overflow();

package/build/TModel.js

@@ -134,6 +134,7 @@ var TModel = exports.TModel = /*#__PURE__*/function (_BaseModel) {
       this.deletedChildren.push(child);
       this.removeFromUpdatingChildren(child);
       this.removeFromActiveChildren(child);
+      this.removeFromAnimatingChildren(child);
       this.childrenUpdateFlag = true;
       (0, _App.getLocationManager)().calcChildren(this);
       this.markLayoutDirty('removeChild');
@@ -501,6 +502,11 @@ var TModel = exports.TModel = /*#__PURE__*/function (_BaseModel) {
       }
       return parentValue;
     }
+  }, {
+    key: "getLoadedItems",
+    value: function getLoadedItems(targetName) {
+      return this.val(_TUtil.TUtil.getLoadTargetName(targetName));
+    }
   }, {
     key: "delVal",
     value: function delVal(key) {

package/build/TModelManager.js

@@ -226,7 +226,7 @@ var TModelManager = exports.TModelManager = /*#__PURE__*/function () {
   }, {
     key: "needsRerender",
     value: function needsRerender(tmodel) {
-      if (tmodel.hasDom() && _TUtil.TUtil.isDefined(tmodel.getHtml()) && (tmodel.$dom.html() !== tmodel.getHtml() || tmodel.$dom.textOnly !== tmodel.isTextOnly())) {
+      if (tmodel.hasDom() && _TUtil.TUtil.isDefined(tmodel.getHtml()) && (tmodel.$dom.innerHTML() !== tmodel.getHtml() || tmodel.$dom.textOnly !== tmodel.isTextOnly())) {
         return true;
       }
       return false;

package/build/TUtil.js

@@ -165,6 +165,11 @@ var TUtil = exports.TUtil = /*#__PURE__*/function () {
     value: function capitalizeFirstLetter(val) {
       return val.charAt(0).toUpperCase() + val.slice(1);
     }
+  }, {
+    key: "getLoadTargetName",
+    value: function getLoadTargetName(targetName) {
+      return "load-".concat(targetName);
+    }
   }, {
     key: "formatNum",
     value: function formatNum(num, precision) {

package/build/TargetUtil.js

@@ -405,6 +405,9 @@ var TargetUtil = exports.TargetUtil = /*#__PURE__*/function () {
         if (tmodel.isTargetImperative(targetName)) {
           continue;
         }
+        if (tmodel.activatedTargets.indexOf(targetName) >= 0) {
+          return "activated targets";
+        }
         if (tmodel.hasUpdatingImperativeTargets(targetName)) {
           return tmodel.oid + "." + targetName + ": " + tmodel.getUpdatingImperativeTargets(targetName);
         }