@adaas/are-html 0.0.23 → 0.0.24

package/examples/os-desktop/src/apps/marketing/PostPreview.component.ts

@@ -0,0 +1,110 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { Are, AreNode } from "@adaas/are";
+import { AreHTMLNode } from "src";
+import { MarketingStore } from "./MarketingStore";
+import { SelectionState } from "../../signals/SelectionState.signal";
+
+
+/**
+ * PostPreview — the live LinkedIn-style preview of the Marketing app.
+ *
+ * It mirrors the app's own {@link MarketingStore} (updated by the editor) and
+ * also listens to the OS-wide {@link SelectionState} signal: whatever text the
+ * user selects anywhere on the desktop is offered as a hashtag. Updates are
+ * applied imperatively to the rendered DOM so the editor's textarea never loses
+ * focus and so there is no teardown to coordinate.
+ */
+export class PostPreview extends Are {
+
+    protected _unsubscribe?: () => void;
+
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode) {
+        node.setContent(`
+            <article class="pp">
+                <header class="pp-top">
+                    <div class="pp-avatar">A</div>
+                    <div>
+                        <div class="pp-name">ARE Platform</div>
+                        <div class="pp-sub">Runtime · 1m · 🌐</div>
+                    </div>
+                </header>
+                <p class="pp-body">${this.escape(MarketingStore.text)}</p>
+                <div class="pp-sel" hidden></div>
+                <footer class="pp-actions">
+                    <span>👍 Like</span><span>💬 Comment</span><span>↪ Share</span>
+                </footer>
+            </article>
+        `);
+    }
+
+    @Are.onAfterMount
+    onMount() {
+        this._unsubscribe = MarketingStore.subscribe(() => {
+            const el = document.querySelector('.pp-body');
+            if (el) el.textContent = MarketingStore.text;
+        });
+    }
+
+    @Are.onBeforeUnmount
+    onUnmount() {
+        this._unsubscribe?.();
+        this._unsubscribe = undefined;
+    }
+
+    @Are.Signal(SelectionState)
+    onSelection(@A_Inject(SelectionState) signal: SelectionState) {
+        const el = document.querySelector('.pp-sel') as HTMLElement | null;
+        if (!el) return;
+
+        const text = signal.text.trim();
+        if (text.length) {
+            const tag = text.replace(/\s+/g, '').replace(/[^\w]/g, '').slice(0, 24);
+            el.hidden = false;
+            el.textContent = tag ? `Selected on desktop → add #${tag}` : `Selected ${signal.length} characters`;
+        } else {
+            el.hidden = true;
+        }
+    }
+
+    protected escape(text: string): string {
+        return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    }
+
+    @Are.Styles
+    styles(@A_Inject(A_Caller) node: AreHTMLNode) {
+        node.setStyles(`
+            .pp {
+                margin: 22px 24px;
+                padding: 18px;
+                border-radius: 14px;
+                background: #ffffff;
+                color: #1d2226;
+                box-shadow: 0 12px 30px rgba(0,0,0,0.25);
+                align-self: start;
+            }
+            .pp-top { display: flex; align-items: center; gap: 12px; margin-bottom: 12px; }
+            .pp-avatar {
+                width: 44px; height: 44px; border-radius: 50%;
+                display: flex; align-items: center; justify-content: center;
+                background: #2f6df6; color: white; font-weight: 700;
+            }
+            .pp-name { font-weight: 700; font-size: 14px; }
+            .pp-sub { font-size: 12px; color: #66707a; }
+            .pp-body { font-size: 14px; line-height: 1.55; white-space: pre-wrap; word-break: break-word; }
+            .pp-sel {
+                margin-top: 12px;
+                padding: 8px 12px;
+                border-radius: 8px;
+                background: #eaf1ff;
+                color: #2f6df6;
+                font-size: 12px;
+                font-weight: 600;
+            }
+            .pp-actions {
+                display: flex; gap: 18px; margin-top: 14px; padding-top: 12px;
+                border-top: 1px solid #e6e9ec; color: #66707a; font-size: 13px; font-weight: 600;
+            }
+        `);
+    }
+}

package/examples/os-desktop/src/apps/marketing/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Marketing app bundle entry.
+ *
+ * This is the ESM module that the OS lazily `import()`s when the user installs
+ * or opens the Marketing app. It exports the app's ENTIRE component set — the
+ * AppComponentResolver picks each class out of this module by the `export` name
+ * declared in the app descriptor (see MarketingApp.backend.ts).
+ *
+ * One bundle, one backend, three components.
+ */
+export { MarketingApp } from "./MarketingApp.component";
+export { PostEditor } from "./PostEditor.component";
+export { PostPreview } from "./PostPreview.component";
+
+import { MarketingApp } from "./MarketingApp.component";
+export default MarketingApp;

package/examples/os-desktop/src/concept.ts

@@ -0,0 +1,126 @@
+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";
+
+// ── OS shell components (eager) ─────────────────────────────────────────────
+import { OsDesktop } from "./os/Desktop.component";
+import { MenuBar } from "./os/MenuBar.component";
+import { OsHud } from "./os/Hud.component";
+import { OsDock } from "./os/Dock.component";
+import { AppStage } from "./os/AppStage.component";
+import { AppWindow } from "./os/AppWindow.component";
+import { OsLaunchpad } from "./os/Launchpad.component";
+
+// ── Runtime (app catalogue + lazy resolver) ─────────────────────────────────
+import { AppRegistry, AppDescriptor } from "./runtime/AppRegistry.fragment";
+import { AppComponentResolver } from "./runtime/AppComponentResolver.fragment";
+
+// ── OS signals ──────────────────────────────────────────────────────────────
+import { OSRoute } from "./signals/OSRoute.signal";
+import { MouseState } from "./signals/MouseState.signal";
+import { SelectionState } from "./signals/SelectionState.signal";
+
+
+(async () => {
+    try {
+        // 1. Discover the installable apps from the OS kernel. Each descriptor
+        //    carries the app's bundle URL + the component tags that bundle
+        //    provides, so the resolver can lazily import it on demand.
+        const available: AppDescriptor[] = await fetch('/api/apps')
+            .then(res => res.json())
+            .catch(() => []);
+
+        // The catalogue starts with nothing installed — the user installs apps
+        // from the Launchpad, which is exactly the flow this example shows.
+        const registry = new AppRegistry({ available });
+
+        // The engine consults this whenever it renders an unregistered tag: it
+        // imports the owning app's bundle (one per app) and hands back the class.
+        const componentResolver = new AppComponentResolver({ registry });
+
+        // Empty signals context: <are-root id="os"> just renders its body
+        // (<os-desktop>); all OS routing is done by the AppStage reacting to
+        // OSRoute, not by are-root conditions.
+        const signalsContext = new AreSignalsContext({});
+
+        const container = new AreContainer({
+            name: 'ARE OS Desktop',
+            components: [
+                // ── OS shell ─────────────────────────────────────────────
+                OsDesktop,
+                MenuBar,
+                OsHud,
+                OsDock,
+                AppStage,
+                AppWindow,
+                OsLaunchpad,
+                // ── Directives ───────────────────────────────────────────
+                AreDirectiveIf,
+                AreDirectiveFor,
+                AreDirectiveShow,
+                // ── Engine ───────────────────────────────────────────────
+                A_SignalBus,
+                AreRoot,
+                AreRouteWatcher,
+                ConfigReader,
+                AreHTMLEngine,
+                A_Logger,
+            ],
+            entities: [
+                AreInit,
+                OSRoute,
+                MouseState,
+                SelectionState,
+            ],
+            fragments: [
+                // EVERY dispatched signal type must appear here too, or
+                // state.has() returns false and the bus drops the signal.
+                new A_SignalState([AreInit, OSRoute, MouseState, SelectionState]),
+                signalsContext,
+                new AreHTMLEngineContext({ container: document }),
+                registry,
+                componentResolver,
+                new A_Config({
+                    defaults: {
+                        [A_LOGGER_ENV_KEYS.LOG_LEVEL]: 'info',
+                    },
+                }),
+            ],
+        });
+
+        const concept = new A_Concept({
+            name: 'adaas-are-example-os-desktop',
+            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/os-desktop/src/os/AppStage.component.ts

@@ -0,0 +1,112 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { Are, AreNode, AreSignalsContext } from "@adaas/are";
+import { AreHTMLNode } from "src";
+import { OSRoute } from "../signals/OSRoute.signal";
+
+
+/**
+ * AppStage — the routed surface of the desktop.
+ *
+ * This is the OS's custom signal outlet. It maps the current {@link OSRoute} to
+ * exactly one of three surfaces and swaps it in via the engine primitives
+ * (`clear()` + `render()`):
+ *   - `/app/<id>`  → `<app-window>` (the window chrome reads the route to pick
+ *                    the app and mounts its lazily-resolved root component).
+ *   - `/launchpad` → `<os-launchpad>` (the App Store overlay).
+ *   - anything else → nothing (the bare desktop).
+ *
+ * Switching between two apps keeps the tag (`app-window`) but is a different
+ * route, so the stage tears the old window down and builds a fresh one — which
+ * is why it keys on the full route, not just the tag. Before tearing a surface
+ * down it unsubscribes that subtree from the bus (same discipline AreRoot uses)
+ * so a detached app stops reacting to signals.
+ */
+export class AppStage extends Are {
+
+    protected _renderedKey: string = '';
+
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode) {
+        const route = document.location.pathname || '/';
+        this._renderedKey = this.surfaceKey(route);
+        const tag = this.surfaceTag(route);
+        if (tag) {
+            node.setContent(`<${tag}></${tag}>`);
+        }
+    }
+
+    @Are.Signal(OSRoute)
+    async onRoute(
+        @A_Inject(A_Caller) node: AreNode,
+        @A_Inject(OSRoute) signal: OSRoute,
+        @A_Inject(AreSignalsContext) signalsContext?: AreSignalsContext,
+    ) {
+        const route = signal.path;
+        const key = this.surfaceKey(route);
+
+        // Same surface already on screen — nothing to swap.
+        if (key === this._renderedKey) {
+            return;
+        }
+
+        // Unsubscribe the outgoing surface (it may contain app components that
+        // subscribed to the bus) before detaching it, so a torn-down app never
+        // reacts to a later signal on a scope that no longer exists.
+        if (signalsContext) {
+            for (const child of [...node.children]) {
+                for (const subscriber of this.collectSubscribers(child, signalsContext)) {
+                    signalsContext.unsubscribe(subscriber);
+                }
+            }
+        }
+
+        await node.clear();
+
+        const tag = this.surfaceTag(route);
+        if (tag) {
+            node.setContent(`<${tag}></${tag}>`);
+        }
+
+        this._renderedKey = key;
+        await node.render();
+    }
+
+    /** A stable key per visible surface (distinct apps must differ). */
+    protected surfaceKey(route: string): string {
+        if (route.startsWith('/app/')) return route;
+        if (route === '/launchpad') return '/launchpad';
+        return '/desktop';
+    }
+
+    /** The component tag to mount for a route ('' = empty desktop). */
+    protected surfaceTag(route: string): string {
+        if (route.startsWith('/app/')) return 'app-window';
+        if (route === '/launchpad') return 'os-launchpad';
+        return '';
+    }
+
+    protected collectSubscribers(
+        node: AreNode,
+        signalsContext: AreSignalsContext,
+    ): AreNode[] {
+        const result: AreNode[] = [];
+        const queue: AreNode[] = [node];
+
+        while (queue.length > 0) {
+            const current = queue.shift()!;
+            if (signalsContext.subscribers.has(current)) {
+                result.push(current);
+            }
+            queue.push(...current.children);
+        }
+
+        return result;
+    }
+
+    @Are.Styles
+    styles(@A_Inject(A_Caller) node: AreHTMLNode) {
+        node.setStyles(`
+            app-stage { display: contents; }
+        `);
+    }
+}

package/examples/os-desktop/src/os/AppWindow.component.ts

@@ -0,0 +1,102 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { A_SignalBus } from "@adaas/a-utils/a-signal";
+import { Are, AreEvent, AreNode } from "@adaas/are";
+import { AreHTMLNode } from "src";
+import { AppRegistry } from "../runtime/AppRegistry.fragment";
+import { OSRoute } from "../signals/OSRoute.signal";
+
+
+/**
+ * AppWindow — the macOS-style window chrome that hosts a running app.
+ *
+ * It reads the current `/app/<id>` route, looks the app up in the
+ * {@link AppRegistry}, draws the title bar (traffic-light controls + app name)
+ * and mounts the app's ROOT tag in its body. That root tag is (usually) not a
+ * registered component yet — the engine resolves it through the
+ * AppComponentResolver, which imports the app's bundle. The window neither
+ * knows nor cares where the app's code comes from.
+ *
+ * The red traffic-light closes the window by routing back to `/desktop`.
+ */
+export class AppWindow extends Are {
+
+    @Are.Template
+    template(
+        @A_Inject(A_Caller) node: AreNode,
+        @A_Inject(AppRegistry) registry: AppRegistry,
+    ) {
+        const id = (document.location.pathname.match(/^\/app\/([^/]+)/) || [])[1];
+        const app = id ? registry.get(id) : undefined;
+
+        if (!app) {
+            node.setContent(`<div class="win win-missing">Application not found.</div>`);
+            return;
+        }
+
+        node.setContent(`
+            <div class="win" style="--accent:${app.accent}">
+                <header class="win-bar">
+                    <div class="traffic">
+                        <button class="tl tl-red" @click="$close()" title="Close"></button>
+                        <span class="tl tl-amber"></span>
+                        <span class="tl tl-green"></span>
+                    </div>
+                    <div class="win-title">${app.icon} ${app.name}</div>
+                    <div class="win-spacer"></div>
+                </header>
+                <div class="win-body">
+                    <${app.rootTag}></${app.rootTag}>
+                </div>
+            </div>
+        `);
+    }
+
+    @Are.EventHandler
+    close(
+        @A_Inject(AreEvent) event: AreEvent,
+        @A_Inject(A_SignalBus) bus: A_SignalBus,
+    ) {
+        (event.get('native') as MouseEvent)?.preventDefault();
+        history.pushState({}, '', '/desktop');
+        bus.next(new OSRoute('/desktop'));
+    }
+
+    @Are.Styles
+    styles(@A_Inject(A_Caller) node: AreHTMLNode) {
+        node.setStyles(`
+            .win {
+                width: min(960px, 86vw);
+                height: min(620px, 80vh);
+                display: flex;
+                flex-direction: column;
+                border-radius: 14px;
+                overflow: hidden;
+                background: #16131f;
+                border: 1px solid rgba(255,255,255,0.1);
+                box-shadow: 0 40px 120px rgba(0,0,0,0.6), 0 0 0 1px rgba(0,0,0,0.4);
+                animation: win-in 0.22s cubic-bezier(0.2, 0.8, 0.2, 1);
+            }
+            @keyframes win-in {
+                from { opacity: 0; transform: translateY(14px) scale(0.97); }
+                to   { opacity: 1; transform: translateY(0) scale(1); }
+            }
+            .win-bar {
+                display: flex;
+                align-items: center;
+                height: 40px;
+                padding: 0 14px;
+                background: linear-gradient(180deg, color-mix(in srgb, var(--accent, #6d5fd0) 26%, #221b33), #1a1526);
+                border-bottom: 1px solid rgba(255,255,255,0.06);
+            }
+            .traffic { display: flex; gap: 8px; width: 80px; }
+            .tl { width: 12px; height: 12px; border-radius: 50%; border: none; padding: 0; cursor: default; }
+            .tl-red { background: #ff5f57; cursor: pointer; }
+            .tl-amber { background: #febc2e; }
+            .tl-green { background: #28c840; }
+            .win-title { flex: 1; text-align: center; font-size: 13px; font-weight: 600; color: rgba(245,245,247,0.9); }
+            .win-spacer { width: 80px; }
+            .win-body { flex: 1; overflow: auto; background: #14111d; }
+            .win-missing { padding: 40px; color: #a1a1aa; }
+        `);
+    }
+}

package/examples/os-desktop/src/os/Desktop.component.ts

@@ -0,0 +1,106 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { A_SignalBus } from "@adaas/a-utils/a-signal";
+import { Are, AreNode } from "@adaas/are";
+import { AreHTMLNode } from "src";
+import { OSRoute } from "../signals/OSRoute.signal";
+import { MouseState } from "../signals/MouseState.signal";
+import { SelectionState } from "../signals/SelectionState.signal";
+
+
+/**
+ * Desktop — the OS shell root.
+ *
+ * It only lays out the persistent surfaces; every dynamic behaviour lives in a
+ * child that reacts to signals on its own:
+ *   - `<menu-bar>`   — top bar, reacts to OSRoute + SelectionState.
+ *   - `<app-stage>`  — the routed surface (window / launchpad / empty desktop).
+ *   - `<os-hud>`     — corner read-out, reacts to MouseState + SelectionState.
+ *   - `<os-dock>`    — bottom dock, reacts to OSRoute.
+ *
+ * There is no central controller wiring these together — the signal bus is the
+ * only coupling, which is exactly what "signal-based routing" buys you.
+ *
+ * Tag: `<os-desktop>` (class name must be `toPascalCase('os-desktop')`).
+ */
+export class OsDesktop extends Are {
+
+    protected _lastMouse: number = 0;
+
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode) {
+        node.setContent(`
+            <div class="os">
+                <menu-bar></menu-bar>
+                <div class="os-stage">
+                    <app-stage></app-stage>
+                </div>
+                <os-hud></os-hud>
+                <os-dock></os-dock>
+            </div>
+        `);
+    }
+
+    /**
+     * Wire the three global signals into the bus once the shell is mounted.
+     * This is the single producer for the OS-wide signals:
+     *   - pointer movement   → {@link MouseState} (throttled),
+     *   - text selection     → {@link SelectionState},
+     *   - browser navigation → {@link OSRoute} (back/forward).
+     *
+     * The listeners are attached on the next animation frame — i.e. AFTER the
+     * engine's atomic initial mount has fully settled. The browser fires a
+     * spurious `selectionchange` while the document is being built; dispatching
+     * a signal into the engine mid-mount would race the first paint, so we wait
+     * for the frame boundary before any signal can flow.
+     *
+     * There is no initial OSRoute dispatch: every route-aware surface
+     * (MenuBar / Dock / AppStage) already reads `location.pathname` in its
+     * template, so the first paint is correct without a signal.
+     */
+    @Are.onAfterMount
+    onMount(@A_Inject(A_SignalBus) bus: A_SignalBus) {
+        requestAnimationFrame(() => {
+            window.addEventListener('mousemove', (event: MouseEvent) => {
+                const now = Date.now();
+                if (now - this._lastMouse < 100) return;   // ~10Hz throttle
+                this._lastMouse = now;
+                bus.next(new MouseState(event.clientX, event.clientY));
+            });
+
+            document.addEventListener('selectionchange', () => {
+                const text = (window.getSelection()?.toString() || '');
+                bus.next(new SelectionState(text));
+            });
+
+            window.addEventListener('popstate', () => {
+                bus.next(new OSRoute(window.location.pathname || '/'));
+            });
+        });
+    }
+
+    @Are.Styles
+    styles(@A_Inject(A_Caller) node: AreHTMLNode) {
+        node.setStyles(`
+            .os {
+                position: relative;
+                width: 100vw;
+                height: 100vh;
+                overflow: hidden;
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                color: #f5f5f7;
+                background:
+                    radial-gradient(120% 120% at 20% 0%, #5b3fb0 0%, transparent 55%),
+                    radial-gradient(120% 120% at 100% 30%, #b03f8a 0%, transparent 50%),
+                    linear-gradient(160deg, #1d1033 0%, #0c0a1a 60%, #050410 100%);
+                user-select: none;
+            }
+            .os-stage {
+                position: absolute;
+                inset: 28px 0 0 0;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+            }
+        `);
+    }
+}