@alwatr/flux 9.28.0 → 9.29.0

package/README.md

@@ -18,6 +18,7 @@ Born from years of building production PWAs and inspired by the best ideas from
 - **Fine-grained reactivity** via Signals (no Virtual DOM overhead)
 - **Global event delegation** for O(1) boot time (inspired by Qwik's Resumability)
 - **Declarative DOM directives** for clean, maintainable UI code
+- **Declarative reactive DOM data binding** via Bind (surgical view model updates)
 - **Type-safe action bus** with zero runtime overhead
 - **Persistent state management** with automatic localStorage/sessionStorage sync
 
@@ -377,6 +378,58 @@ createEffect({
 });
 ```
 
+### 🔗 **Declarative DOM Data Binding (Bind)**
+
+Flux aggregates `@alwatr/bind` to provide a declarative, low-overhead way to bind elements directly to reactive view models. This enables surgical updates to text, values, and attributes without virtual DOM diffing or full-component re-renders.
+
+```typescript
+import {service_binding, createStateSignal} from '@alwatr/flux';
+
+// 1. Create domain state signal
+const userSignal = createStateSignal({
+  name: 'user',
+  initialValue: {firstName: 'Ali', lastName: 'Mihandoost', cart: []},
+});
+
+// 2. Project domain state to flat view model representation
+service_binding.createViewModel('user', userSignal, (u) => ({
+  firstName: u.firstName,
+  fullName: `${u.firstName} ${u.lastName}`,
+  cartIsEmpty: u.cart.length === 0,
+}));
+```
+
+In your HTML, bind properties using declarative attributes:
+
+```html
+<!-- Text Content Binding -->
+<h2 bind-text="user.fullName">Loading...</h2>
+
+<!-- Value Binding with active cursor position preservation guard -->
+<input
+  type="text"
+  bind-value="user.firstName"
+  on-input="ui_edit_name:$value"
+/>
+
+<!-- Attribute Binding (boolean presence toggling / nullish removal) -->
+<button bind-attrib="disabled=user.cartIsEmpty">Checkout</button>
+
+<!-- Lazy Binding (evaluated only when element enters viewport) -->
+<div
+  bind-text="user.fullName"
+  lazy-bind
+></div>
+```
+
+#### 🌟 Key Advantages of Bind
+
+- **Cursor Preservation**: Writing to input values directly in other frameworks often resets the cursor caret to the end of the text. `@alwatr/bind` compares values and only writes to the DOM if the value changed, preserving typing cursor position perfectly.
+- **Presence-Aware Attributes**: Binds attributes intelligently. A `boolean` value toggles attribute presence, a `nullish` value removes the attribute, and any other value sets the attribute as a string.
+- **Lazy Initialization**: Placing `lazy-bind` on elements defers signal subscription and DOM updates until the element physically intersects the viewport, optimizing rendering performance on large pages.
+
+---
+
 ### 🤖 **Finite State Machine (FSM) & Actor Model**
 
 Flux natively aggregates `@alwatr/fsm` to eliminate ad-hoc state variables, boolean flags, and race conditions. Instead of writing unpredictable, disjointed spaghetti code, you model your application's lifecycle as a **declarative, type-safe statechart**.
@@ -388,7 +441,9 @@ import type {StateMachineConfig} from '@alwatr/flux';
 // 1. Define strict Union Types for compile-time safety
 type FetchState = 'idle' | 'loading' | 'success' | 'failed';
 type FetchEvent = {type: 'FETCH'} | {type: 'SUCCESS'} | {type: 'ERROR'};
-interface FetchContext { retries: number }
+interface FetchContext {
+  retries: number;
+}
 
 // 2. Configure the machine declaratively
 const fetchConfig: StateMachineConfig<FetchState, FetchEvent, FetchContext> = {
@@ -397,21 +452,25 @@ const fetchConfig: StateMachineConfig<FetchState, FetchEvent, FetchContext> = {
   context: {retries: 0},
   states: {
     idle: {
-      on: { FETCH: { target: 'loading' } },
+      on: {FETCH: {target: 'loading'}},
     },
     loading: {
       on: {
-        SUCCESS: { target: 'success', assigners: [({context}) => ({...context, retries: 0})] },
+        SUCCESS: {target: 'success', assigners: [({context}) => ({...context, retries: 0})]},
         ERROR: [
           // Guard evaluates condition; first matching transition branch is chosen
-          { target: 'loading', guard: ({context}) => context.retries < 3, assigners: [({context}) => ({...context, retries: context.retries + 1})] },
-          { target: 'failed' }
+          {
+            target: 'loading',
+            guard: ({context}) => context.retries < 3,
+            assigners: [({context}) => ({...context, retries: context.retries + 1})],
+          },
+          {target: 'failed'},
         ],
       },
     },
     success: {},
     failed: {
-      on: { FETCH: { target: 'loading', assigners: [({context}) => ({...context, retries: 0})] } },
+      on: {FETCH: {target: 'loading', assigners: [({context}) => ({...context, retries: 0})]}},
     },
   },
 };
@@ -442,6 +501,7 @@ fetchService.dispatch({type: 'FETCH'});
 Flux implements a **strict layered architecture** where each layer has a single responsibility. It supports both standard Unidirectional Data Flow (UDF) and the decentralized **Actor Model** (where components/features behave as isolated micro-services powered by FSMs).
 
 ### 1. Unidirectional Data Flow (UDF) Layering
+
 ```
 ┌───────────────────────────────────────────────────────────┐
 │                         VIEW LAYER                        │
@@ -1058,6 +1118,62 @@ class FormDirective extends Directive {
 
 ---
 
+### Bind (Declarative Data Binding)
+
+#### `setupBindDirectives()`
+
+Registers and bootstraps all `@alwatr/bind` attribute directives on application boot.
+
+```typescript
+import {setupBindDirectives} from '@alwatr/flux';
+
+setupBindDirectives();
+```
+
+#### `service_binding`
+
+The registry singleton managing presentation view models and mapping subscriptions.
+
+##### `service_binding.createViewModel(namespace, sourceSignal, project)`
+
+Registers a ViewModel namespaces mapping a domain signal state `S` to a flat presentation record `T`.
+
+```typescript
+import {service_binding} from '@alwatr/flux';
+
+service_binding.createViewModel('user', userSignal, (u) => ({
+  fullName: `${u.firstName} ${u.lastName}`,
+  cartIsEmpty: u.cart.length === 0,
+}));
+```
+
+##### `service_binding.getViewModel(namespace)`
+
+Retrieves a registered ViewModel's computed signal. Returns `null` if the namespace is not registered.
+
+##### `service_binding.removeViewModel(namespace)`
+
+Destroys the ViewModel's computed signal and removes the namespace from the active registry.
+
+#### Directives HTML Syntax
+
+- **`bind-text="namespace.prop"`**
+  Updates the element's `textContent` to the property value. Maps nullish values (`null`/`undefined`) to `''`.
+
+- **`bind-value="namespace.prop"`**
+  Updates input element values safely. Skips DOM writing if the element's value is already equal to the bound value to prevent caret cursor jumping in active text inputs.
+
+- **`bind-attrib="attr1=namespace.prop1; attr2=namespace.prop2"`**
+  Updates target DOM attributes.
+  - A boolean value toggles the attribute's presence.
+  - A nullish value (`null` or `undefined`) removes the attribute.
+  - All other values are coerced to strings.
+
+- **`lazy-bind`**
+  When added to any element with the above bindings, defers initialization and signal subscription until the element physically intersects the viewport.
+
+---
+
 ### Page Ready
 
 #### `onPageReady(pageId, handler)`

package/dist/main.d.ts

@@ -1,5 +1,6 @@
 export * from '@alwatr/signal';
 export * from '@alwatr/action';
+export * from '@alwatr/bind';
 export * from '@alwatr/directive';
 export * from '@alwatr/embedded-data';
 export * from '@alwatr/fsm';
@@ -9,5 +10,4 @@ export * from '@alwatr/local-storage';
 export * from '@alwatr/session-storage';
 export * from '@alwatr/page-ready';
 export * from './lit-html.js';
-export type * from '@alwatr/type-helper';
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,mBAAmB,qBAAqB,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC"}

package/dist/main.js

@@ -1,5 +1,5 @@
-/* 📦 @alwatr/flux v9.28.0 */
-export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/directive";export*from"@alwatr/embedded-data";export*from"@alwatr/fsm";export*from"@alwatr/keyboard-shortcut";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";import{html as e,svg as p,mathml as a,render as f,noChange as t,nothing as x}from"lit-html";import{unsafeSVG as m}from"lit-html/directives/unsafe-svg.js";import{ifDefined as i}from"lit-html/directives/if-defined.js";import{cache as s}from"lit-html/directives/cache.js";import{classMap as b}from"lit-html/directives/class-map.js";import{when as d}from"lit-html/directives/when.js";import{repeat as I}from"lit-html/directives/repeat.js";export{d as when,m as unsafeSVG,p as svg,I as repeat,f as render,x as nothing,t as noChange,a as mathml,i as ifDefined,e as html,b as classMap,s as cache};
+/* 📦 @alwatr/flux v9.29.0 */
+export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/bind";export*from"@alwatr/directive";export*from"@alwatr/embedded-data";export*from"@alwatr/fsm";export*from"@alwatr/keyboard-shortcut";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";import{html as e,svg as f,mathml as p,render as x,noChange as a,nothing as n}from"lit-html";import{unsafeSVG as m}from"lit-html/directives/unsafe-svg.js";import{ifDefined as i}from"lit-html/directives/if-defined.js";import{cache as b}from"lit-html/directives/cache.js";import{classMap as d}from"lit-html/directives/class-map.js";import{when as I}from"lit-html/directives/when.js";import{repeat as k}from"lit-html/directives/repeat.js";export{I as when,m as unsafeSVG,f as svg,k as repeat,x as render,n as nothing,a as noChange,p as mathml,i as ifDefined,e as html,d as classMap,b as cache};
 
-//# debugId=F1AB5B823C55946064756E2164756E21
+//# debugId=09E68C2A4C1329DF64756E2164756E21
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -2,10 +2,10 @@
   "version": 3,
   "sources": ["../src/main.ts", "../src/lit-html.ts"],
   "sourcesContent": [
-    "// UI and reactive bundle — signals, actions, directives, and client-side storage.\n// This package aggregates all UI-layer nanolibs for convenient single-import usage.\n\nexport * from '@alwatr/signal';\nexport * from '@alwatr/action';\nexport * from '@alwatr/directive';\nexport * from '@alwatr/embedded-data';\nexport * from '@alwatr/fsm';\nexport * from '@alwatr/keyboard-shortcut';\nexport * from '@alwatr/render-state';\nexport * from '@alwatr/local-storage';\nexport * from '@alwatr/session-storage';\nexport * from '@alwatr/page-ready';\nexport * from './lit-html.js';\nexport type * from '@alwatr/type-helper';\n",
+    "// UI and reactive bundle — signals, actions, directives, and client-side storage.\n// This package aggregates all UI-layer nanolibs for convenient single-import usage.\n\nexport * from '@alwatr/signal';\nexport * from '@alwatr/action';\nexport * from '@alwatr/bind';\nexport * from '@alwatr/directive';\nexport * from '@alwatr/embedded-data';\nexport * from '@alwatr/fsm';\nexport * from '@alwatr/keyboard-shortcut';\nexport * from '@alwatr/render-state';\nexport * from '@alwatr/local-storage';\nexport * from '@alwatr/session-storage';\nexport * from '@alwatr/page-ready';\nexport * from './lit-html.js';\n",
     "/**\n * Curated re-exports from `lit-html` for use within `@alwatr/flux`.\n *\n * Only the subset of `lit-html` APIs that are commonly needed in a Flux-based\n * application is exported here. This keeps the public surface minimal and\n * avoids pulling in advanced directive utilities that most consumers never use.\n *\n * **Exported APIs:**\n * - `html` — tagged template literal that produces a `TemplateResult`\n * - `render` — renders a `TemplateResult` into a DOM container\n * - `noChange` — sentinel that tells lit-html to leave the current part value unchanged\n * - `nothing` — sentinel that renders nothing (removes the node/attribute)\n * - `ifDefined` — renders a value only when it is not `undefined`\n * - `cache` — caches rendered templates to avoid re-parsing on state changes\n * - `classMap` — efficiently sets/removes CSS classes from an object map\n * - `when` — conditional rendering helper (`when(condition, trueCase, falseCase)`)\n *\n * @example\n * ```typescript\n * import {html, render, classMap, when} from '@alwatr/flux';\n *\n * const template = (isActive: boolean) => html`\n *   <div class=${classMap({active: isActive, hidden: !isActive})}>\n *     ${when(isActive, () => html`<span>Active</span>`, () => html`<span>Inactive</span>`)}\n *   </div>\n * `;\n *\n * render(template(true), document.getElementById('app')!);\n * ```\n */\nexport {\n  html,\n  svg,\n  mathml,\n  render,\n  noChange,\n  nothing,\n  type TemplateResult,\n  type HTMLTemplateResult,\n  type SVGTemplateResult,\n  type MathMLTemplateResult,\n} from 'lit-html';\nexport {unsafeSVG} from 'lit-html/directives/unsafe-svg.js';\nexport {ifDefined} from 'lit-html/directives/if-defined.js';\nexport {cache} from 'lit-html/directives/cache.js';\nexport {classMap, type ClassInfo} from 'lit-html/directives/class-map.js';\nexport {when} from 'lit-html/directives/when.js';\nexport {repeat, type RepeatDirectiveFn, type KeyFn, type ItemTemplate} from 'lit-html/directives/repeat.js';\n"
   ],
-  "mappings": ";AAGA,4BACA,4BACA,+BACA,mCACA,yBACA,uCACA,kCACA,mCACA,qCACA,gCCkBA,eACE,SACA,YACA,YACA,cACA,aACA,iBAMF,oBAAQ,0CACR,oBAAQ,0CACR,gBAAQ,qCACR,mBAAQ,yCACR,eAAQ,oCACR,iBAAQ",
-  "debugId": "F1AB5B823C55946064756E2164756E21",
+  "mappings": ";AAGA,4BACA,4BACA,0BACA,+BACA,mCACA,yBACA,uCACA,kCACA,mCACA,qCACA,gCCiBA,eACE,SACA,YACA,YACA,cACA,aACA,iBAMF,oBAAQ,0CACR,oBAAQ,0CACR,gBAAQ,qCACR,mBAAQ,yCACR,eAAQ,oCACR,iBAAQ",
+  "debugId": "09E68C2A4C1329DF64756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/flux",
-  "version": "9.28.0",
+  "version": "9.29.0",
   "description": "UI and reactive library bundle for ECMAScript (JavaScript/TypeScript) projects — signals, actions, directives, and storage.",
   "license": "MPL-2.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
@@ -21,17 +21,17 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@alwatr/action": "9.28.0",
-    "@alwatr/directive": "9.26.0",
-    "@alwatr/embedded-data": "9.25.0",
-    "@alwatr/fsm": "9.28.0",
-    "@alwatr/keyboard-shortcut": "9.28.0",
-    "@alwatr/local-storage": "9.25.0",
-    "@alwatr/page-ready": "9.27.0",
-    "@alwatr/render-state": "9.25.0",
-    "@alwatr/session-storage": "9.25.0",
-    "@alwatr/signal": "9.26.0",
-    "@alwatr/type-helper": "9.14.0",
+    "@alwatr/action": "9.29.0",
+    "@alwatr/bind": "9.29.0",
+    "@alwatr/directive": "9.29.0",
+    "@alwatr/embedded-data": "9.29.0",
+    "@alwatr/fsm": "9.29.0",
+    "@alwatr/keyboard-shortcut": "9.29.0",
+    "@alwatr/local-storage": "9.29.0",
+    "@alwatr/page-ready": "9.29.0",
+    "@alwatr/render-state": "9.29.0",
+    "@alwatr/session-storage": "9.29.0",
+    "@alwatr/signal": "9.29.0",
     "lit-html": "^3.3.3"
   },
   "devDependencies": {
@@ -85,5 +85,5 @@
     "ui",
     "unidirectional-data-flow"
   ],
-  "gitHead": "d60f1d986e5ff44f871d38231f1f2be60833140b"
+  "gitHead": "2f80c615d90e038dca634a2dfba8d900d3df6248"
 }

package/src/main.ts

@@ -3,6 +3,7 @@
 
 export * from '@alwatr/signal';
 export * from '@alwatr/action';
+export * from '@alwatr/bind';
 export * from '@alwatr/directive';
 export * from '@alwatr/embedded-data';
 export * from '@alwatr/fsm';
@@ -12,4 +13,3 @@ export * from '@alwatr/local-storage';
 export * from '@alwatr/session-storage';
 export * from '@alwatr/page-ready';
 export * from './lit-html.js';
-export type * from '@alwatr/type-helper';