@preact-mvc/core 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,96 @@
+# @preact-mvc/core
+
+[![CI](https://github.com/jwhenry3/preact-mvc/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jwhenry3/preact-mvc/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jwhenry3/preact-mvc/graph/badge.svg?branch=main)](https://codecov.io/gh/jwhenry3/preact-mvc)
+[![Socket Badge](https://badge.socket.dev/npm/package/@preact-mvc/core)](https://badge.socket.dev/npm/package/@preact-mvc/core)
+
+Angular-inspired architecture rendered by Preact: `@Module`/`@Component`
+decorators, hierarchical dependency injection, class-based `View`
+components, controllers, an injector-scoped router, and signal reactivity
+via `@preact/signals` — all over plain JSX, with no template compiler.
+
+**[preact-mvc — documentation](https://jwhenry3.github.io/preact-mvc/docs/overview/)**
+
+## Install
+
+```bash
+npm install @preact-mvc/core preact @preact/signals
+```
+
+Point JSX at Preact (`tsconfig.json`):
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  }
+}
+```
+
+## A view is a class
+
+`View` subclasses are constructed once per mount inside their own injector
+scope — `inject()` works in field initializers and constructors, `render()`
+stays hook-free, and signals drive re-rendering:
+
+```tsx
+import { Component, View, inject, signal, computed } from '@preact-mvc/core';
+
+@Component()
+export class CounterView extends View {
+  count = signal(0);
+  doubled = computed(() => this.count.value * 2);
+
+  render() {
+    return (
+      <section>
+        <button onClick={() => (this.count.value -= 1)}>−</button>
+        <span>{this.count.value}</span>
+        <button onClick={() => (this.count.value += 1)}>+</button>
+        <p>doubled: {this.doubled.value}</p>
+      </section>
+    );
+  }
+}
+```
+
+## Modules are the app map
+
+```ts
+import { Module, RouterModule } from '@preact-mvc/core';
+import { AppShell } from './app.shell';
+import { routes } from './app.routes';
+
+@Module({
+  imports: [RouterModule.forRoot(routes)],
+  providers: [{ provide: API_URL, useValue: '/api' }],
+  bootstrap: [AppShell],
+})
+export class AppModule {}
+```
+
+```ts
+// main.tsx
+import { bootstrap } from '@preact-mvc/core';
+import { AppModule } from './app/app.module';
+
+bootstrap(AppModule, document.getElementById('app')!);
+```
+
+`components`/`bootstrap` declarations are enforced ownership: a declared
+view may only mount where its module's injector is an ancestor.
+Undeclared views mount anywhere — structure is opt-in per declaration.
+
+## DI, controllers, router
+
+- `@Injectable`/`@Controller` classes resolve through the element-injector
+  hierarchy — view providers → module providers → root, closest scope wins.
+- `OnInit`/`OnDestroy` lifecycle plus `DestroyRef` make teardown
+  declaration-driven instead of `useEffect` cleanup.
+- `RouterModule.forRoot(routes)` + `<RouterOutlet/>` + `<Link/>` give you
+  nested routes whose `module` boundaries get their own child injectors.
+
+Published builds ship compiled `dist/` (`.js` + `.d.ts`).

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentChildren } from 'preact';
+import { Injector } from './injector';
+import type { Provider, Token } from './injector';
+export declare const InjectorContext: import("preact").Context<Injector>;
+export declare function useInjector(): Injector;
+export declare function useService<T>(token: Token<T>): T;
+export declare function Provide(props: {
+    providers: Provider[];
+    children?: ComponentChildren;
+}): import("preact").JSX.Element;

package/dist/context.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "preact/jsx-runtime";
+import { createContext } from 'preact';
+import { useContext, useRef } from 'preact/hooks';
+import { Injector } from './injector';
+// The current injector travels through the view tree as Preact context.
+// Module and route boundaries swap in child injectors.
+export const InjectorContext = createContext(null);
+export function useInjector() {
+    const injector = useContext(InjectorContext);
+    if (!injector) {
+        throw new Error('No injector in context — is this view mounted under bootstrap()?');
+    }
+    return injector;
+}
+// Resolve a service/store from the view's injector scope.
+export function useService(token) {
+    return useInjector().get(token);
+}
+// View-local provider scope: equivalent to a component-level providers array.
+// Providers created here live and die with this subtree.
+export function Provide(props) {
+    const parent = useInjector();
+    const ref = useRef(null);
+    if (!ref.current) {
+        ref.current = new Injector(parent, 'view providers');
+        for (const p of props.providers)
+            ref.current.provide(p);
+    }
+    return (_jsx(InjectorContext.Provider, { value: ref.current, children: props.children }));
+}

package/dist/controller.d.ts

@@ -0,0 +1,8 @@
+import type { Type } from './injector';
+export interface OnInit {
+    onInit(): void;
+}
+export interface OnDestroy {
+    onDestroy(): void;
+}
+export declare function useController<T extends object>(cls: Type<T>): T;

package/dist/controller.js

@@ -0,0 +1,21 @@
+import { useLayoutEffect, useRef } from 'preact/hooks';
+import { useInjector } from './context';
+import { Injector } from './injector';
+// Binds a controller class to a view instance. The controller is created once
+// per mounted view inside its own child injector, so `inject()` in its
+// constructor sees every provider from the enclosing module scope upward.
+// Lifecycle maps to mount/unmount: onInit on mount, onDestroy on unmount.
+export function useController(cls) {
+    const parent = useInjector();
+    const ref = useRef(null);
+    if (!ref.current) {
+        const injector = new Injector(parent, `controller ${cls.name}`);
+        ref.current = { injector, ctrl: injector.instantiate(cls) };
+    }
+    const { ctrl, injector } = ref.current;
+    useLayoutEffect(() => {
+        injector.activate();
+        return () => injector.deactivate();
+    }, []);
+    return ctrl;
+}

package/dist/decorators.d.ts

@@ -0,0 +1,22 @@
+import type { Provider, Type } from './injector';
+export interface InjectableMeta {
+    providedIn?: 'root';
+}
+export declare function Injectable(meta?: InjectableMeta): <T extends Type<any>>(target: T) => T;
+export declare function Controller(): <T extends Type<any>>(target: T) => T;
+export interface ComponentMeta {
+    providers?: Provider[];
+    controllers?: Type<any>[];
+    imports?: any[];
+}
+export declare function Component(meta?: ComponentMeta): <T>(target: T) => T;
+export interface ModuleMeta {
+    imports?: any[];
+    providers?: Provider[];
+    controllers?: Type<any>[];
+    components?: any[];
+    exports?: any[];
+    bootstrap?: any[];
+}
+export declare function ownerOf(view: any): any;
+export declare function Module(meta: ModuleMeta): <T>(target: T) => T;

package/dist/decorators.js

@@ -0,0 +1,38 @@
+export function Injectable(meta = {}) {
+    return function (target) {
+        target.__injectable = meta;
+        return target;
+    };
+}
+export function Controller() {
+    return function (target) {
+        target.__controller = true;
+        return target;
+    };
+}
+export function Component(meta = {}) {
+    return function (target) {
+        target.__component = meta;
+        return target;
+    };
+}
+// View class -> the module that declared it. Built as module classes are
+// decorated; consulted at mount time to enforce scope ownership.
+const componentOwners = new Map();
+export function ownerOf(view) {
+    return componentOwners.get(view);
+}
+export function Module(meta) {
+    return function (target) {
+        target.__module = meta;
+        for (const c of [...(meta.components ?? []), ...(meta.bootstrap ?? [])]) {
+            const prev = componentOwners.get(c);
+            if (prev && prev !== target) {
+                console.warn(`[framework] ${c.name ?? c} is declared by both ${prev.name} and ${target.name}; keeping ${prev.name}`);
+                continue;
+            }
+            componentOwners.set(c, target);
+        }
+        return target;
+    };
+}

package/{src/index.ts → dist/index.d.ts}

@@ -1,33 +1,13 @@
-// Signals — the reactivity primitive shared by models, controllers, and views.
 export { signal, computed, effect, batch, untracked } from './signals';
 export type { Signal, ReadonlySignal } from './signals';
-
-// Dependency injection
-export {
-  Injector,
-  InjectionToken,
-  inject,
-  runInInjectionContext,
-  getCurrentInjector,
-  DestroyRef,
-} from './injector';
+export { Injector, InjectionToken, inject, runInInjectionContext, getCurrentInjector, DestroyRef, } from './injector';
 export type { Provider, Token, Type } from './injector';
-
-// Metadata
 export { Injectable, Controller, Module, Component } from './decorators';
 export type { InjectableMeta, ModuleMeta, ComponentMeta } from './decorators';
-
-// Class-based views
 export { View, installViewInterop } from './view';
-
-// Modules & bootstrap
 export { bootstrap, createModuleInjector, getModuleInjector, getModuleMeta } from './module';
-
-// View integration
 export { InjectorContext, useInjector, useService, Provide } from './context';
 export { useController } from './controller';
 export type { OnInit, OnDestroy } from './controller';
-
-// Router
 export { Router, ROUTES, ROUTER_BASE, RouterModule, RouterOutlet, Link, defaultBasePath } from './router';
 export type { Route, RouteMatch, RouterOptions } from './router';

package/dist/index.js

@@ -0,0 +1,15 @@
+// Signals — the reactivity primitive shared by models, controllers, and views.
+export { signal, computed, effect, batch, untracked } from './signals';
+// Dependency injection
+export { Injector, InjectionToken, inject, runInInjectionContext, getCurrentInjector, DestroyRef, } from './injector';
+// Metadata
+export { Injectable, Controller, Module, Component } from './decorators';
+// Class-based views
+export { View, installViewInterop } from './view';
+// Modules & bootstrap
+export { bootstrap, createModuleInjector, getModuleInjector, getModuleMeta } from './module';
+// View integration
+export { InjectorContext, useInjector, useService, Provide } from './context';
+export { useController } from './controller';
+// Router
+export { Router, ROUTES, ROUTER_BASE, RouterModule, RouterOutlet, Link, defaultBasePath } from './router';

package/dist/injector.d.ts

@@ -0,0 +1,47 @@
+export type Type<T> = new (...args: any[]) => T;
+export declare class InjectionToken<T> {
+    protected readonly _desc: string;
+    constructor(_desc: string);
+    toString(): string;
+}
+export type Token<T> = Type<T> | InjectionToken<T> | (abstract new (...args: any[]) => T);
+export type Provider = Type<any> | {
+    provide: Token<any>;
+    useClass: Type<any>;
+} | {
+    provide: Token<any>;
+    useValue: any;
+} | {
+    provide: Token<any>;
+    useFactory: (...deps: any[]) => any;
+    deps?: Token<any>[];
+};
+export declare function runInInjectionContext<T>(injector: Injector, fn: () => T): T;
+export declare function inject<T>(token: Token<T>): T;
+export declare function getCurrentInjector(): Injector | null;
+export declare class DestroyRef {
+    private readonly injector;
+    constructor(injector: Injector);
+    onDestroy(fn: () => void): void;
+}
+export declare class Injector {
+    readonly parent: Injector | null;
+    readonly name: string;
+    private records;
+    readonly modules: Set<any>;
+    constructor(parent?: Injector | null, name?: string);
+    get root(): Injector;
+    provide(provider: Provider): void;
+    has(token: Token<any>): boolean;
+    get<T>(token: Token<T>): T;
+    private resolveRecord;
+    private isRootProvided;
+    instantiate<T>(cls: Type<T>, ...args: any[]): T;
+    private managed;
+    private active;
+    private trackLifecycle;
+    activate(): void;
+    deactivate(): void;
+    private cleanups;
+    registerCleanup(fn: () => void): void;
+}

package/dist/injector.js

@@ -0,0 +1,202 @@
+export class InjectionToken {
+    constructor(_desc) {
+        this._desc = _desc;
+    }
+    toString() {
+        return `InjectionToken ${this._desc}`;
+    }
+}
+// --- Injection context -----------------------------------------------------
+// While an Injector constructs a class (service, controller, factory), it
+// becomes the "current" injector so `inject()` calls inside the constructor
+// or field initializers resolve against it — the same model as Angular's
+// injection context.
+let currentInjector = null;
+export function runInInjectionContext(injector, fn) {
+    const prev = currentInjector;
+    currentInjector = injector;
+    try {
+        return fn();
+    }
+    finally {
+        currentInjector = prev;
+    }
+}
+export function inject(token) {
+    if (!currentInjector) {
+        throw new Error('inject() called outside an injection context. It can only be used in the ' +
+            'constructor/field initializers of a class instantiated by the framework.');
+    }
+    return currentInjector.get(token);
+}
+export function getCurrentInjector() {
+    return currentInjector;
+}
+// --- Injector ---------------------------------------------------------------
+function tokenName(token) {
+    return typeof token === 'function' ? token.name : token.toString();
+}
+// Injectable handle to the enclosing scope's destruction — inject(DestroyRef)
+// anywhere to register cleanup that runs when the scope is deactivated.
+export class DestroyRef {
+    constructor(injector) {
+        this.injector = injector;
+    }
+    onDestroy(fn) {
+        this.injector.registerCleanup(fn);
+    }
+}
+export class Injector {
+    constructor(parent = null, name = 'injector') {
+        this.parent = parent;
+        this.name = name;
+        this.records = new Map();
+        // Every module whose providers AND declared components are visible in this
+        // scope: the module this injector was created for plus its transitive
+        // imports. Populated by registerModule(); read by view-mount enforcement.
+        this.modules = new Set();
+        // --- Scope lifecycle -----------------------------------------------------
+        // Every class this injector constructs (view, injected controllers,
+        // view-scoped providers) is managed together: activate() fires onInit on
+        // all of them at mount, deactivate() fires onDestroy at unmount — the same
+        // way Angular ties provider lifecycles to their injector's scope.
+        this.managed = [];
+        this.active = false;
+        this.cleanups = [];
+        this.records.set(DestroyRef, {
+            factory: () => null,
+            resolving: false,
+            resolved: true,
+            value: new DestroyRef(this),
+        });
+    }
+    get root() {
+        let node = this;
+        while (node.parent)
+            node = node.parent;
+        return node;
+    }
+    provide(provider) {
+        if (typeof provider === 'function') {
+            const cls = provider;
+            this.records.set(cls, {
+                factory: () => this.instantiate(cls),
+                resolving: false,
+                resolved: false,
+                value: undefined,
+            });
+        }
+        else if ('useValue' in provider) {
+            this.records.set(provider.provide, {
+                factory: () => provider.useValue,
+                resolving: false,
+                resolved: false,
+                value: undefined,
+            });
+        }
+        else if ('useClass' in provider) {
+            const cls = provider.useClass;
+            this.records.set(provider.provide, {
+                factory: () => this.instantiate(cls),
+                resolving: false,
+                resolved: false,
+                value: undefined,
+            });
+        }
+        else {
+            const { useFactory, deps = [] } = provider;
+            this.records.set(provider.provide, {
+                factory: () => useFactory(...deps.map((d) => this.get(d))),
+                resolving: false,
+                resolved: false,
+                value: undefined,
+            });
+        }
+    }
+    has(token) {
+        if (this.records.has(token))
+            return true;
+        if (token.__controller)
+            return true;
+        if (this.parent)
+            return this.parent.has(token);
+        return this.isRootProvided(token);
+    }
+    get(token) {
+        // Nearest explicit registration wins, walking up the scope chain. This is
+        // what makes declaring a controller/provider in a scope meaningful: every
+        // descendant resolves that shared instance.
+        let node = this;
+        while (node) {
+            const rec = node.records.get(token);
+            if (rec)
+                return node.resolveRecord(token, rec);
+            node = node.parent;
+        }
+        // Controllers are transient unless explicitly provided: one instance per
+        // requesting scope, so a view always gets its own controller.
+        if (token.__controller) {
+            this.provide(token);
+            return this.resolveRecord(token, this.records.get(token));
+        }
+        // providedIn: 'root' lazily registers at the top — local providers still
+        // shadow it because the chain walk runs first.
+        const root = this.root;
+        if (root.isRootProvided(token)) {
+            root.provide({ provide: token, useClass: token });
+            return root.get(token);
+        }
+        throw new Error(`No provider for ${tokenName(token)} (looked up from "${this.name}")`);
+    }
+    resolveRecord(token, rec) {
+        if (rec.resolving) {
+            throw new Error(`Circular dependency detected while resolving ${tokenName(token)}`);
+        }
+        if (!rec.resolved) {
+            rec.resolving = true;
+            try {
+                rec.value = rec.factory();
+                rec.resolved = true;
+            }
+            finally {
+                rec.resolving = false;
+            }
+        }
+        return rec.value;
+    }
+    isRootProvided(token) {
+        const meta = token.__injectable;
+        return meta?.providedIn === 'root';
+    }
+    instantiate(cls, ...args) {
+        const inst = runInInjectionContext(this, () => new cls(...args));
+        this.trackLifecycle(inst);
+        return inst;
+    }
+    trackLifecycle(inst) {
+        if (typeof inst?.onInit !== 'function' && typeof inst?.onDestroy !== 'function')
+            return;
+        this.managed.push(inst);
+        if (this.active)
+            inst.onInit?.();
+    }
+    activate() {
+        this.active = true;
+        for (const inst of this.managed)
+            inst.onInit?.();
+    }
+    deactivate() {
+        for (const inst of this.managed)
+            inst.onDestroy?.();
+        for (const cleanup of this.cleanups)
+            cleanup();
+        this.managed.length = 0;
+        this.cleanups.length = 0;
+        this.active = false;
+    }
+    // Register teardown (effect disposers, subscriptions, timers) that runs
+    // when this scope is deactivated. Exposed to classes via DestroyRef.
+    registerCleanup(fn) {
+        this.cleanups.push(fn);
+    }
+}

package/dist/module.d.ts

@@ -0,0 +1,7 @@
+import { Injector } from './injector';
+import type { ModuleMeta } from './decorators';
+export declare function getModuleMeta(mod: any): ModuleMeta | undefined;
+export declare function registerModule(mod: any, injector: Injector, seen: Set<any>): void;
+export declare function createModuleInjector(mod: any, parent: Injector): Injector;
+export declare function getModuleInjector(mod: any, parent: Injector): Injector;
+export declare function bootstrap(RootModule: any, el: HTMLElement): void;

package/dist/module.js

@@ -0,0 +1,69 @@
+import { h, render } from 'preact';
+import { Injector } from './injector';
+import { InjectorContext } from './context';
+import { installViewInterop } from './view';
+// Modules are the unit of provider scoping. A module's providers (plus those
+// of its imports, transitively) register into a single child Injector. The
+// injector tree mirrors the view tree: root injector -> AppModule injector ->
+// feature/lazy module injectors -> per-view injectors.
+export function getModuleMeta(mod) {
+    return mod?.__module;
+}
+// Applies a module to an injector: registers all transitively imported
+// modules (and their providers/controllers) into it and marks them visible
+// on injector.modules. Used for module injectors and standalone-component
+// `imports` alike.
+export function registerModule(mod, injector, seen) {
+    if (seen.has(mod))
+        return;
+    seen.add(mod);
+    const meta = getModuleMeta(mod);
+    if (!meta) {
+        throw new Error(`${mod?.name ?? mod} is not a module — missing @Module() metadata`);
+    }
+    for (const imp of meta.imports ?? [])
+        registerModule(imp, injector, seen);
+    injector.modules.add(mod);
+    for (const provider of meta.providers ?? [])
+        injector.provide(provider);
+    // Module-declared controllers register at module scope: one shared
+    // instance for everything injected under that module.
+    for (const c of meta.controllers ?? [])
+        injector.provide(c);
+}
+export function createModuleInjector(mod, parent) {
+    const meta = getModuleMeta(mod);
+    if (!meta) {
+        throw new Error(`${mod?.name ?? mod} is not a module — missing @Module() metadata`);
+    }
+    const injector = new Injector(parent, `module ${mod.name ?? '(anonymous)'}`);
+    registerModule(mod, injector, new Set());
+    return injector;
+}
+// Lazy/feature modules get one injector per parent injector, cached so a
+// route-mounted module's providers stay alive across navigations.
+const moduleInjectorCache = new WeakMap();
+export function getModuleInjector(mod, parent) {
+    let byModule = moduleInjectorCache.get(parent);
+    if (!byModule) {
+        byModule = new Map();
+        moduleInjectorCache.set(parent, byModule);
+    }
+    let injector = byModule.get(mod);
+    if (!injector) {
+        injector = createModuleInjector(mod, parent);
+        byModule.set(mod, injector);
+    }
+    return injector;
+}
+export function bootstrap(RootModule, el) {
+    installViewInterop();
+    const root = new Injector(null, 'root');
+    const appInjector = createModuleInjector(RootModule, root);
+    const meta = getModuleMeta(RootModule);
+    const App = meta.bootstrap?.[0];
+    if (!App) {
+        throw new Error('Root module must declare a bootstrap component: @Module({ bootstrap: [AppView] })');
+    }
+    render(h(InjectorContext.Provider, { value: appInjector }, h(App, {})), el);
+}

package/dist/router/index.js

@@ -0,0 +1,4 @@
+export { Router, ROUTES, ROUTER_BASE, defaultBasePath } from './router';
+export { RouterModule, routeComponent } from './module';
+export { RouterOutlet } from './outlet';
+export { Link } from './link';

package/dist/router/link.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentChildren } from 'preact';
+import type { JSX } from 'preact';
+export declare function Link(props: {
+    to: string;
+    class?: string;
+    children?: ComponentChildren;
+}): JSX.Element;

package/dist/router/link.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "preact/jsx-runtime";
+import { useService } from '../context';
+import { Router } from './router';
+export function Link(props) {
+    const router = useService(Router);
+    const onClick = (e) => {
+        if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0)
+            return;
+        e.preventDefault();
+        // preact-router's document-level <a> interceptor routes any plain
+        // anchor click it sees — stop propagation so ours doesn't double-nav.
+        e.stopPropagation();
+        router.navigate(props.to);
+    };
+    return (_jsx("a", { href: router.href(props.to), class: props.class, onClick: onClick, children: props.children }));
+}

package/dist/router/module.d.ts

@@ -0,0 +1,35 @@
+import { Router } from './router';
+import type { Route } from './router';
+export interface RouterOptions {
+    /**
+     * Mount prefix the app is served under ('/demo/'), Angular's APP_BASE_HREF.
+     * Defaults to the document's own directory (document.baseURI), so apps
+     * hosted under a subpath need no config; '/' disables prefixing.
+     */
+    basePath?: string;
+}
+export declare class RouterModule {
+    static forRoot(routes: Route[], opts?: RouterOptions): {
+        __module: {
+            providers: ({
+                provide: import("..").InjectionToken<Route[]>;
+                useValue: Route[];
+                useFactory?: undefined;
+                deps?: undefined;
+            } | {
+                provide: import("..").InjectionToken<string>;
+                useValue: string;
+                useFactory?: undefined;
+                deps?: undefined;
+            } | {
+                provide: typeof Router;
+                useFactory: (r: Route[], base: string) => Router;
+                deps: import("..").InjectionToken<Route[]>[];
+                useValue?: undefined;
+            })[];
+        };
+    };
+}
+export declare function routeComponent(match: {
+    route: Route;
+}): any;