targetj 1.0.240 → 1.0.242

package/Export.js

@@ -1,4 +1,26 @@
-export * from "./build/App.js";
+export {
+    App,
+    tApp,
+    tRoot,
+    isRunning,
+    getEvents,
+    getPager,
+    getLoader,
+    fetch,
+    fetchImage,
+    getManager,
+    getTargetManager,
+    getAnimationManager,
+    getRunScheduler,
+    getLocationManager,
+    getScreenWidth,
+    getScreenHeight,
+    getVisibles,
+    getResizeLastUpdate,
+    getTModelById,
+    getDomTModelById
+} from "./build/App.js";
+
 export * from "./build/TModel.js";
 export * from "./build/Moves.js";
 export * from "./build/SearchUtil.js";
@@ -7,7 +29,7 @@ export * from "./build/TargetUtil.js";
 export * from "./build/TargetParser.js";
 export * from "./build/TModelUtil.js";
 export * from "./build/TUtil.js";
-export * from "./build/DomInit.js"
+export * from "./build/DomInit.js";
 export * from "./build/$Dom.js";
 export * from "./build/Bracket.js";
 export * from "./build/BracketGenerator.js";
@@ -19,7 +41,7 @@ export * from "./build/AnimationUtil.js";
 export * from "./build/VisibilityUtil.js";
 export * from "./build/ScheduleUtil.js";
 
-import * as App from './build/App.js';
+import * as AppModule from './build/App.js';
 import * as TModel from './build/TModel.js';
 import * as Moves from './build/Moves.js';
 import * as SearchUtil from './build/SearchUtil.js';
@@ -41,7 +63,7 @@ import * as VisibilityUtil from './build/VisibilityUtil.js';
 import * as ScheduleUtil from './build/ScheduleUtil.js';
 
 const TargetJS = {
-  ...App,
+  ...AppModule,
   ...TModel,
   ...Moves,
   ...SearchUtil,
@@ -67,4 +89,4 @@ if (typeof window !== 'undefined') {
   window.TargetJS = TargetJS;
 }
 
-export default TargetJS;
+export default TargetJS;

package/README.md

@@ -7,7 +7,7 @@
 [![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". It also lets code order directly define the UI sequence. It unifies UI, animations, API calls, event handling, and state into self-contained "Targets" that stack together like intelligent Lego pieces using Code-Ordered Reactivity.
+TargetJS is a JavaScript UI framework that replaces the "State → Render" model with "State → Transition → Render". It also lets code order directly define the UI sequence. It unifies UI, animations, API calls, event handling, and state into self-contained "Targets" that stack together like Lego pieces using Code-Ordered Reactivity.
 
 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).
 
@@ -40,11 +40,11 @@ With its compact style, TargetJS makes the journey from A → B explicit and eff
 
 ## 🚀 Why TargetJS?
 
-1. Unified State: State isn't "elsewhere". It is built into every Target.
-2. Animation by Default: High-performance animations are baked into the logic.
-3. Ultra-Compact: Write 30% to 70% less code than standard frameworks.
-4. UI as Sequence: Code describes the UI story from top to bottom, exactly how the user experiences the interaction: "When this finishes, do that."
-5. Zero Boilerplate Async: Targets can handle waiting for asynchronous operations automatically.
+1. Unified State: One single state. Transitions are state too.
+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.
 
 ## ⚡ Quick Start (30 Seconds)
 
@@ -54,19 +54,31 @@ With its compact style, TargetJS makes the journey from A → B explicit and eff
 npm install targetj
 ```
 
-**2. The "Hello World" Sequence**
+**2. Example**
 
-This creates a blue box that grows, then turns red, and then logs "Hello World" in order.
+This creates the following sequential sequence: appear → bounce → move → turn red → log. Notice how the code follows the UI sequence. There is only one state, and the animation transitions are part of that state.
 
 ```javascript
 import { App } from "targetj";
 
 App({
-  backgroundColor: 'blue', // Starts immediately
-  width: { value: [100, 200], steps: 100, interval: 8 }, // Starts immediately: animate width from 100px to 200px in 100 steps with 8 ms interval per step.
-  height: { value: [100, 200], steps: 100, interval: 8 }, // Starts immediately: animate height.
-  backgroundColor$$: { value: 'red', steps: 100, interval: 8 }, // Wait ($$) for width/height to finish
-  done$$() { console.log("Hello World!"); } // 3. Waits ($$) for the background color, width/height to finish
+  width: 100,
+  height: 100,
+  backgroundColor: "blue",
+
+  // Starts immediately: bounce in.
+  scale: { value: [0.5, 1.2, 1], steps: 24, interval: 12 },
+
+  // Waits for scale to finish, then moves right.
+  x$$: { value: [0, 180], steps: 40, interval: 8 },
+
+  // Waits for x to finish, then turns red.
+  backgroundColor$$: { value: "crimson", steps: 30, interval: 8 },
+
+  // Waits for the color change to finish.
+  done$$() {
+    console.log("Sequence complete");
+  }
 }).mount("#app");
 ```
 
@@ -80,11 +92,12 @@ Methods and properties both are internally transformed into targets that the fra
 A target can:
 - execute a method
 - hold a value
-- move toward that value over time
-- wait for previous targets
+- move toward a new value over time
+- pause while moving toward a value
+- wait for previous targets to complete
 - react when previous targets update
 - fetch data
-- react to an event
+- respond to events
 - create children
 - run callbacks
 - control its own lifecycle
@@ -101,13 +114,13 @@ A target can also be defined as an object with optional controls that manage its
 | `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. |
+| `loop` | Controls repetition, either actively for continuous execution or passively when the value changes. |
 | `active` | Boolean property controlling when `value` is executed. |
 | `enabledOn` | Determines whether the target is enabled for execution. |
+| `pauseOn` | Pauses execution while the target is in progress. |
 | `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. |
-| `onChange` | Callback triggered when the target emits a new value. |
 | `on<PropertyName>Step` | Callback triggered on every step of a specific property. |
 
 ### Compact Execution Syntax
@@ -222,7 +235,7 @@ App({
 
 ### Summary
 
-Each target has its own state and lifecycle. Targets execute automatically in the order they are written. `$$` defers execution until all prior sibling targets (including their children) are fully complete. Animations, API calls, event handling, and child creation are all treated uniformly as targets. Complex asynchronous flows can be structured by organizing work into parent and child targets. In addition, targets provide built-in capabilities such as `onComplete` callbacks, `enabledOn`, looping with delays, and more. This also makes the code more compact, as it avoids using extra variables to track progress and reduces the need for loops and conditional statements.
+Each target has its own state and lifecycle. Targets execute automatically in the order they are written. `$$` defers execution until all prior sibling targets (including their children) are fully complete. Animations, API calls, event handling, and child creation are all treated uniformly as targets. Complex asynchronous flows can be structured by organizing work into parent and child targets. In addition, targets provide built-in capabilities such as `onComplete` callbacks, `pauseOn`, `enabledOn`, looping with delays, and more. This also makes the code more compact, as it avoids using extra variables to track progress and reduces the need for loops and conditional statements.
 
 ---
 
@@ -399,13 +412,13 @@ In this advanced example, we implement an infinite-scrolling application.
 
 * `photo` and `userName` each add a `div` element inside every item, serving as placeholders for the photo and user name.
 
-* `pause$$` delays the execution of all targets that follow it by 100 ms.
+* `pause$$` delays the execution of all targets that follow it by 300 ms. It also has `pauseOn: 'hidden'`, which means the delay is paused if the item becomes invisible, such as when the user scrolls down quickly. This also puts all following `$$` targets on hold, so `fetch$$` will not execute until the item becomes visible again.
 
 * `fetch$$` retrieves the user’s details.
 
 * `reveal$$` executes after `fetch$$`, revealing the user name and populating the photo with a random color.
 
-* `wave$$` executes only after all preceding children have completed their targets, giving each user item a coordinated animation.
+* `wave` executes when all visible children have completed their targets or when scrolling ends, giving each user item a coordinated animation.
 
 TargetJS employs a tree-like structure to track visible branches, optimizing scroller performance.
 
@@ -421,61 +434,88 @@ import { App, getEvents, getScreenWidth, getScreenHeight } from "targetj";
 
 App({
   preventDefault: true,
-  width: 250,
+  width: 300,
   height() { return getScreenHeight(); },
   x() { return (getScreenWidth() - this.getWidth()) / 2; },
   containerOverflowMode: "always",
+  canDeleteDom: false,
+  overflow: 'scroll',
+  onWindowScroll: true,
   addChildren: {
-    waitForChildren: 'visible',
-    value() {
-      return Array.from({ length: 10 }, (_, i) => ({
-        height: 56,
-        width() { return this.parent.getWidth(); },
-        bottomMargin: 8,
-        borderRadius: 12,
-        backgroundColor: "white",
-        boxShadow: "0 8px 20px rgba(0,0,0,0.08)",
-        photo: {
-          x: 10, y: 10, width: 34, height: 34,
-          borderRadius: "50%",
-          backgroundColor: "#ddd"
-        },
-        userName: {
-          x: 60, y: 10, width: 180, height: 30,
-          overflow: "hidden",
-          borderRadius: 5,
-          backgroundColor: "#ddd"
-        },
-        pause$$: { interval: 100 },
-        fetch$$: "https://targetjs.io/api/randomUser",
-        reveal$$() {
-          const userName = this.getChild("userName");
-          userName.setTarget("html", this.val("fetch$$").name);
-          userName.setTarget("backgroundColor", { value: "white", steps: 20 });
-          this.getChild("photo").setTarget("backgroundColor", { value: "#" + Math.random().toString(16).slice(-6), steps: 20 });
-        },
-      }));
-    }
+      value() {
+          return Array.from({length: 10}, (_, i) => ({
+              height: 56,
+              width() { return this.parent.getWidth() - 30; },
+              bottomMargin: 8,
+              borderRadius: 12,
+              backgroundColor: 'white',
+              boxShadow: "0 8px 20px rgba(0,0,0,0.08)",
+              pause: { 
+                  interval() { return getEvents().isWindowScrolling() ? 600 : 0; },
+                  pauseOn: 'hidden'
+              },
+              photo$$: {
+                  x: 10,
+                  y: 10,
+                  width:34,
+                  height:34,
+                  borderRadius: '50%',
+                  backgroundColor: '#ddd'
+              },
+              userName$$: {
+                  x: 60,
+                  y: 10,
+                  width: 180,
+                  height: 30,
+                  overflow: 'hidden',
+                  borderRadius: 5,
+                  backgroundColor: '#ddd'
+              },
+              pause$$: { 
+                  interval: 300,
+                  pauseOn: 'hidden'
+              },
+              fetch$$: "https://targetjs.io/api/randomUser",
+              reveal$$() {
+                  const userName = this.getChild('userName$$');
+                  userName.setTarget('html', this.val('fetch$$').name);
+                  userName.setTarget('backgroundColor', { value: 'white', steps: 20 });
+                  this.getChild('photo$$').setTarget('backgroundColor', { value: '#' + Math.random().toString(16).slice(-6), steps: 20 });
+              }
+          }));
+      },
+      onVisibleComplete() {
+          if (!getEvents().isWindowScrolling()) {
+              this.activateTarget('wave');
+          }
+      }
   },
-  wave$$: {
-    interval: 30,
-    cycles() { return this.visibleChildren.length; },
-    value(i) {
-      const child = this.visibleChildren[i];
-      if (child) {
-        child.setTarget("scale", { value: [1, 1.06, 1], steps: 18 });
-        child.setTarget("opacity", { value: [1, 0.92, 1], steps: 18 });
-      }  
-    }
+  onWindowScrollTopEnd() {
+      if (this.isTargetVisibleTreeComplete('addChildren')) {
+          this.activateTarget('wave');
+      }
   },
-  onScroll() {
-    this.setTarget("scrollTop", Math.max(0, this.getScrollTop() + getEvents().deltaY()));
+  wave: {
+      active: false,
+      interval: 30,
+      cycles() { return this.visibleChildren.length; },
+      value(i) {
+          const child = this.visibleChildren[i];
+          if (child) {
+              child.setTarget("scale", { value: [1, 1.06, 1], steps: 18 });
+              child.setTarget("opacity", { value: [1, 0.7, 1], steps: 18 });
+          }
+      }
   },
   onVisibleChildrenChange() {
-    const visibleCount = this.visibleChildren.length;
-    if (getEvents().dir() !== "up" && visibleCount * 64 < this.getHeight()) {
-      this.activateTarget("addChildren");
-    }
+      if (!this.visibleChildren.length) {
+          return this.activateTarget("addChildren");
+      }
+      const scrollTop = this.$dom?.getScrollTop() ?? 0;
+      const lastY = this.getLastChild().getY() - scrollTop - 500;
+      if (lastY <= this.getHeight()) {
+          this.activateTarget("addChildren");
+      }
   }
 }).mount("#userList");
 ```

package/build/$Dom.js

@@ -1,21 +1,16 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.$Dom = void 0;
-var _TUtil = require("./TUtil.js");
-var _App = require("./App.js");
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
 function _defineProperties(e, r) { for (var t = 0; t < r.length; t++) { var o = r[t]; o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, _toPropertyKey(o.key), o); } }
 function _createClass(e, r, t) { return r && _defineProperties(e.prototype, r), t && _defineProperties(e, t), Object.defineProperty(e, "prototype", { writable: !1 }), e; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { TUtil } from "./TUtil.js";
+import { getManager } from "./App.js";
+
 /**
  * It serves as a wrapper for all DOM operations.
  */
-var $Dom = exports.$Dom = /*#__PURE__*/function () {
+var $Dom = /*#__PURE__*/function () {
   function $Dom(elemSelector) {
     _classCallCheck(this, $Dom);
     if (typeof elemSelector === 'string') {
@@ -208,7 +203,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
       if (!this.element) {
         return;
       }
-      if (_TUtil.TUtil.isDefined(value)) {
+      if (TUtil.isDefined(value)) {
         this.element.setAttribute(name, value);
       } else {
         return this.element.getAttribute(name);
@@ -221,7 +216,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
         return;
       }
       var currentValue = this.element.value;
-      if (_TUtil.TUtil.isDefined(_value)) {
+      if (TUtil.isDefined(_value)) {
         this.element.value = _value;
       }
       return currentValue;
@@ -236,8 +231,8 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "width",
     value: function width(_width) {
-      if (_TUtil.TUtil.isDefined(_width)) {
-        this.element.style.width = _TUtil.TUtil.isNumber(_width) ? "".concat(_width, "px") : _width;
+      if (TUtil.isDefined(_width)) {
+        this.element.style.width = TUtil.isNumber(_width) ? "".concat(_width, "px") : _width;
       } else {
         return this.element.offsetWidth;
       }
@@ -245,8 +240,8 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "height",
     value: function height(_height) {
-      if (_TUtil.TUtil.isDefined(_height)) {
-        this.element.style.height = _TUtil.TUtil.isNumber(_height) ? "".concat(_height, "px") : _height;
+      if (TUtil.isDefined(_height)) {
+        this.element.style.height = TUtil.isNumber(_height) ? "".concat(_height, "px") : _height;
       } else {
         return this.element.offsetHeight;
       }
@@ -254,7 +249,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "css",
     value: function css(_css) {
-      if (_TUtil.TUtil.isDefined(_css)) {
+      if (TUtil.isDefined(_css)) {
         this.element.className = _css;
       } else {
         return this.element.className;
@@ -283,7 +278,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
     key: "getStyleValue",
     value: function getStyleValue(name) {
       var styleValue = this.style(name);
-      var numericValue = _TUtil.TUtil.isDefined(styleValue) ? styleValue.replace(/[^-\d.]/g, '') : 0;
+      var numericValue = TUtil.isDefined(styleValue) ? styleValue.replace(/[^-\d.]/g, '') : 0;
       return parseFloat(numericValue);
     }
   }, {
@@ -402,7 +397,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "html",
     value: function html(_html) {
-      if (_TUtil.TUtil.isDefined(_html)) {
+      if (TUtil.isDefined(_html)) {
         if (this.isNoSlotHost() || !this.hasRealChildren) {
           this.element.innerHTML = _html;
         } else {
@@ -416,7 +411,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "text",
     value: function text(_text) {
-      if (_TUtil.TUtil.isDefined(_text)) {
+      if (TUtil.isDefined(_text)) {
         if (this.isNoSlotHost() || !this.hasRealChildren) {
           this.element.textContent = _text;
         } else {
@@ -464,7 +459,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "innerHTML",
     value: function innerHTML(html) {
-      if (_TUtil.TUtil.isDefined(html)) {
+      if (TUtil.isDefined(html)) {
         this.element.innerHTML = html;
       } else {
         return this.element.innerHTML;
@@ -473,7 +468,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "innerText",
     value: function innerText(text) {
-      if (_TUtil.TUtil.isDefined(text)) {
+      if (TUtil.isDefined(text)) {
         this.element.innerText = text;
       } else {
         return this.element.innerText;
@@ -524,7 +519,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "getContext",
     value: function getContext(type, selector) {
-      var element = _TUtil.TUtil.isDefined(selector) ? $Dom.query(selector) : this.query('canvas');
+      var element = TUtil.isDefined(selector) ? $Dom.query(selector) : this.query('canvas');
       return element ? element.getContext(type) : undefined;
     }
   }, {
@@ -616,7 +611,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
     value: function findNearestParentWithId(element) {
       while (element) {
         var oid = typeof element.getAttribute === 'function' && element.getAttribute("id") ? element.getAttribute("id") : null;
-        if (oid && (0, _App.getManager)().visibleOidMap[oid]) {
+        if (oid && getManager().visibleOidMap[oid]) {
           return oid;
         }
         element = element.parentElement;
@@ -625,7 +620,7 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
   }, {
     key: "detach",
     value: function detach(element) {
-      var parent = _TUtil.TUtil.isDefined(element) ? element.parentElement : null;
+      var parent = TUtil.isDefined(element) ? element.parentElement : null;
       if (parent) {
         parent.removeChild(element);
       }
@@ -692,4 +687,5 @@ var $Dom = exports.$Dom = /*#__PURE__*/function () {
       }
     }
   }]);
-}();
+}();
+export { $Dom };