@adaas/are-html 0.0.23 → 0.0.25

package/examples/lazy-loading/src/concept.ts

@@ -0,0 +1,116 @@
+import { A_Concept, A_Context } from "@adaas/a-concept";
+import { A_Config, ConfigReader } from "@adaas/a-utils/a-config";
+import { A_Logger, A_LOGGER_ENV_KEYS } from "@adaas/a-utils/a-logger";
+import { A_SignalBus, A_SignalState } from "@adaas/a-utils/a-signal";
+import { A_Polyfill } from "@adaas/a-utils/a-polyfill";
+import {
+    AreContainer,
+    AreInit,
+    AreSignalsContext,
+} from "@adaas/are";
+import {
+    AreRoot,
+    AreHTMLEngine,
+    AreHTMLEngineContext,
+    AreDirectiveIf,
+    AreDirectiveFor,
+    AreDirectiveShow,
+    AreRouteWatcher,
+} from "src";
+
+// ── Eager components (shipped in this bundle) ───────────────────────────────
+import { AppShell } from "./components/AppShell.component";
+import { NavBar } from "./components/NavBar.component";
+import { HomePage } from "./components/HomePage.component";
+import { LazyOutlet } from "./components/LazyOutlet.component";
+
+// ── Runtime ─────────────────────────────────────────────────────────────────
+import { ComponentManifest, ComponentManifestEntry } from "./runtime/ComponentManifest.fragment";
+import { LazyComponentResolver } from "./runtime/LazyComponentResolver.fragment";
+
+// AreRoute must come from are-html (not @adaas/are) so state.has() matches the
+// class NavBar emits — otherwise the bus silently drops every route signal.
+import { AreRoute as AreRouteSignal } from "src/signals/AreRoute.signal";
+
+
+(async () => {
+    try {
+        // 1. Discover available components from the backend BEFORE bootstrapping.
+        //    The set of routes/components is server-driven; lazy ones carry a URL
+        //    the LazyOutlet will dynamically import on first visit.
+        const entries: ComponentManifestEntry[] = await fetch('/api/components')
+            .then(res => res.json())
+            .catch(() => []);
+
+        const manifest = new ComponentManifest({ entries });
+
+        // The engine consults this resolver whenever a node's tag does not match
+        // a registered component: it imports the lazy bundle from the manifest
+        // and the engine registers the returned class globally.
+        const componentResolver = new LazyComponentResolver({ manifest });
+
+        // Empty signals context: the outer <are-root id="app"> has no routing
+        // config, so it renders its body (<app-shell>) and ignores route signals.
+        // LazyOutlet does its own routing independently.
+        const signalsContext = new AreSignalsContext({});
+
+        const container = new AreContainer({
+            name: 'ARE Lazy Loading',
+            components: [
+                // ── Eager UI ─────────────────────────────────────────────
+                AppShell,
+                NavBar,
+                HomePage,
+                LazyOutlet,
+                // ── Directives ───────────────────────────────────────────
+                AreDirectiveIf,
+                AreDirectiveFor,
+                AreDirectiveShow,
+                // ── Engine ───────────────────────────────────────────────
+                A_SignalBus,
+                AreRoot,
+                AreRouteWatcher,
+                ConfigReader,
+                AreHTMLEngine,
+                A_Logger,
+            ],
+            entities: [
+                AreInit,
+                AreRouteSignal,
+            ],
+            fragments: [
+                // Both AreInit AND AreRouteSignal must be in this state, or
+                // state.has() returns false and the bus drops route signals.
+                new A_SignalState([AreInit, AreRouteSignal]),
+                signalsContext,
+                new AreHTMLEngineContext({ container: document }),
+                manifest,
+                componentResolver,
+                new A_Config({
+                    defaults: {
+                        [A_LOGGER_ENV_KEYS.LOG_LEVEL]: 'info',
+                    },
+                }),
+            ],
+        });
+
+        const concept = new A_Concept({
+            name: 'adaas-are-example-lazy-loading',
+            fragments: [
+                new A_Config({
+                    variables: ['CONFIG_VERBOSE', 'DEV_MODE'] as const,
+                    defaults: { CONFIG_VERBOSE: true, DEV_MODE: true },
+                }),
+            ],
+            components: [A_Logger, ConfigReader, A_Polyfill],
+            containers: [container],
+        });
+
+        await concept.load();
+        await concept.start();
+
+    } catch (error) {
+        const logger = A_Context.root.resolve<A_Logger>(A_Logger)!;
+        logger.error(error);
+    }
+})();

package/examples/lazy-loading/src/lazy/AboutPage.component.ts

@@ -0,0 +1,54 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { Are, AreNode } from "@adaas/are";
+import { AreHTMLNode } from "src";
+
+
+/**
+ * About page — LAZY. Built into its own bundle (`/lazy/about-page.js`) and NOT
+ * registered at bootstrap. It is fetched + registered the first time the
+ * `/about` route is visited.
+ *
+ * Authored exactly like an eager component — the only difference is it lives in
+ * `src/lazy/` (its own esbuild entry point) and is `export default`ed so the
+ * loader can grab the class without knowing its name.
+ */
+export class AboutPage extends Are {
+
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode) {
+        node.setContent(`
+            <section class="page">
+                <span class="eyebrow">Lazy · fetched on demand</span>
+                <h1 class="page-title">About this example</h1>
+                <p class="page-lead">
+                    You just triggered a dynamic <code>import('/lazy/about-page.js')</code>.
+                    The class was registered into the running scope and rendered into the
+                    outlet — no page reload, and it wasn't in the initial bundle.
+                </p>
+                <div class="grid">
+                    <div class="card"><h3>Code-split</h3><p>The app and every lazy bundle share framework chunks, so this class <code>extends</code> the same <code>Are</code> runtime.</p></div>
+                    <div class="card"><h3>Backend-driven</h3><p>The server's <code>/api/components</code> manifest decided this page exists and where to fetch it.</p></div>
+                    <div class="card"><h3>Cached</h3><p>Revisit /about — no second network request. The manifest marks it loaded.</p></div>
+                </div>
+            </section>
+        `);
+    }
+
+    @Are.Styles
+    styles(@A_Inject(A_Caller) node: AreHTMLNode) {
+        node.setStyles(`
+            .page { padding: 48px 56px; max-width: 860px; }
+            .eyebrow { display: inline-block; font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; padding: 4px 10px; border-radius: 999px; margin-bottom: 20px; color: #fcd34d; background: rgba(252, 211, 77, 0.12); }
+            .page-title { font-size: 32px; font-weight: 800; color: #f4f4f5; margin-bottom: 14px; letter-spacing: -0.02em; }
+            .page-lead { font-size: 16px; color: #a1a1aa; line-height: 1.7; margin-bottom: 28px; }
+            code { background: #27272a; padding: 2px 6px; border-radius: 4px; color: #a78bfa; font-size: 13px; }
+            .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 16px; }
+            .card { background: #1c1c1f; border: 1px solid #27272a; border-radius: 12px; padding: 20px; }
+            .card h3 { font-size: 15px; font-weight: 600; color: #f4f4f5; margin-bottom: 8px; }
+            .card p { font-size: 13px; color: #71717a; line-height: 1.6; }
+            .card code { font-size: 12px; }
+        `);
+    }
+}
+
+export default AboutPage;

package/examples/lazy-loading/src/lazy/ReportsPage.component.ts

@@ -0,0 +1,56 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { Are, AreNode } from "@adaas/are";
+import { AreHTMLNode } from "src";
+
+
+/**
+ * Reports page — LAZY (`/lazy/reports-page.js`). A heavier page (charts/tables)
+ * is a classic candidate for code-splitting: there's no reason to pay for it on
+ * first paint if most users never open it.
+ */
+export class ReportsPage extends Are {
+
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode) {
+        node.setContent(`
+            <section class="page">
+                <span class="eyebrow">Lazy · fetched on demand</span>
+                <h1 class="page-title">Reports</h1>
+                <p class="page-lead">Heavy, rarely-visited views are ideal lazy-load candidates — they stay out of the critical path.</p>
+                <div class="stats">
+                    <div class="stat"><div class="stat-value">1,284</div><div class="stat-label">Components served</div></div>
+                    <div class="stat"><div class="stat-value">96 ms</div><div class="stat-label">Avg load time</div></div>
+                    <div class="stat"><div class="stat-value">3</div><div class="stat-label">Lazy bundles</div></div>
+                    <div class="stat"><div class="stat-value">100%</div><div class="stat-label">Cache hit on revisit</div></div>
+                </div>
+                <div class="bars">
+                    <div class="bar" style="height: 38%"></div>
+                    <div class="bar" style="height: 62%"></div>
+                    <div class="bar" style="height: 48%"></div>
+                    <div class="bar" style="height: 81%"></div>
+                    <div class="bar" style="height: 55%"></div>
+                    <div class="bar" style="height: 72%"></div>
+                    <div class="bar" style="height: 90%"></div>
+                </div>
+            </section>
+        `);
+    }
+
+    @Are.Styles
+    styles(@A_Inject(A_Caller) node: AreHTMLNode) {
+        node.setStyles(`
+            .page { padding: 48px 56px; max-width: 860px; }
+            .eyebrow { display: inline-block; font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; padding: 4px 10px; border-radius: 999px; margin-bottom: 20px; color: #fcd34d; background: rgba(252, 211, 77, 0.12); }
+            .page-title { font-size: 32px; font-weight: 800; color: #f4f4f5; margin-bottom: 14px; letter-spacing: -0.02em; }
+            .page-lead { font-size: 16px; color: #a1a1aa; line-height: 1.7; margin-bottom: 28px; }
+            .stats { display: grid; grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); gap: 16px; margin-bottom: 32px; }
+            .stat { background: #1c1c1f; border: 1px solid #27272a; border-radius: 12px; padding: 20px; }
+            .stat-value { font-size: 26px; font-weight: 800; color: #a78bfa; }
+            .stat-label { font-size: 12px; color: #71717a; margin-top: 6px; }
+            .bars { display: flex; align-items: flex-end; gap: 12px; height: 180px; padding: 20px; background: #1c1c1f; border: 1px solid #27272a; border-radius: 12px; }
+            .bar { flex: 1; background: linear-gradient(180deg, #a78bfa, #7c3aed); border-radius: 6px 6px 0 0; }
+        `);
+    }
+}
+
+export default ReportsPage;

package/examples/lazy-loading/src/lazy/SettingsPage.component.ts

@@ -0,0 +1,45 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { Are, AreNode } from "@adaas/are";
+import { AreHTMLNode } from "src";
+
+
+/**
+ * Settings page — LAZY (`/lazy/settings-page.js`). Demonstrates that a lazy
+ * component can carry its own interactive markup and styles just like any
+ * eager one.
+ */
+export class SettingsPage extends Are {
+
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode) {
+        node.setContent(`
+            <section class="page">
+                <span class="eyebrow">Lazy · fetched on demand</span>
+                <h1 class="page-title">Settings</h1>
+                <p class="page-lead">A second independently-served bundle. It shares the framework runtime with the app via code-split chunks.</p>
+                <div class="settings">
+                    <label class="row"><span>Dark theme</span><input type="checkbox" checked /></label>
+                    <label class="row"><span>Compact density</span><input type="checkbox" /></label>
+                    <label class="row"><span>Telemetry</span><input type="checkbox" /></label>
+                    <label class="row"><span>Auto-update components</span><input type="checkbox" checked /></label>
+                </div>
+            </section>
+        `);
+    }
+
+    @Are.Styles
+    styles(@A_Inject(A_Caller) node: AreHTMLNode) {
+        node.setStyles(`
+            .page { padding: 48px 56px; max-width: 640px; }
+            .eyebrow { display: inline-block; font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; padding: 4px 10px; border-radius: 999px; margin-bottom: 20px; color: #fcd34d; background: rgba(252, 211, 77, 0.12); }
+            .page-title { font-size: 32px; font-weight: 800; color: #f4f4f5; margin-bottom: 14px; letter-spacing: -0.02em; }
+            .page-lead { font-size: 16px; color: #a1a1aa; line-height: 1.7; margin-bottom: 28px; }
+            .settings { display: flex; flex-direction: column; gap: 2px; border: 1px solid #27272a; border-radius: 12px; overflow: hidden; }
+            .row { display: flex; align-items: center; justify-content: space-between; padding: 16px 20px; background: #1c1c1f; font-size: 14px; color: #e4e4e7; }
+            .row + .row { border-top: 1px solid #27272a; }
+            .row input { width: 18px; height: 18px; accent-color: #a78bfa; }
+        `);
+    }
+}
+
+export default SettingsPage;

package/examples/lazy-loading/src/runtime/ComponentManifest.fragment.ts

@@ -0,0 +1,61 @@
+import { A_Fragment } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame/core";
+
+
+export type ComponentManifestEntry = {
+    /** Route that activates this component. */
+    route: string;
+    /** Custom-element tag (kebab-case of the class name). */
+    tag: string;
+    /** Class name (PascalCase). */
+    name: string;
+    /** Public URL to dynamically import (null when bundled eagerly). */
+    url: string | null;
+    /** Whether the component must be fetched on demand. */
+    lazy: boolean;
+};
+
+
+/**
+ * App-level fragment that holds the component manifest fetched from the backend
+ * (`GET /api/components`) plus a record of which lazy components have already
+ * been loaded + registered into the scope.
+ *
+ * The browser app receives this from the server at bootstrap, so the *set of
+ * available components is backend-driven* — the frontend discovers them at
+ * runtime rather than hard-coding a component list.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-html-example',
+    description: 'Holds the backend-served component manifest and tracks which lazy components have been dynamically imported and registered.'
+})
+export class ComponentManifest extends A_Fragment {
+
+    protected _entries: ComponentManifestEntry[] = [];
+    protected _loaded: Set<string> = new Set();
+
+    constructor(data: { entries: ComponentManifestEntry[] }) {
+        super({ name: 'ComponentManifest' });
+        this._entries = data.entries ?? [];
+    }
+
+    /** All known components (eager + lazy). */
+    list(): ComponentManifestEntry[] {
+        return this._entries;
+    }
+
+    /** Resolve a route to its component descriptor (exact match). */
+    match(route: string): ComponentManifestEntry | undefined {
+        return this._entries.find(entry => entry.route === route);
+    }
+
+    /** Has the lazy bundle for this tag already been imported + registered? */
+    isLoaded(tag: string): boolean {
+        return this._loaded.has(tag);
+    }
+
+    /** Mark a lazy component as loaded so we never re-import it. */
+    markLoaded(tag: string): void {
+        this._loaded.add(tag);
+    }
+}

package/examples/lazy-loading/src/runtime/LazyComponentResolver.fragment.ts

@@ -0,0 +1,77 @@
+import { A_TYPES__Ctor } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame/core";
+import { Are, AreComponentResolver } from "@adaas/are";
+import { ComponentManifest } from "./ComponentManifest.fragment";
+
+
+/**
+ * App-side {@link AreComponentResolver} — the lazy-loading hook the engine
+ * consults whenever a node's tag does NOT resolve to a registered component.
+ *
+ * This is where the "fetch a component from the backend on demand" logic now
+ * lives. The engine (AreLoader) calls {@link resolve} with the unresolved tag;
+ * if the manifest says that tag is a lazy component, we dynamically `import()`
+ * its bundle and hand the class back. The engine then registers that class
+ * GLOBALLY (root scope) so every node can resolve it from here on — we no
+ * longer touch any scope ourselves.
+ *
+ * Compared to the previous hand-rolled `LazyOutlet`, the fetch/import/dedupe
+ * logic is fully decoupled from rendering: the outlet just sets a `<tag>` and
+ * renders; the engine + this resolver handle "where does that class come from".
+ */
+@A_Frame.Define({
+    namespace: 'a-are-html-example',
+    description: 'Resolves unregistered component tags by dynamically importing their backend-served bundle, per the component manifest. Plugged into the engine via AreComponentResolver; returned classes are registered globally by the engine.'
+})
+export class LazyComponentResolver extends AreComponentResolver {
+
+    protected _manifest: ComponentManifest;
+
+    constructor(data: { manifest: ComponentManifest }) {
+        super({ name: 'LazyComponentResolver' });
+        this._manifest = data.manifest;
+    }
+
+    /**
+     * Resolve a tag to its component class, fetching the bundle on demand.
+     *
+     * Returns `undefined` when the tag is not a lazy component in the manifest
+     * (eager components are already registered; plain elements stay plain), or
+     * when it has already been imported (the engine has it registered, so a
+     * second resolve is unnecessary).
+     */
+    async resolve(entity: string): Promise<A_TYPES__Ctor<Are> | undefined> {
+        const target = this._manifest.list().find(item => item.tag === entity);
+
+        if (!target || !target.lazy || !target.url || this._manifest.isLoaded(entity)) {
+            return undefined;
+        }
+
+        const Component = await this.importComponent(target.url);
+
+        if (!Component) {
+            return undefined;
+        }
+
+        this._manifest.markLoaded(entity);
+
+        return Component as A_TYPES__Ctor<Are>;
+    }
+
+    /**
+     * Dynamic import of a component bundle served by the backend.
+     *
+     * Because the app + lazy bundles are code-split against shared framework
+     * chunks, the class returned here `extends` the SAME `Are`/DI runtime the
+     * host app is running.
+     */
+    protected async importComponent(url: string): Promise<Function | undefined> {
+        const mod: Record<string, unknown> = await import(/* @vite-ignore */ url);
+
+        if (typeof mod.default === 'function') {
+            return mod.default as Function;
+        }
+
+        return Object.values(mod).find(value => typeof value === 'function') as Function | undefined;
+    }
+}

package/examples/os-desktop/README.md

@@ -0,0 +1,91 @@
+# ARE · OS Desktop
+
+A macOS-style **operating-system desktop** built with ARE, showing how to manage
+**dynamically installable applications** where **each app is its own bundle with
+its own frontend *and* its own backend**, wired together by **signal-based
+routing**.
+
+```
+┌──────────────────────────────────────────────── menu bar (OSRoute, Selection)
+│  desktop (wallpaper)
+│        ┌────────────── app window (macOS chrome) ──────────────┐
+│        │  Marketing  ·  post-editor | post-preview              │
+│        │  Timeline   ·  gantt-toolbar | gantt-chart             │
+│        └───────────────────────────────────────────────────────┘
+│  HUD (MouseState, Selection)                          dock (OSRoute)
+└──────────────────────────────────────────────────────────────────
+```
+
+## Run
+
+```bash
+npm run example:os-desktop
+# http://localhost:8084
+```
+
+The desktop boots empty. Click the dock's **＋ (Launchpad)** button, **Install**
+an app — that fetches the app's bundle and adds it to the dock — then open it.
+
+## What it demonstrates
+
+### 1. Apps are self-contained bundles (FE + BE), installed at runtime
+Each app is a single code-split bundle exporting a **set** of components plus a
+matching backend:
+
+| App         | Frontend components                          | Backend endpoint                  |
+|-------------|----------------------------------------------|-----------------------------------|
+| Marketing   | `marketing-app` · `post-editor` · `post-preview` | `GET /apps/marketing/api/hashtags` |
+| Timeline    | `gantt-app` · `gantt-toolbar` · `gantt-chart`    | `GET /apps/gantt/api/tasks`        |
+
+The OS kernel (`containers/OS.container.ts`) never imports an app's source. It
+only:
+- advertises descriptors at `GET /api/apps`,
+- builds the shell + every app bundle in **one code-split esbuild pass** (so a
+  lazily-`import()`ed app reuses the SAME framework runtime singletons), and
+- routes `/apps/<id>/api/*` to that app's own backend.
+
+Adding an app = adding one `AppBackend` to the kernel. Installing it in the UI
+(`AppRegistry.install`) makes it appear in the dock; the
+`AppComponentResolver` then lazily imports its bundle on first render — one
+network request per app, however many components it ships.
+
+### 2. Signal-based routing with several signals
+Three OS-wide signals travel on one bus, and many components react to each one
+**independently** — there is no central controller:
+
+| Signal           | Produced by                          | Consumed by                                   |
+|------------------|--------------------------------------|-----------------------------------------------|
+| `OSRoute`        | dock / launchpad / window chrome     | `AppStage` (swaps surface), `MenuBar` (title), `OsDock` (running dot) |
+| `MouseState`     | global `mousemove` (throttled)       | `OsHud` (x/y read-out), `GanttChart` (guide line) |
+| `SelectionState` | global `selectionchange`             | `OsHud` (length), `MenuBar` (chip), `PostPreview` (hashtag hint) |
+
+`AppStage` is a custom **signal outlet**: it maps the current `OSRoute` to one
+surface (`app-window` / `os-launchpad` / empty desktop) and swaps it with the
+engine primitives `clear()` + `render()`, unsubscribing the outgoing subtree
+from the bus first.
+
+> Every dispatched signal type is listed in BOTH `entities` and the
+> `A_SignalState([...])` structure in `src/concept.ts` — otherwise the bus
+> silently drops it.
+
+## Layout
+
+```
+os-desktop/
+├── concept.ts                     # node entry (kernel)
+├── public/index.html              # <are-root id="os"><os-desktop>
+├── containers/
+│   ├── OS.container.ts            # build + serve + /api/apps + app-API routing
+│   └── apps/
+│       ├── AppBackend.ts          # app backend interface
+│       ├── MarketingApp.backend.ts
+│       └── GanttApp.backend.ts
+└── src/
+    ├── concept.ts                 # browser bootstrap (registry + resolver + bus)
+    ├── signals/                   # OSRoute · MouseState · SelectionState
+    ├── runtime/                   # AppRegistry + AppComponentResolver
+    ├── os/                        # shell: desktop, menu bar, dock, hud, stage, window, launchpad
+    └── apps/
+        ├── marketing/             # marketing bundle (FE) + own store
+        └── gantt/                 # gantt bundle (FE) + own store
+```

package/examples/os-desktop/concept.ts

@@ -0,0 +1,54 @@
+import { A_Concept, A_Context } from "@adaas/a-concept";
+import { OSContainer } from "./containers/OS.container";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+import { A_Polyfill } from "@adaas/a-utils/a-polyfill";
+import { A_Config, ENVConfigReader } from "@adaas/a-utils/a-config";
+
+
+/**
+ * Node-side entry point for the OS Desktop example.
+ *
+ * The OSContainer is the "kernel": it builds the OS shell bundle plus one
+ * code-split bundle per app, serves the static desktop SPA, advertises the
+ * installable apps at `/api/apps`, and routes each app's `/apps/<id>/api/*`
+ * calls to that app's own backend.
+ *
+ * In the browser, the desktop boots, you install apps from the Launchpad (each
+ * install lazily fetches that app's bundle), open them in macOS-style windows,
+ * and watch the OS-wide signals (route / mouse / selection) drive the menu bar,
+ * dock and HUD independently.
+ */
+(async () => {
+    try {
+        const Application = new OSContainer({
+            name: 'ARE OS Desktop',
+            components: [
+                A_Polyfill,
+                ENVConfigReader,
+                A_Logger,
+            ],
+            fragments: [
+                new A_Config({
+                    defaults: {
+                        PORT: 8084,
+                        CONFIG_VERBOSE: true,
+                        DEV_MODE: true,
+                    }
+                }),
+            ]
+        });
+
+        const concept = new A_Concept({
+            name: 'adaas-are-example-os-desktop',
+            components: [A_Logger, A_Polyfill, ENVConfigReader],
+            containers: [Application],
+        });
+
+        await concept.load();
+        await concept.start();
+
+    } catch (error) {
+        const logger = A_Context.root.resolve<A_Logger>(A_Logger)!;
+        logger.error(error);
+    }
+})();