@alwatr/flux 9.17.0 → 9.18.0

package/README.md

@@ -945,6 +945,123 @@ renderState(currentState, {
 
 ---
 
+### Template (lit-html)
+
+`@alwatr/flux` re-exports a curated subset of [`lit-html`](https://lit.dev/docs/libraries/standalone-templates/) so you can render efficient DOM templates without adding a separate dependency.
+
+#### `html`
+
+Tagged template literal that produces a `TemplateResult`. lit-html parses the template once and only updates the dynamic parts on subsequent renders.
+
+```typescript
+import {html} from '@alwatr/flux';
+
+const greeting = (name: string) => html`
+  <p>Hello, ${name}!</p>
+`;
+```
+
+#### `render(value, container)`
+
+Renders a `TemplateResult` (or any renderable value) into a DOM container. Subsequent calls efficiently patch only the changed parts.
+
+```typescript
+import {html, render} from '@alwatr/flux';
+
+render(
+  html`
+    <h1>Hello World</h1>
+  `,
+  document.getElementById('app')!,
+);
+```
+
+#### `noChange` / `nothing`
+
+Sentinels for fine-grained control over part updates:
+
+- **`noChange`** — leaves the current DOM value untouched (skips the update entirely)
+- **`nothing`** — removes the node or attribute from the DOM
+
+```typescript
+import {html, noChange, nothing} from '@alwatr/flux';
+
+const badge = (count: number | undefined) => html`
+  <span class="badge">
+    ${count === undefined ? nothing
+    : count === 0 ? noChange
+    : count}
+  </span>
+`;
+```
+
+#### `ifDefined(value)`
+
+Renders the attribute only when `value` is not `undefined`; removes the attribute otherwise.
+
+```typescript
+import {html, ifDefined} from '@alwatr/flux';
+
+const link = (href?: string) => html`
+  <a href=${ifDefined(href)}>Click</a>
+`;
+```
+
+#### `cache(value)`
+
+Caches rendered templates keyed by their `TemplateResult` identity. Avoids re-parsing the template string when switching between a fixed set of templates (e.g. tab panels).
+
+```typescript
+import {html, cache} from '@alwatr/flux';
+
+const panel = (tab: 'home' | 'settings') =>
+  cache(
+    tab === 'home' ?
+      html`
+        <home-panel></home-panel>
+      `
+    : html`
+        <settings-panel></settings-panel>
+      `,
+  );
+```
+
+#### `classMap(classInfo)`
+
+Efficiently toggles CSS classes from a `{[className]: boolean}` object. Only the classes present in the map are touched; others are left unchanged.
+
+```typescript
+import {html, classMap} from '@alwatr/flux';
+
+const button = (isActive: boolean, isDisabled: boolean) => html`
+  <button class=${classMap({active: isActive, disabled: isDisabled})}>Click</button>
+`;
+```
+
+#### `when(condition, trueCase, falseCase?)`
+
+Conditional rendering helper. Cleaner than ternary expressions for template branches.
+
+```typescript
+import {html, when} from '@alwatr/flux';
+
+const status = (isLoading: boolean) => html`
+  <div>
+    ${when(
+      isLoading,
+      () => html`
+        <spinner-element></spinner-element>
+      `,
+      () => html`
+        <content-element></content-element>
+      `,
+    )}
+  </div>
+`;
+```
+
+---
+
 ## 🆚 Why Choose Alwatr Flux?
 
 | Feature                | React + Redux            | Solid.js        | Svelte                   | **Alwatr Flux** 🌊                 |

package/dist/lit-html.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Curated re-exports from `lit-html` for use within `@alwatr/flux`.
+ *
+ * Only the subset of `lit-html` APIs that are commonly needed in a Flux-based
+ * application is exported here. This keeps the public surface minimal and
+ * avoids pulling in advanced directive utilities that most consumers never use.
+ *
+ * **Exported APIs:**
+ * - `html` — tagged template literal that produces a `TemplateResult`
+ * - `render` — renders a `TemplateResult` into a DOM container
+ * - `noChange` — sentinel that tells lit-html to leave the current part value unchanged
+ * - `nothing` — sentinel that renders nothing (removes the node/attribute)
+ * - `ifDefined` — renders a value only when it is not `undefined`
+ * - `cache` — caches rendered templates to avoid re-parsing on state changes
+ * - `classMap` — efficiently sets/removes CSS classes from an object map
+ * - `when` — conditional rendering helper (`when(condition, trueCase, falseCase)`)
+ *
+ * @example
+ * ```typescript
+ * import {html, render, classMap, when} from '@alwatr/flux';
+ *
+ * const template = (isActive: boolean) => html`
+ *   <div class=${classMap({active: isActive, hidden: !isActive})}>
+ *     ${when(isActive, () => html`<span>Active</span>`, () => html`<span>Inactive</span>`)}
+ *   </div>
+ * `;
+ *
+ * render(template(true), document.getElementById('app')!);
+ * ```
+ */
+export { html, render, noChange, nothing } from 'lit-html';
+export { ifDefined } from 'lit-html/directives/if-defined.js';
+export { cache } from 'lit-html/directives/cache.js';
+export { classMap } from 'lit-html/directives/class-map.js';
+export { when } from 'lit-html/directives/when.js';
+//# sourceMappingURL=lit-html.d.ts.map

package/dist/lit-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lit-html.d.ts","sourceRoot":"","sources":["../src/lit-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAC,MAAM,UAAU,CAAC;AAIzD,OAAO,EAAC,SAAS,EAAC,MAAM,mCAAmC,CAAC;AAC5D,OAAO,EAAC,KAAK,EAAC,MAAM,8BAA8B,CAAC;AACnD,OAAO,EAAC,QAAQ,EAAC,MAAM,kCAAkC,CAAC;AAC1D,OAAO,EAAC,IAAI,EAAC,MAAM,6BAA6B,CAAC"}

package/dist/main.d.ts

@@ -5,5 +5,6 @@ export * from '@alwatr/render-state';
 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,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,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,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,mBAAmB,qBAAqB,CAAC"}

package/dist/main.js

@@ -1,5 +1,5 @@
-/* 📦 @alwatr/flux v9.17.0 */
-export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/directive";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";
+/* 📦 @alwatr/flux v9.18.0 */
+export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/directive";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";import{html as o,render as a,noChange as t,nothing as p}from"lit-html";import{ifDefined as f}from"lit-html/directives/if-defined.js";import{cache as g}from"lit-html/directives/cache.js";import{classMap as i}from"lit-html/directives/class-map.js";import{when as s}from"lit-html/directives/when.js";export{s as when,a as render,p as nothing,t as noChange,f as ifDefined,o as html,i as classMap,g as cache};
 
-//# debugId=0386D7BA1F615EBF64756E2164756E21
+//# debugId=432FAE968752561764756E2164756E21
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -1,10 +1,11 @@
 {
   "version": 3,
-  "sources": ["../src/main.ts"],
+  "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/render-state';\nexport * from '@alwatr/local-storage';\nexport * from '@alwatr/session-storage';\nexport * from '@alwatr/page-ready';\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/directive';\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",
+    "/**\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 {html, render, noChange, nothing} from 'lit-html';\n// export {Directive, PartType, directive} from 'lit-html/directive.js';\n// export {AsyncDirective} from 'lit-html/async-directive.js';\n// export {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} from 'lit-html/directives/class-map.js';\nexport {when} from 'lit-html/directives/when.js';\n\n// export type {Part, PartInfo} from 'lit-html/directive.js';\n// export type {LitUnstable} from 'lit-html';\n"
   ],
-  "mappings": ";AAGA,4BACA,4BACA,+BACA,kCACA,mCACA,qCACA",
-  "debugId": "0386D7BA1F615EBF64756E2164756E21",
+  "mappings": ";AAGA,4BACA,4BACA,+BACA,kCACA,mCACA,qCACA,gCCqBA,eAAQ,YAAM,cAAQ,aAAU,iBAIhC,oBAAQ,0CACR,gBAAQ,qCACR,mBAAQ,yCACR,eAAQ",
+  "debugId": "432FAE968752561764756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/flux",
-  "version": "9.17.0",
+  "version": "9.18.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)",
@@ -22,13 +22,14 @@
   "sideEffects": false,
   "dependencies": {
     "@alwatr/action": "9.17.0",
-    "@alwatr/directive": "9.16.0",
+    "@alwatr/directive": "9.18.0",
     "@alwatr/local-storage": "9.16.0",
     "@alwatr/page-ready": "9.16.0",
     "@alwatr/render-state": "9.16.0",
     "@alwatr/session-storage": "9.16.0",
     "@alwatr/signal": "9.16.0",
-    "@alwatr/type-helper": "9.14.0"
+    "@alwatr/type-helper": "9.14.0",
+    "lit-html": "^3.3.2"
   },
   "devDependencies": {
     "@alwatr/nano-build": "9.14.0",
@@ -38,7 +39,7 @@
   "scripts": {
     "b": "bun run build",
     "build": "bun run build:ts && bun run build:es",
-    "build:es": "nano-build --preset=module src/*.ts",
+    "build:es": "nano-build --preset=module src/main.ts",
     "build:ts": "tsc --build",
     "cl": "bun run clean",
     "clean": "rm -rfv dist *.tsbuildinfo",
@@ -81,5 +82,5 @@
     "ui",
     "unidirectional-data-flow"
   ],
-  "gitHead": "782563375f55c55d29719cbcfebaca251d69ddcd"
+  "gitHead": "ae7aed95106fd2e6d3c14f0628fc12ae8a29ea15"
 }

package/src/lit-html.ts

@@ -0,0 +1,41 @@
+/**
+ * Curated re-exports from `lit-html` for use within `@alwatr/flux`.
+ *
+ * Only the subset of `lit-html` APIs that are commonly needed in a Flux-based
+ * application is exported here. This keeps the public surface minimal and
+ * avoids pulling in advanced directive utilities that most consumers never use.
+ *
+ * **Exported APIs:**
+ * - `html` — tagged template literal that produces a `TemplateResult`
+ * - `render` — renders a `TemplateResult` into a DOM container
+ * - `noChange` — sentinel that tells lit-html to leave the current part value unchanged
+ * - `nothing` — sentinel that renders nothing (removes the node/attribute)
+ * - `ifDefined` — renders a value only when it is not `undefined`
+ * - `cache` — caches rendered templates to avoid re-parsing on state changes
+ * - `classMap` — efficiently sets/removes CSS classes from an object map
+ * - `when` — conditional rendering helper (`when(condition, trueCase, falseCase)`)
+ *
+ * @example
+ * ```typescript
+ * import {html, render, classMap, when} from '@alwatr/flux';
+ *
+ * const template = (isActive: boolean) => html`
+ *   <div class=${classMap({active: isActive, hidden: !isActive})}>
+ *     ${when(isActive, () => html`<span>Active</span>`, () => html`<span>Inactive</span>`)}
+ *   </div>
+ * `;
+ *
+ * render(template(true), document.getElementById('app')!);
+ * ```
+ */
+export {html, render, noChange, nothing} from 'lit-html';
+// export {Directive, PartType, directive} from 'lit-html/directive.js';
+// export {AsyncDirective} from 'lit-html/async-directive.js';
+// export {unsafeSVG} from 'lit-html/directives/unsafe-svg.js';
+export {ifDefined} from 'lit-html/directives/if-defined.js';
+export {cache} from 'lit-html/directives/cache.js';
+export {classMap} from 'lit-html/directives/class-map.js';
+export {when} from 'lit-html/directives/when.js';
+
+// export type {Part, PartInfo} from 'lit-html/directive.js';
+// export type {LitUnstable} from 'lit-html';

package/src/main.ts

@@ -8,4 +8,5 @@ export * from '@alwatr/render-state';
 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';