application.ts 1.0.0

package/src/app/AppView.ts

@@ -0,0 +1,333 @@
+import { TemplateBinder } from 'template.ts';
+import type { RouteParams } from '../navigation/types';
+import { App } from './App';
+import type { 
+    AppViewLifecycle,
+    AppViewOptions,
+    AppViewState
+} from './types';
+
+/**
+ * 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 abstract class AppView<TState extends AppViewState = AppViewState> extends HTMLElement implements AppViewLifecycle {
+    protected binder: TemplateBinder | null = null;
+    protected _state: TState | null = null;
+    protected _options: AppViewOptions;
+    protected _root: HTMLElement | ShadowRoot;
+    private _isInitialized: boolean = false;
+
+    constructor(options?: AppViewOptions) {
+        super();
+        
+        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 as HTMLElement;
+        } 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 as HTMLElement;
+        }
+
+        // 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(): void {
+        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(): string {
+        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(): void {
+        const tagName = this.getTagName();
+        if (!customElements.get(tagName)) {
+            customElements.define(tagName, this as any);
+        }
+    }
+
+    /**
+     * Define the HTML template for this view
+     * Use Template.Ts syntax for data binding
+     * @returns HTML template string
+     */
+    protected abstract template(): string;
+
+    /**
+     * Define the initial state for this view
+     * State should include data and methods
+     * @returns Initial state object
+     */
+    protected abstract state(): TState;
+
+    /**
+     * Get the current state
+     */
+    protected get viewState(): TState {
+        if (!this._state) {
+            throw new Error('State not initialized. Call render() first.');
+        }
+        return this._state;
+    }
+
+    /**
+     * Get the route parameters passed to this view
+     */
+    protected get params(): RouteParams {
+        return this.app?.router?.currentParams || {};
+    }
+
+    /**
+     * Get the App instance by traversing up the DOM tree
+     */
+    protected get app(): App | null {
+        return App.fromElement(this);
+    }
+
+    /**
+     * Navigate to a specific path using the app's router
+     * @param path - The path to navigate to
+     */
+    protected navigate(path: string): void {
+        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
+     */
+    protected setState<K extends keyof TState>(key: K, value: TState[K]): void {
+        if (!this._state) {
+            console.warn('Cannot set state before initialization');
+            return;
+        }
+
+        this._state[key] = value;
+
+        // Call lifecycle hook
+        if (this.onStateChanged) {
+            this.onStateChanged(key as string, 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
+     */
+    protected setStates(updates: Partial<TState>): void {
+        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
+     */
+    public update(withAnimation: boolean = true): void {
+        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: RouteParams = {}): Promise<void> {
+        // 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(): Promise<void> {
+        // Call before mount hook
+        if (this.onBeforeMount) {
+            await this.onBeforeMount();
+        }
+    }
+
+    /**
+     * StackView lifecycle: called when view is about to be hidden
+     */
+    async stackViewHiding(): Promise<void> {
+        if (this.onBeforeUnmount) {
+            await this.onBeforeUnmount();
+        }
+    }
+
+    /**
+     * StackView lifecycle: called after view is hidden
+     */
+    async stackViewHidden(): Promise<void> {
+        // 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(): Promise<void> {
+        // 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(): void {
+        // Cleanup is handled by stackViewHidden
+    }
+
+    /**
+     * Check if the view is initialized
+     */
+    get isInitialized(): boolean {
+        return this._isInitialized;
+    }
+
+    // Lifecycle hooks (can be overridden by subclasses)
+    onBeforeMount?(): void | Promise<void>;
+    onMounted?(): void | Promise<void>;
+    onBeforeUnmount?(): void | Promise<void>;
+    onUnmounted?(): void | Promise<void>;
+    onStateChanged?(key: string, value: any): void;
+    onParamsChanged?(newParams: RouteParams, oldParams: RouteParams): void | Promise<void>;
+}
+
+export function Register(target: any) : any {
+    target.register();
+    return target;
+}

package/src/app/types.ts

@@ -0,0 +1,78 @@
+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/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 types
+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/src/navigation/route.ts

@@ -0,0 +1,87 @@
+import type { RouteParams, RouteOptions } from './types';
+
+/**
+ * Represents a route with path pattern matching and parameter extraction
+ */
+export class Route {
+    public readonly path: string;
+    public readonly pattern: RegExp;
+    public readonly paramNames: string[];
+    public readonly options: RouteOptions;
+
+    constructor(path: string, options: RouteOptions = {}) {
+        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'
+     */
+    private pathToRegExp(path: string): RegExp {
+        // 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: string): RouteParams | null {
+        const match = this.pattern.exec(path);
+        
+        if (!match) {
+            return null;
+        }
+
+        // Extract parameters from capture groups
+        const params: RouteParams = {};
+        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: RouteParams): Promise<boolean | string> {
+        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: RouteParams = {}): string {
+        let path = this.path;
+
+        for (const [key, value] of Object.entries(params)) {
+            path = path.replace(`:${key}`, encodeURIComponent(value));
+        }
+
+        return path;
+    }
+}