application.ts 1.0.0

package/dist/app/AppView.js

@@ -0,0 +1,264 @@
+import { TemplateBinder } from 'template.ts';
+import { App } from './App';
+/**
+ * Abstract base class for creating views with Template.Ts
+ * Extends HTMLElement as a Web Component for seamless integration with StackView.Ts
+ * Custom elements are automatically registered when views are registered with App
+ *
+ * @example
+ * ```typescript
+ * const template: `
+ *  <div>
+ *      <h1>Count: {{ count }}</h1>
+ *      <button @on:click="increment">Increment</button>
+ *  </div>`;
+ *
+ * class State {
+ *     count: number = 0;
+ *     increment: () => { this.count += 1; };
+ * }
+ *
+ * @Register
+ * class HomeView extends AppView<{ count: number }> {
+ *     template(): string {
+ *         return template;
+ *     }
+ *
+ *     state() {
+ *         return new State();
+ *     }
+ * }
+ *
+ * // Register with app - automatically registers as <home-view>
+ * app.registerView('HomeView', HomeView);
+ * ```
+ */
+export class AppView extends HTMLElement {
+    constructor(options) {
+        super();
+        this.binder = null;
+        this._state = null;
+        this._isInitialized = false;
+        this._options = {
+            transitionClass: 'transition-fade',
+            autoUpdate: true,
+            useShadowDOM: false,
+            ...options
+        };
+        // Create shadow root if enabled
+        if (this._options.useShadowDOM) {
+            const shadow = this.attachShadow({ mode: 'open' });
+            shadow.innerHTML = this.template();
+            if (!shadow.firstElementChild || !(shadow.firstElementChild instanceof HTMLElement)) {
+                throw new Error('AppView template must have a single root element');
+            }
+            this._root = shadow.firstElementChild;
+        }
+        else {
+            this.innerHTML = this.template();
+            if (!this.firstElementChild || !(this.firstElementChild instanceof HTMLElement)) {
+                throw new Error('AppView template must have a single root element');
+            }
+            this._root = this.firstElementChild;
+        }
+        // Eager initialization in constructor
+        this.initialize();
+    }
+    /**
+     * Render the view with route parameters
+     * Initializes the template and binds state
+     * @param params - Route parameters from the router
+     */
+    initialize() {
+        if (this._isInitialized) {
+            return;
+        }
+        // Add app-view class
+        this.classList.add('app-view');
+        // Initialize state
+        this._state = this.state();
+        // Bind template using container
+        this.binder = new TemplateBinder(this._root, this._state, this._options.transitionClass);
+        this.binder.autoUpdate = this._options.autoUpdate ?? true;
+        this.binder.bind();
+        this._isInitialized = true;
+    }
+    /**
+     * Get the custom element tag name for this class
+     * Converts class name to kebab-case (e.g., HomeView -> home-view)
+     */
+    static getTagName() {
+        return this.name
+            .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+            .toLowerCase();
+    }
+    /**
+     * Register this class as a custom element
+     * Should be called before instantiation
+     */
+    static register() {
+        const tagName = this.getTagName();
+        if (!customElements.get(tagName)) {
+            customElements.define(tagName, this);
+        }
+    }
+    /**
+     * Get the current state
+     */
+    get viewState() {
+        if (!this._state) {
+            throw new Error('State not initialized. Call render() first.');
+        }
+        return this._state;
+    }
+    /**
+     * Get the route parameters passed to this view
+     */
+    get params() {
+        return this.app?.router?.currentParams || {};
+    }
+    /**
+     * Get the App instance by traversing up the DOM tree
+     */
+    get app() {
+        return App.fromElement(this);
+    }
+    /**
+     * Navigate to a specific path using the app's router
+     * @param path - The path to navigate to
+     */
+    navigate(path) {
+        const appInstance = this.app;
+        if (appInstance) {
+            appInstance.navigate(path);
+        }
+        else {
+            console.warn('Cannot navigate: App instance not found');
+        }
+    }
+    /**
+     * Update a single state value
+     * @param key - The state key to update
+     * @param value - The new value
+     */
+    setState(key, value) {
+        if (!this._state) {
+            console.warn('Cannot set state before initialization');
+            return;
+        }
+        this._state[key] = value;
+        // Call lifecycle hook
+        if (this.onStateChanged) {
+            this.onStateChanged(key, value);
+        }
+        // Auto-update if enabled
+        if (this._options.autoUpdate && this.binder) {
+            this.update();
+        }
+    }
+    /**
+     * Update multiple state values at once
+     * @param updates - Object with state updates
+     */
+    setStates(updates) {
+        if (!this._state) {
+            console.warn('Cannot set state before initialization');
+            return;
+        }
+        Object.assign(this._state, updates);
+        // Call lifecycle hooks for each update
+        if (this.onStateChanged) {
+            for (const [key, value] of Object.entries(updates)) {
+                this.onStateChanged(key, value);
+            }
+        }
+        // Auto-update if enabled
+        if (this._options.autoUpdate && this.binder) {
+            this.update();
+        }
+    }
+    /**
+     * Manually trigger a view update
+     * @param withAnimation - Whether to apply transition animation
+     */
+    update(withAnimation = true) {
+        if (this.binder) {
+            this.binder.update(withAnimation);
+        }
+    }
+    /**
+     * Update route parameters and re-trigger initialization logic
+     * Used when navigating to the same view with different parameters
+     * @param params - New route parameters
+     */
+    async updateParams(params = {}) {
+        // Call the parameter changed hook with old and new params
+        if (this.onParamsChanged) {
+            await this.onParamsChanged(params, this.params);
+        }
+        // Update the view if needed
+        if (this.binder && this._options.autoUpdate) {
+            this.update();
+        }
+    }
+    /**
+     * StackView lifecycle: called when view is about to be shown
+     */
+    async stackViewShowing() {
+        // Call before mount hook
+        if (this.onBeforeMount) {
+            await this.onBeforeMount();
+        }
+    }
+    /**
+     * StackView lifecycle: called when view is about to be hidden
+     */
+    async stackViewHiding() {
+        if (this.onBeforeUnmount) {
+            await this.onBeforeUnmount();
+        }
+    }
+    /**
+     * StackView lifecycle: called after view is hidden
+     */
+    async stackViewHidden() {
+        // Destroy binder
+        if (this.binder) {
+            this.binder.destroy();
+            this.binder = null;
+        }
+        this._isInitialized = false;
+        if (this.onUnmounted) {
+            await this.onUnmounted();
+        }
+    }
+    /**
+     * Web Component lifecycle: called when connected to DOM
+     */
+    async connectedCallback() {
+        // Initialize if not already done
+        if (!this._isInitialized) {
+            await this.initialize();
+        }
+        if (this.onMounted) {
+            await this.onMounted();
+        }
+    }
+    /**
+     * Web Component lifecycle: called when disconnected from DOM
+     */
+    disconnectedCallback() {
+        // Cleanup is handled by stackViewHidden
+    }
+    /**
+     * Check if the view is initialized
+     */
+    get isInitialized() {
+        return this._isInitialized;
+    }
+}
+export function Register(target) {
+    target.register();
+    return target;
+}
+//# sourceMappingURL=AppView.js.map

package/dist/app/AppView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppView.js","sourceRoot":"","sources":["../../src/app/AppView.ts"],"names":[],"mappings":"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"}

package/dist/app/types.d.ts

@@ -0,0 +1,67 @@
+import type { RouteParams } from '../navigation/types';
+/**
+ * AppView lifecycle hooks
+ */
+export interface AppViewLifecycle {
+    /**
+     * Called before the view is shown
+     * Use this to initialize data, fetch from APIs, etc.
+     */
+    onBeforeMount?(): void | Promise<void>;
+    /**
+     * Called after the view is mounted to the DOM
+     * Use this to set up event listeners, third-party libraries, etc.
+     */
+    onMounted?(): void | Promise<void>;
+    /**
+     * Called before the view is unmounted
+     * Use this to clean up resources, save state, etc.
+     */
+    onBeforeUnmount?(): void | Promise<void>;
+    /**
+     * Called after the view is unmounted from the DOM
+     * Final cleanup
+     */
+    onUnmounted?(): void | Promise<void>;
+    /**
+     * Called when the state is updated
+     * Use this to react to state changes
+     */
+    onStateChanged?(key: string, value: any): void;
+    /**
+     * Called when route parameters change while staying on the same view
+     * Use this to reload data based on new parameters (e.g., /user/1 -> /user/2)
+     * @param newParams - The new route parameters
+     * @param oldParams - The previous route parameters
+     */
+    onParamsChanged?(newParams: RouteParams, oldParams: RouteParams): void | Promise<void>;
+}
+/**
+ * AppView configuration options
+ */
+export interface AppViewOptions {
+    /**
+     * Custom transition class for Template.Ts animations
+     * Default: 'transition-fade'
+     */
+    transitionClass?: string;
+    /**
+     * Whether to automatically update the view on state changes
+     * Default: true
+     */
+    autoUpdate?: boolean;
+    /**
+     * Whether to use Shadow DOM for the template
+     * When true, template is rendered in shadow root (enables <slot> to work properly)
+     * Default: false
+     */
+    useShadowDOM?: boolean;
+}
+/**
+ * AppView state object - can be any shape defined by the developer
+ */
+export type AppViewState = Record<string, any>;
+/**
+ * Template function that returns HTML string
+ */
+export type TemplateFunction<T extends AppViewState = AppViewState> = (this: T) => string;

package/dist/app/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/app/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/app/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Main entry point for the application
+ * Export all public APIs
+ */
+export { App } from './app/App';
+export { AppView, Register } from './app/AppView';
+export { Router } from './navigation/router';
+export { Route } from './navigation/route';
+export type { AppViewLifecycle, AppViewOptions, AppViewState, TemplateFunction } from './app/types';
+export type { RouteParams, RouteGuard, RouteOptions, RouteHandler, RouteDefinition, NavigationEventDetail } from './navigation/types';
+export { NavigationEvents } from './navigation/types';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Main entry point for the application
+ * Export all public APIs
+ */
+export { App } from './app/App';
+export { AppView, Register } from './app/AppView';
+export { Router } from './navigation/router';
+export { Route } from './navigation/route';
+export { NavigationEvents } from './navigation/types';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAmB3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/navigation/route.d.ts

@@ -0,0 +1,34 @@
+import type { RouteParams, RouteOptions } from './types';
+/**
+ * Represents a route with path pattern matching and parameter extraction
+ */
+export declare class Route {
+    readonly path: string;
+    readonly pattern: RegExp;
+    readonly paramNames: string[];
+    readonly options: RouteOptions;
+    constructor(path: string, options?: RouteOptions);
+    /**
+     * Convert a path pattern like '/user/:id' to a RegExp
+     * Extracts parameter names like 'id'
+     */
+    private pathToRegExp;
+    /**
+     * Check if the given path matches this route
+     * @param path - The path to test
+     * @returns The extracted parameters if match, null otherwise
+     */
+    match(path: string): RouteParams | null;
+    /**
+     * Check if navigation is allowed via the route guard
+     * @param params - Route parameters
+     * @returns true if allowed, false if denied, or redirect path
+     */
+    canEnter(params: RouteParams): Promise<boolean | string>;
+    /**
+     * Generate a path from this route pattern with given parameters
+     * @param params - Parameters to inject into the path
+     * @returns The generated path
+     */
+    generate(params?: RouteParams): string;
+}

package/dist/navigation/route.js

@@ -0,0 +1,68 @@
+/**
+ * Represents a route with path pattern matching and parameter extraction
+ */
+export class Route {
+    constructor(path, options = {}) {
+        this.path = path;
+        this.options = options;
+        this.paramNames = [];
+        // Convert path pattern to RegExp and extract parameter names
+        this.pattern = this.pathToRegExp(path);
+    }
+    /**
+     * Convert a path pattern like '/user/:id' to a RegExp
+     * Extracts parameter names like 'id'
+     */
+    pathToRegExp(path) {
+        // Escape special characters except for :param patterns
+        const escapedPath = path.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        // Replace :param with capture groups and extract param names
+        const pattern = escapedPath.replace(/:([^/]+)/g, (match, paramName) => {
+            this.paramNames.push(paramName);
+            return '([^/]+)';
+        });
+        // Match exact path or with trailing slash
+        return new RegExp(`^${pattern}/?$`);
+    }
+    /**
+     * Check if the given path matches this route
+     * @param path - The path to test
+     * @returns The extracted parameters if match, null otherwise
+     */
+    match(path) {
+        const match = this.pattern.exec(path);
+        if (!match) {
+            return null;
+        }
+        // Extract parameters from capture groups
+        const params = {};
+        this.paramNames.forEach((name, index) => {
+            params[name] = decodeURIComponent(match[index + 1]);
+        });
+        return params;
+    }
+    /**
+     * Check if navigation is allowed via the route guard
+     * @param params - Route parameters
+     * @returns true if allowed, false if denied, or redirect path
+     */
+    async canEnter(params) {
+        if (!this.options.canEnter) {
+            return true;
+        }
+        return await this.options.canEnter(params);
+    }
+    /**
+     * Generate a path from this route pattern with given parameters
+     * @param params - Parameters to inject into the path
+     * @returns The generated path
+     */
+    generate(params = {}) {
+        let path = this.path;
+        for (const [key, value] of Object.entries(params)) {
+            path = path.replace(`:${key}`, encodeURIComponent(value));
+        }
+        return path;
+    }
+}
+//# sourceMappingURL=route.js.map

package/dist/navigation/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/navigation/route.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,KAAK;IAMd,YAAY,IAAY,EAAE,UAAwB,EAAE;QAChD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QAErB,6DAA6D;QAC7D,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACK,YAAY,CAAC,IAAY;QAC7B,uDAAuD;QACvD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;QAE/D,6DAA6D;QAC7D,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;YAClE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAChC,OAAO,SAAS,CAAC;QACrB,CAAC,CAAC,CAAC;QAEH,0CAA0C;QAC1C,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAY;QACd,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,yCAAyC;QACzC,MAAM,MAAM,GAAgB,EAAE,CAAC;QAC/B,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YACpC,MAAM,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,MAAmB;QAC9B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,SAAsB,EAAE;QAC7B,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAErB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAChD,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,EAAE,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9D,CAAC;QAED,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ"}

package/dist/navigation/router.d.ts

@@ -0,0 +1,92 @@
+import type { RouteParams, RouteOptions, RouteHandler } from './types';
+/**
+ * Router class for managing navigation and route mapping
+ * Emits events for Application.ts to handle view rendering via StackView
+ */
+export declare class Router extends EventTarget {
+    private routes;
+    private notFoundHandler?;
+    private isInitialized;
+    private basePath;
+    private _currentPath;
+    private _currentParams;
+    private _currentMeta?;
+    constructor();
+    /**
+     * Map a route path to a handler (view identifier)
+     * @param path - The route path (e.g., '/', '/user/:id')
+     * @param handler - The view identifier/handler
+     * @param options - Optional route configuration
+     * @returns The router instance for chaining
+     */
+    map(path: string, handler: RouteHandler, options?: RouteOptions): this;
+    /**
+     * Set the 404 not found handler
+     * @param handler - The view identifier to use for 404
+     * @returns The router instance for chaining
+     */
+    notFound(handler: RouteHandler): this;
+    /**
+     * Set the base path for all routes
+     * @param base - Base path (e.g., '/basic', '/app')
+     * @returns The router instance for chaining
+     */
+    setBasePath(base: string): this;
+    /**
+     * Get the current base path
+     */
+    getBasePath(): string;
+    /**
+     * Initialize the router and handle the current path
+     */
+    start(): void;
+    /**
+     * Navigate to a specific path
+     * @param path - The path to navigate to (relative to basePath)
+     * @param replaceState - If true, replaces current history entry instead of pushing
+     */
+    navigate(path: string, replaceState?: boolean): Promise<void>;
+    /**
+     * Get the current path (route pattern)
+     */
+    get currentPath(): string;
+    /**
+     * Get the current route parameters
+     */
+    get currentParams(): RouteParams;
+    /**
+     * Get the current route metadata
+     */
+    get currentMeta(): Record<string, any> | undefined;
+    /**
+     * Find a route that matches the given path
+     */
+    private findRoute;
+    /**
+     * Handle route change (from popstate or initial load)
+     */
+    private handleRouteChange;
+    /**
+     * Strip base path from a full path
+     */
+    private stripBasePath;
+    /**
+     * Add base path to a route path
+     */
+    private addBasePath;
+    /**
+     * Emit navigation event
+     */
+    private emitNavigation;
+    /**
+     * Emit not found event
+     */
+    private emitNotFound;
+    /**
+     * Generate a URL for a route with parameters
+     * @param path - The route path pattern
+     * @param params - Parameters to inject
+     * @returns The generated URL (with basePath) or null if route not found
+     */
+    generateUrl(path: string, params?: RouteParams): string | null;
+}