@adaas/are-html 0.0.23 → 0.0.25

package/examples/os-desktop/src/runtime/AppComponentResolver.fragment.ts

@@ -0,0 +1,121 @@
+import { A_TYPES__Ctor } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame/core";
+import { Are, AreComponentResolver } from "@adaas/are";
+import { AppDescriptor, AppRegistry } from "./AppRegistry.fragment";
+
+
+/**
+ * AppComponentResolver — the engine's lazy-loading hook for application code.
+ *
+ * The engine ({@link AreComponentResolver}) consults this whenever it renders a
+ * tag that is NOT a registered component. We answer the question "which app
+ * owns this tag, and where do I fetch its class from?".
+ *
+ * The crucial idea: **an app is ONE bundle that exports a SET of components.**
+ * The first time any of an app's tags is requested we dynamically `import()`
+ * the app's single bundle (cached per URL), then pick the right named export
+ * for the requested tag. The engine registers that class globally, so the next
+ * tag from the same app resolves from the already-evaluated module — one
+ * network request per app, however many components it ships.
+ *
+ * Two entry points:
+ *   - {@link resolve} — the lazy path the engine calls on a render miss.
+ *   - {@link preload} — the eager path the Launchpad calls on *install*, so
+ *     "adding an app loads all its components" up front.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-os-desktop',
+    description: 'Resolves unregistered component tags to classes from their owning app bundle (one code-split bundle per app, many components). Plugged into the engine via AreComponentResolver; also exposes preload() to eagerly load every component of an app on install.'
+})
+export class AppComponentResolver extends AreComponentResolver {
+
+    protected _registry: AppRegistry;
+
+    /** Cache of in-flight / settled bundle imports, keyed by bundle URL. */
+    protected _bundles: Map<string, Promise<Record<string, unknown>>> = new Map();
+
+    /** Tags already handed to the engine (registered) — skip re-resolving. */
+    protected _resolved: Set<string> = new Set();
+
+    constructor(data: { registry: AppRegistry }) {
+        super({ name: 'AppComponentResolver' });
+        this._registry = data.registry;
+    }
+
+    /**
+     * Lazy path: resolve a single tag on a render miss. Returns `undefined` for
+     * tags that do not belong to any installed app (they stay plain elements)
+     * or that the engine already has registered.
+     */
+    async resolve(entity: string): Promise<A_TYPES__Ctor<Are> | undefined> {
+        if (this._resolved.has(entity)) {
+            return undefined;
+        }
+
+        const app = this._registry.appByComponentTag(entity);
+
+        if (!app) {
+            return undefined;
+        }
+
+        const exportName = this.exportNameForTag(app, entity);
+
+        if (!exportName) {
+            return undefined;
+        }
+
+        const mod = await this.importBundle(app.bundle);
+        const Component = mod[exportName];
+
+        if (typeof Component !== 'function') {
+            return undefined;
+        }
+
+        this._resolved.add(entity);
+
+        return Component as A_TYPES__Ctor<Are>;
+    }
+
+    /**
+     * Eager path: fetch an app's WHOLE bundle (all its components) on install,
+     * so "adding an app loads all its necessary components" up front. Called by
+     * the Launchpad. It only *warms* the import cache and returns the classes —
+     * it deliberately does NOT mark the tags resolved, so the engine still does
+     * the actual global registration lazily on first render (now instant,
+     * because the bundle is already in memory). This keeps a single owner of
+     * registration (the engine) while making install the moment the code lands.
+     */
+    async preload(app: AppDescriptor): Promise<A_TYPES__Ctor<Are>[]> {
+        const mod = await this.importBundle(app.bundle);
+        const classes: A_TYPES__Ctor<Are>[] = [];
+
+        for (const ref of app.components) {
+            const Component = mod[ref.export];
+            if (typeof Component === 'function') {
+                classes.push(Component as A_TYPES__Ctor<Are>);
+            }
+        }
+
+        return classes;
+    }
+
+    protected exportNameForTag(app: AppDescriptor, tag: string): string | undefined {
+        return app.components.find(c => c.tag === tag)?.export;
+    }
+
+    /**
+     * Dynamic import of an app bundle, de-duplicated per URL. Because the shell
+     * and every app bundle are code-split against shared framework chunks, the
+     * classes returned here `extend` the SAME `Are`/DI runtime the OS shell runs.
+     */
+    protected importBundle(url: string): Promise<Record<string, unknown>> {
+        let pending = this._bundles.get(url);
+
+        if (!pending) {
+            pending = import(/* @vite-ignore */ url) as Promise<Record<string, unknown>>;
+            this._bundles.set(url, pending);
+        }
+
+        return pending;
+    }
+}

package/examples/os-desktop/src/runtime/AppRegistry.fragment.ts

@@ -0,0 +1,104 @@
+import { A_Fragment } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame/core";
+
+
+/** A single component contributed by an app's bundle. */
+export type AppComponentRef = {
+    /** Custom-element tag (kebab-case of the class name). */
+    tag: string;
+    /** Named export inside the app bundle that provides this component's class. */
+    export: string;
+};
+
+/**
+ * The public descriptor of an installable application, served by the OS kernel
+ * at `GET /api/apps`. It is the single contract between the OS shell and an
+ * app: the OS never imports an app's source — it only knows its metadata, the
+ * URL of its single code-split bundle, and which tags that bundle provides.
+ */
+export type AppDescriptor = {
+    /** Stable id, also the URL segment: `/app/<id>`. */
+    id: string;
+    /** Human-facing name shown in the dock and window title. */
+    name: string;
+    /** Emoji used as the app icon. */
+    icon: string;
+    /** Accent colour for the app's window chrome / dock highlight. */
+    accent: string;
+    /** Short marketing line shown in the Launchpad. */
+    tagline: string;
+    /** Root component tag the OS mounts inside the window (e.g. `marketing-app`). */
+    rootTag: string;
+    /** Public URL of the app's single (code-split) bundle. */
+    bundle: string;
+    /** Base path of the app's OWN backend API (e.g. `/apps/marketing/api`). */
+    api: string;
+    /** Every component the bundle exports, so any of its tags can be resolved. */
+    components: AppComponentRef[];
+};
+
+
+/**
+ * AppRegistry — the OS's view of the application catalogue.
+ *
+ * It holds the list of *available* apps (discovered from the backend) and the
+ * set the user has *installed*. Installing an app is a frontend-only state
+ * change here (the bundle is fetched lazily on demand by the resolver); a real
+ * OS would persist this and gate it behind auth/licensing.
+ *
+ * The registry is a plain data fragment shared across the OS shell components
+ * (Dock, Launchpad, MenuBar, AppStage) and the {@link AppComponentResolver}.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-os-desktop',
+    description: 'Holds the catalogue of available applications (from GET /api/apps) and the set the user has installed. Shared by the OS shell components and the AppComponentResolver to map component tags to their owning app bundle.'
+})
+export class AppRegistry extends A_Fragment {
+
+    protected _available: AppDescriptor[] = [];
+    protected _installed: Set<string> = new Set();
+
+    constructor(data: { available: AppDescriptor[]; installed?: string[] }) {
+        super({ name: 'AppRegistry' });
+        this._available = data.available ?? [];
+        for (const id of data.installed ?? []) {
+            this._installed.add(id);
+        }
+    }
+
+    /** Every app the backend offers. */
+    available(): AppDescriptor[] {
+        return this._available;
+    }
+
+    /** Apps the user has installed, in catalogue order. */
+    installed(): AppDescriptor[] {
+        return this._available.filter(app => this._installed.has(app.id));
+    }
+
+    isInstalled(id: string): boolean {
+        return this._installed.has(id);
+    }
+
+    install(id: string): void {
+        if (this._available.some(app => app.id === id)) {
+            this._installed.add(id);
+        }
+    }
+
+    uninstall(id: string): void {
+        this._installed.delete(id);
+    }
+
+    /** Look up an app by its id. */
+    get(id: string): AppDescriptor | undefined {
+        return this._available.find(app => app.id === id);
+    }
+
+    /** Find the installed app that owns a given component tag (root or child). */
+    appByComponentTag(tag: string): AppDescriptor | undefined {
+        return this.installed().find(app =>
+            app.rootTag === tag || app.components.some(c => c.tag === tag)
+        );
+    }
+}

package/examples/os-desktop/src/signals/MouseState.signal.ts

@@ -0,0 +1,34 @@
+import { AreSignal } from "@adaas/are";
+import { A_Frame } from "@adaas/a-frame/core";
+
+
+/**
+ * MouseState — the live pointer-position signal.
+ *
+ * Emitted (throttled) from a global `mousemove` listener wired up in the
+ * browser bootstrap. It is a *state* signal, not an event: the bus keeps only
+ * the latest value, so any component that mounts later still sees the current
+ * pointer position.
+ *
+ * This example uses it to drive the corner HUD's live coordinates and to prove
+ * that several unrelated signal TYPES can travel the same bus and be consumed
+ * by `@Are.Signal(MouseState)` typed handlers without interfering with routing.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-os-desktop',
+    description: 'Live pointer-position state signal {x, y}. Emitted throttled from a global mousemove listener and consumed by the HUD via a typed @Are.Signal(MouseState) handler.'
+})
+export class MouseState extends AreSignal<{ x: number; y: number }> {
+
+    constructor(x: number, y: number) {
+        super({ data: { x, y } });
+    }
+
+    get x(): number {
+        return this.data.x;
+    }
+
+    get y(): number {
+        return this.data.y;
+    }
+}

package/examples/os-desktop/src/signals/OSRoute.signal.ts

@@ -0,0 +1,37 @@
+import { A_Signal } from "@adaas/a-utils/a-signal";
+import { AreSignal } from "@adaas/are";
+import { A_Frame } from "@adaas/a-frame/core";
+
+
+/**
+ * OSRoute — the routing signal for the OS desktop.
+ *
+ * The OS uses URL-style routes to decide what the screen shows:
+ *   - `/` or `/desktop`  → empty desktop (wallpaper + dock, no window)
+ *   - `/launchpad`       → the App Store overlay (install apps)
+ *   - `/app/<id>`        → the focused application window for app `<id>`
+ *
+ * Dispatched by the Dock, the Launchpad and the window chrome. Multiple
+ * components react to it independently (the AppStage swaps the visible surface,
+ * the MenuBar updates the active-app title, the Dock highlights the running
+ * app) — which is the whole point of signal-based routing: one signal, many
+ * independent reactions, no shared controller.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-os-desktop',
+    description: 'OS routing signal carrying the active route (/desktop, /launchpad, /app/<id>). Drives which surface the desktop shows and is consumed independently by the AppStage, MenuBar and Dock.'
+})
+export class OSRoute extends AreSignal<{ path: string }> {
+
+    constructor(path: string) {
+        super({ data: { path } });
+    }
+
+    get path(): string {
+        return this.data.path;
+    }
+
+    compare(other: A_Signal<{ path: string }>): boolean {
+        return this.data.path === other.data.path;
+    }
+}

package/examples/os-desktop/src/signals/SelectionState.signal.ts

@@ -0,0 +1,34 @@
+import { AreSignal } from "@adaas/are";
+import { A_Frame } from "@adaas/a-frame/core";
+
+
+/**
+ * SelectionState — the current text-selection signal.
+ *
+ * Emitted from a global `selectionchange` listener wired up in the browser
+ * bootstrap. Carries the selected text and its length. Like {@link MouseState}
+ * it is a *state* signal — the bus retains the latest selection.
+ *
+ * Two unrelated consumers react to it, demonstrating cross-component reuse of a
+ * single signal: the OS HUD shows "N chars selected", and the Marketing app
+ * (when open) offers to turn the current selection into a hashtag. Neither
+ * consumer knows about the other.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-os-desktop',
+    description: 'Current text-selection state signal {text, length}. Emitted from a global selectionchange listener and consumed independently by the OS HUD and the Marketing app.'
+})
+export class SelectionState extends AreSignal<{ text: string; length: number }> {
+
+    constructor(text: string) {
+        super({ data: { text, length: text.length } });
+    }
+
+    get text(): string {
+        return this.data.text;
+    }
+
+    get length(): number {
+        return this.data.length;
+    }
+}

package/examples/signal-routing/dist/index.html

@@ -13,6 +13,6 @@
 <body>
   <are-root id="app"><app-shell></app-shell></are-root>
 
-  <script type="module" src="./mqiwo23h-bhcolu.js"></script>
+  <script type="module" src="./mqp8hgce-4d6rh0.js"></script>
 </body>
 </html>