npm - smart-lifecycle - Versions diffs - 0.1.1 → 0.2.1 - Mend

smart-lifecycle 0.1.1 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (819) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # SmartComponents
-> A lightweight, reactive web components framework for TypeScript.
+> A lightweight, reactive web components framework for TypeScript and modern browser ESM.
 > Business logic stays in services. Components are pure presentation.
 [![npm](https://img.shields.io/npm/v/smart-lifecycle)](https://www.npmjs.com/package/smart-lifecycle)
@@ -18,6 +18,7 @@
 - **Factory-first DI** — Explicit dependency injection through factory functions; no auto-wiring magic.
 - **Security-first expression evaluator** — Deterministic AST pipeline; no `eval` or `new Function`. Whitelisted method calls only.
 - **Tiny footprint** — Zero runtime dependencies.
+- **Browser-ready distribution** — Published ESM build for direct `<script type="module">` usage.
 ---
@@ -29,6 +30,90 @@ npm install smart-lifecycle
 ---
+## Choose Your Setup
+### Option A — npm + bundler
+Use this in Vite, Rollup, Webpack, esbuild, or similar toolchains.
+```typescript
+import { bootstrapFramework, Services } from "smart-lifecycle";
+```
+This path does not specifically require Vite, but it does require a toolchain that can resolve npm package imports for the browser.
+### Option B — plain HTML + browser-ready ESM
+Use this when you want to import the framework directly in the browser with no bundler.
+For this mode, use the browser-ready artifacts prepared for GitHub Releases rather than trying to import the npm package directly in the browser.
+Release assets are published here:
+- `https://github.com/janmbaco/smartcomponents/releases`
+- `https://github.com/janmbaco/smartcomponents/releases/tag/v<version>`
+Direct asset URLs follow this pattern:
+- `https://github.com/janmbaco/smartcomponents/releases/download/v<version>/smart-lifecycle.js`
+- `https://github.com/janmbaco/smartcomponents/releases/download/v<version>/smart-lifecycle-bootstrap.js`
+Recommended flow:
+1. Download the browser bundle from the project's GitHub Release assets.
+2. Copy it into your site's public assets, for example `/vendor/smart-lifecycle.js`.
+3. Import that file from your HTML with `<script type="module">`.
+Minimal example:
+```html
+<!doctype html>
+<html lang="en">
+  <body>
+    <hello-card></hello-card>
+    <script type="module">
+      import {
+        bootstrapFramework,
+        Services,
+        Smart,
+      } from "/vendor/smart-lifecycle.js";
+      await bootstrapFramework(Services);
+      @Smart("hello-card", (ctx) => {
+        ctx.state({ name: "world" });
+        ctx.html(`<p>Hello {{name}}</p>`);
+      })
+      class HelloCard {}
+    </script>
+  </body>
+</html>
+```
+The browser-ready distribution is self-contained and does not rely on external runtime packages or Node builtins. It is intended for direct browser import once the file is being served by your site.
+The npm package is optimized for development and consumption. The plain-browser distribution is documented and prepared as a separate release artifact flow, not as a browser-importable npm package entrypoint.
+For GitHub Releases, the project also prepares a heavier browser distribution with:
+- non-minified bundles
+- minified bundles
+- source maps for all browser bundles
+- SHA256 checksums
+Build the release artifacts locally with:
+```bash
+npm run build:release
+```
+This creates `.release-artifacts/v<version>/`, which mirrors the intended GitHub Release contents.
+This direct browser path assumes a modern browser environment with ESM and decorator support. If you need broader compatibility or a transpilation step, use the standard npm + bundler setup.
+---
 ## Bootstrap
 Call `bootstrapFramework()` once in your entry point before any component is used:
@@ -43,6 +128,14 @@ bootstrapFramework(Services);
 ## Usage
+The examples below use the standard package import form:
+```typescript
+import { bootstrapFramework, Services } from "smart-lifecycle";
+await bootstrapFramework(Services);
+```
 ### Presentational Component (Slot Projection)
 Components that wrap child content in a styled layout using native Shadow DOM slots. No state, no logic.
@@ -203,9 +296,12 @@ export class TodoList extends SmartComponent {
 | -------------------------- | ------------------------------------------------- |
 | `npm install`              | Install dependencies                              |
 | `npm run build:lib`        | Compile library to `dist/`                        |
+| `npm run build:browser`    | Bundle browser-ready ESM artifacts to `dist/browser/` |
+| `npm run build:prod`       | Compile library + browser-ready ESM artifacts     |
+| `npm run build:release`    | Prepare GitHub release browser artifacts in `.release-artifacts/` |
 | `npm run build`            | Compile library + examples                        |
 | `npm run serve:dev`        | Start dev server on `http://localhost:3000`        |
-| `npm run serve:dist`       | Serve production build on `http://localhost:8080`  |
+| `npm run serve:dist`       | Serve the built examples bundle on `http://localhost:8080` |
 | `npm test`                 | Run full test suite (unit + integration)           |
 | `npm run test:unit`        | Unit tests only                                   |
 | `npm run test:integration` | Integration tests only                            |
@@ -229,6 +325,13 @@ npm run build        # builds library + example bundles
 npm run serve:dev    # http://localhost:3000
 ```
+To preview the built examples with the production-oriented static server:
+```bash
+npm run build
+npm run serve:dist   # http://localhost:8080
+```
 ### Examples
 | #  | Tab              | Category      | Description                                  |
@@ -266,7 +369,6 @@ docker run -p 8080:8080 smart-components
 | [docs/RENDERING-ARCHITECTURE.md](docs/RENDERING-ARCHITECTURE.md)              | Rendering pipeline overview                                  |
 | [docs/RENDERING-PIPELINE-DEEP-DIVE.md](docs/RENDERING-PIPELINE-DEEP-DIVE.md) | Expression parsing, binding resolution, reactivity internals |
 | [docs/templates.md](docs/templates.md)                                        | Template system reference                                    |
-| [docs/BABEL-TO-TYPESCRIPT-MIGRATION.md](docs/BABEL-TO-TYPESCRIPT-MIGRATION.md)| Migration from Babel to TypeScript standalone transpiler      |
 ---

package/dist/core/component-instance-registry.d.ts CHANGED Viewed

File without changes

package/dist/core/component-instance-registry.js CHANGED Viewed

File without changes

package/dist/core/component-metadata-registry.d.ts CHANGED Viewed

File without changes

package/dist/core/component-metadata-registry.js CHANGED Viewed

File without changes

package/dist/core/component-metadata.d.ts CHANGED Viewed

File without changes

package/dist/core/component-metadata.js CHANGED Viewed

File without changes

package/dist/core/smart-component.d.ts CHANGED Viewed

File without changes

package/dist/core/smart-component.js CHANGED Viewed

File without changes

package/dist/decorators/index.d.ts CHANGED Viewed

File without changes

package/dist/decorators/index.js CHANGED Viewed

File without changes

package/dist/decorators/listen.decorator.d.ts CHANGED Viewed

File without changes

package/dist/decorators/listen.decorator.js CHANGED Viewed

File without changes

package/dist/decorators/smart/types.d.ts CHANGED Viewed

File without changes

package/dist/decorators/smart/types.js CHANGED Viewed

File without changes

package/dist/decorators/smart-render.decorator.d.ts CHANGED Viewed

File without changes

package/dist/decorators/smart-render.decorator.js CHANGED Viewed

@@ -1,4 +1,12 @@
 import { Services } from "../providers/service-provider.js";
+function getRequiredDecoratorService(token) {
+    if (!Services.has(token)) {
+        throw new Error(`[SmartRender] Framework services are not available. ` +
+            `Call bootstrapFramework(Services) before importing or defining components ` +
+            `that use @SmartRender. Missing service: '${token}'.`);
+    }
+    return Services.get(token);
+}
 /**
  * @SmartRender decorator - Marks a class as a SmartComponent with declarative configuration.
  *
@@ -28,12 +36,12 @@ export function SmartRender(config) {
                 selector: config.selector,
                 template: config.template || "",
             };
-            Services.get("IComponentMetadataRegistry").register(config.selector, metadata);
+            getRequiredDecoratorService("IComponentMetadataRegistry").register(config.selector, metadata);
             const options = {
                 initializer: config.initializer,
                 lifecycle: config.lifecycle,
             };
-            Services.get("ISmartElementRegistrar").register(config.selector, target, options);
+            getRequiredDecoratorService("ISmartElementRegistrar").register(config.selector, target, options);
         }
         return target;
     };

package/dist/decorators/smart.decorator.d.ts CHANGED Viewed

File without changes

package/dist/decorators/smart.decorator.js CHANGED Viewed

@@ -1,5 +1,13 @@
 import { SmartRender as SmartComponentDecorator } from "./smart-render.decorator.js";
 import { Services } from "../providers/service-provider.js";
+function getRequiredDecoratorService(token) {
+    if (!Services.has(token)) {
+        throw new Error(`[Smart] Framework services are not available. ` +
+            `Call bootstrapFramework(Services) before importing or defining components ` +
+            `that use @Smart. Missing service: '${token}'.`);
+    }
+    return Services.get(token);
+}
 /**
  * Implements the responsibility of providing a functional decorator for SmartComponents.
  *
@@ -23,7 +31,7 @@ export function Smart(selector, setup) {
     if (!setup)
         throw new Error("setup is required");
     const decorator = ((target) => {
-        const factory = Services.get("ISmartComponentFactory");
+        const factory = getRequiredDecoratorService("ISmartComponentFactory");
         const config = factory.captureConfig(setup);
         const EnhancedClass = factory.createEnhancedClass(target, config);
         const InitializerClass = factory.createInitializerClass(config);

package/dist/index.d.ts CHANGED Viewed

File without changes

package/dist/index.js CHANGED Viewed

File without changes

package/dist/providers/default-service-provider.d.ts CHANGED Viewed

File without changes

package/dist/providers/default-service-provider.js CHANGED Viewed

File without changes

package/dist/providers/service-provider.d.ts CHANGED Viewed

File without changes

package/dist/providers/service-provider.interface.d.ts CHANGED Viewed

File without changes

package/dist/providers/service-provider.interface.js CHANGED Viewed

File without changes

package/dist/providers/service-provider.js CHANGED Viewed

File without changes

package/dist/reactive/signal.d.ts CHANGED Viewed

File without changes

package/dist/reactive/signal.js CHANGED Viewed

File without changes

package/dist/registration/smart-element-factory.js CHANGED Viewed

@@ -101,7 +101,7 @@ export class SmartElementFactory {
                     }
                 });
                 const componentId = this.tagName.toLowerCase();
-                const targetRoot = this.attachShadow({ mode: "open" });
+                const targetRoot = this.shadowRoot ?? this.attachShadow({ mode: "open" });
                 // Inherit the document-level data-theme so that Shadow DOM CSS rules
                 // (e.g. Pico CSS :host(:not([data-theme=dark]))) respect the current theme.
                 const docTheme = document.documentElement.getAttribute("data-theme");

package/dist/rendering/bindings/binding-resolver.d.ts CHANGED Viewed

File without changes

package/dist/rendering/bindings/binding-resolver.js CHANGED Viewed

File without changes

package/dist/rendering/bindings/property-extractor.d.ts CHANGED Viewed

File without changes

package/dist/rendering/bindings/property-extractor.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/bindings/property-extractor.interface.js CHANGED Viewed

File without changes

package/dist/rendering/bindings/property-extractor.js CHANGED Viewed

File without changes

package/dist/rendering/bindings/rules-resolver.d.ts CHANGED Viewed

File without changes

package/dist/rendering/bindings/rules-resolver.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/bindings/rules-resolver.interface.js CHANGED Viewed

File without changes

package/dist/rendering/bindings/rules-resolver.js CHANGED Viewed

File without changes

package/dist/rendering/bindings/static-binding-resolver.d.ts CHANGED Viewed

File without changes

package/dist/rendering/bindings/static-binding-resolver.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/bindings/static-binding-resolver.interface.js CHANGED Viewed

File without changes

package/dist/rendering/bindings/static-binding-resolver.js CHANGED Viewed

File without changes

package/dist/rendering/dom/browser-dom-adapter.d.ts CHANGED Viewed

File without changes

package/dist/rendering/dom/browser-dom-adapter.js CHANGED Viewed

File without changes

package/dist/rendering/dom/dom-adapter.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/dom/dom-adapter.interface.js CHANGED Viewed

File without changes

package/dist/rendering/dom/node-types.d.ts CHANGED Viewed

File without changes

package/dist/rendering/dom/node-types.js CHANGED Viewed

File without changes

package/dist/rendering/dom-context/dom-context-factory.d.ts CHANGED Viewed

File without changes

package/dist/rendering/dom-context/dom-context-factory.js CHANGED Viewed

File without changes

package/dist/rendering/dom-context/dom-context.d.ts CHANGED Viewed

File without changes

package/dist/rendering/dom-context/dom-context.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/dom-context/dom-context.interface.js CHANGED Viewed

File without changes

package/dist/rendering/dom-context/dom-context.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/ast.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/ast.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/base.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/base.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/binary.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/binary.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/call.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/call.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/conditional.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/conditional.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/identifier.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/identifier.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/index.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/index.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/literal.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/literal.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/member.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/member.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/unary.evaluator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/evaluators/unary.evaluator.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/expression-parser.service.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/expression-parser.service.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/index.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/index.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/interfaces.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/interfaces.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/parser.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/parser.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/safe-methods.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/safe-methods.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/tokenizer.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/tokenizer.js CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/types.d.ts CHANGED Viewed

File without changes

package/dist/rendering/expression-parser/types.js CHANGED Viewed

File without changes

package/dist/rendering/index.d.ts CHANGED Viewed

File without changes

package/dist/rendering/index.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/host-style-migrator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/host-style-migrator.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/host-style-migrator.interface.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/host-style-migrator.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/index.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/index.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/managed-element-registry.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/managed-element-registry.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/managed-element-resolver.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/managed-element-resolver.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/managed-element-resolver.interface.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/managed-element-resolver.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/outlet-resolver.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/outlet-resolver.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/managed-host/outlet-resolver.interface.js CHANGED Viewed

File without changes

package/dist/rendering/managed-host/outlet-resolver.js CHANGED Viewed

File without changes

package/dist/rendering/pipeline/render-pipeline.d.ts CHANGED Viewed

File without changes

package/dist/rendering/pipeline/render-pipeline.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/pipeline/render-pipeline.interface.js CHANGED Viewed

File without changes

package/dist/rendering/pipeline/render-pipeline.js CHANGED Viewed

File without changes

package/dist/rendering/render-engine.d.ts CHANGED Viewed

File without changes

package/dist/rendering/render-engine.js CHANGED Viewed

File without changes

package/dist/rendering/skeleton/skeleton-renderer.d.ts CHANGED Viewed

File without changes

package/dist/rendering/skeleton/skeleton-renderer.js CHANGED Viewed

File without changes

package/dist/rendering/skeleton/skeleton-validator.d.ts CHANGED Viewed

File without changes

package/dist/rendering/skeleton/skeleton-validator.js CHANGED Viewed

File without changes

package/dist/rendering/templates/compiled-template.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/templates/compiled-template.interface.js CHANGED Viewed

File without changes

package/dist/rendering/templates/composite-token-extractor.d.ts CHANGED Viewed

File without changes

package/dist/rendering/templates/composite-token-extractor.js CHANGED Viewed

File without changes

package/dist/rendering/templates/delimited-token-extractor.d.ts CHANGED Viewed

File without changes

package/dist/rendering/templates/delimited-token-extractor.js CHANGED Viewed

File without changes

package/dist/rendering/templates/html-aware-token-extractor.d.ts CHANGED Viewed

File without changes

package/dist/rendering/templates/html-aware-token-extractor.js CHANGED Viewed

File without changes

package/dist/rendering/templates/html-fragment-parser.interface.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 /**
- * Represents a parsed HTML node from parse5 or similar parser.
+ * Represents a parsed HTML fragment.
  * This type is opaque as the internal structure varies by parser implementation.
  */
 export type ParsedNode = unknown;

package/dist/rendering/templates/html-fragment-parser.interface.js CHANGED Viewed

File without changes

package/dist/rendering/templates/interpolable-content-selector.interface.d.ts CHANGED Viewed

File without changes

package/dist/rendering/templates/interpolable-content-selector.interface.js CHANGED Viewed

File without changes

package/dist/rendering/templates/parse5-fragment-parser.d.ts CHANGED Viewed

@@ -1,10 +1,12 @@
 import { IHtmlFragmentParser, ParsedNode } from "./html-fragment-parser.interface.js";
 /**
- * Implements the responsibility of parsing HTML fragments using parse5.
+ * Implements the responsibility of normalizing HTML fragments for selector traversal.
  *
  * @description
- * Uses parse5 to parse HTML template strings into a structured DOM-like representation.
- * parse5 is a standards-compliant HTML parser suitable for Node.js environments.
+ * The historical class name is preserved for public API compatibility, but the
+ * runtime implementation is intentionally self-contained and does not rely on
+ * external parsing libraries. The selector layer operates on the normalized
+ * HTML string returned by this parser.
  *
  * @example
  * ```typescript
@@ -14,10 +16,10 @@ import { IHtmlFragmentParser, ParsedNode } from "./html-fragment-parser.interfac
  */
 export declare class Parse5FragmentParser implements IHtmlFragmentParser {
     /**
-     * Parses an HTML template string into a parse5 DocumentFragment.
+     * Parses an HTML template string into a normalized fragment representation.
      *
      * @param html - HTML template string to parse
-     * @returns parse5 DocumentFragment AST
+     * @returns Normalized fragment representation
      * @throws Error if html is null or undefined
      *
      * @example

package/dist/rendering/templates/parse5-fragment-parser.js CHANGED Viewed

@@ -1,10 +1,11 @@
-import { parseFragment } from "parse5";
 /**
- * Implements the responsibility of parsing HTML fragments using parse5.
+ * Implements the responsibility of normalizing HTML fragments for selector traversal.
  *
  * @description
- * Uses parse5 to parse HTML template strings into a structured DOM-like representation.
- * parse5 is a standards-compliant HTML parser suitable for Node.js environments.
+ * The historical class name is preserved for public API compatibility, but the
+ * runtime implementation is intentionally self-contained and does not rely on
+ * external parsing libraries. The selector layer operates on the normalized
+ * HTML string returned by this parser.
  *
  * @example
  * ```typescript
@@ -14,10 +15,10 @@ import { parseFragment } from "parse5";
  */
 export class Parse5FragmentParser {
     /**
-     * Parses an HTML template string into a parse5 DocumentFragment.
+     * Parses an HTML template string into a normalized fragment representation.
      *
      * @param html - HTML template string to parse
-     * @returns parse5 DocumentFragment AST
+     * @returns Normalized fragment representation
      * @throws Error if html is null or undefined
      *
      * @example
@@ -30,7 +31,7 @@ export class Parse5FragmentParser {
         if (html === null || html === undefined) {
             throw new Error("Html is required");
         }
-        return parseFragment(html);
+        return html;
     }
 }
 //# sourceMappingURL=parse5-fragment-parser.js.map