rasti 4.0.0 → 4.1.0-alpha.0

package/types/Component.d.ts

@@ -0,0 +1,238 @@
+import View, { ViewOptions } from './View.js';
+import Model from './Model.js';
+
+export interface ComponentReservedOptions<S = any, M = any> extends ViewOptions<M> {
+    /**
+     * A unique key to identify the component.
+     * Components with keys are recycled when the same key is found in the previous render.
+     * Unkeyed components are recycled based on type and position.
+     */
+    key?: string;
+    /**
+     * A `Model` or any emitter object containing data and business logic, to be used as internal
+     * state. The component will listen to `change` events and call `onChange` lifecycle method.
+     */
+    state?: S;
+    /** Lifecycle hook called at the end of the constructor. */
+    onCreate?: (...args: any[]) => void;
+    /** Lifecycle hook called when `model`, `state` or `props` emits `change`. */
+    onChange?: (...args: any[]) => void;
+    /** Lifecycle hook called after the first render (client only). */
+    onHydrate?: () => void;
+    /** Lifecycle hook called at the start of `recycle`, before any recycling happens. */
+    onBeforeRecycle?: () => void;
+    /** Lifecycle hook called after the component is recycled and props are updated. */
+    onRecycle?: () => void;
+    /** Lifecycle hook called at the start of `render` on update. */
+    onBeforeUpdate?: () => void;
+    /** Lifecycle hook called at the end of `render` on update. */
+    onUpdate?: () => void;
+}
+
+export type ComponentOptions<P = {}, S = any, M = any> = P & ComponentReservedOptions<S, M>;
+
+/** Marker type for strings that are safe to inject as HTML without sanitization. */
+export interface SafeHTML {
+    readonly __rastiSafeHTML: true;
+    toString(): string;
+}
+
+/** A partial template produced by `this.partial` — preserves structure for position-based recycling. */
+export interface Partial {
+    strings: TemplateStringsArray;
+    expressions: any[];
+}
+
+/**
+ * Helper type for typing event handlers passed to component templates.
+ * `this` is bound to the component, and the handler also receives `(event, component, matched)`.
+ *
+ * @example
+ * const onClick: EventHandler<Todo, MouseEvent> = function(ev) {
+ *     this.model.toggle();
+ * };
+ */
+export type EventHandler<C, E extends Event = Event> = (
+    this: C,
+    event: E,
+    component: C,
+    matched: Element,
+) => void;
+
+/**
+ * Helper type for typing render expressions inside component templates.
+ * Rasti calls the expression with the component as argument **and** binds `this` to it,
+ * so both arrow and `function` forms are covered.
+ *
+ * @example
+ * const renderTitle: RenderExpression<Todo> = ({ model }) => model.title;
+ * const renderTotal: RenderExpression<Todo> = function() { return this.props.total; };
+ */
+export type RenderExpression<C> = (this: C, component: C) => any;
+
+/** Extracts the props type `P` from a Component subclass. */
+export type Props<C> = C extends Component<infer P, any, any> ? P : never;
+/** Extracts the state type `S` from a Component subclass. */
+export type State<C> = C extends Component<any, infer S, any> ? S : never;
+/** Extracts the model type `M` from a Component / View subclass. */
+export type ComponentModel<C> = C extends Component<any, any, infer M> ? M : never;
+
+/**
+ * Components are a special kind of `View` designed to be easily composable. Unlike views,
+ * which are render-agnostic, components have a specific set of rendering guidelines that
+ * allow for a more declarative development style.
+ *
+ * Components are defined with the {@link Component.create} static method, which takes a
+ * tagged template string or a function that returns another component.
+ *
+ * @example
+ * import { Component, Model } from 'rasti';
+ * const Timer = Component.create`
+ *     <div>Seconds: <span>${({ model }) => model.seconds}</span></div>
+ * `;
+ * const model = new Model({ seconds: 0 });
+ * Timer.mount({ model }, document.body);
+ * setInterval(() => model.seconds++, 1000);
+ */
+declare class Component<P = {}, S = any, M = any> extends View<M> {
+    /**
+     * Mark a string as safe HTML to be rendered.
+     * Rasti marks string literals as safe automatically when a component is created or when
+     * using `this.partial`. Only use this manually when you're sure the string is safe.
+     */
+    static markAsSafeHTML(value: string): SafeHTML;
+
+    /**
+     * Helper method used to extend a `Component`, creating a subclass.
+     * @param object Object with methods to add to the subclass, or a function that receives
+     * the parent prototype and returns such an object.
+     * @return The newly created Component subclass.
+     */
+    static extend<T extends new (...args: any[]) => Component<any, any, any>>(
+        this: T,
+        object: object | ((proto: InstanceType<T>) => object),
+    ): T;
+
+    /**
+     * Mount the component into the DOM.
+     *
+     * - **Normal mount** (default): renders as HTML and appends it to `el`.
+     * - **Hydration mode**: assumes the DOM already contains the component's HTML (SSR).
+     *
+     * If `el` is omitted, the component is instantiated but not mounted.
+     *
+     * @param options Passed to the constructor.
+     * @param el Target DOM element.
+     * @param hydrate If `true`, hydrate an existing SSR tree instead of rendering from scratch.
+     * @return The component instance.
+     */
+    static mount<T extends new (...args: any[]) => Component<any, any, any>>(
+        this: T,
+        options?: ConstructorParameters<T>[0],
+        el?: Element,
+        hydrate?: boolean,
+    ): InstanceType<T>;
+
+    /**
+     * Takes a tagged template string (or a function returning another component) and returns
+     * a new `Component` class.
+     *
+     * - The template outer tag and attributes define the view's root element.
+     * - Inner HTML becomes the view's template.
+     * - Function interpolations are evaluated on render, bound to the component instance.
+     * - DOM event handlers via camelCased attributes (`onClick=${handler}`), delegated to the root.
+     * - Returning a component instance (or array of them) adds it as a child.
+     * - Use `<${Sub}>…</${Sub}>` syntax for child component tags.
+     *
+     * @example
+     * const Button = Component.create`
+     *     <button class="${({ props }) => props.className}"
+     *             onClick=${function(event, self) { self.emit('click'); }}>
+     *         ${({ props }) => props.label}
+     *     </button>
+     * `;
+     */
+    static create<P = Record<string, any>, S = any, M = any>(
+        strings: string | TemplateStringsArray | ((...args: any[]) => any),
+        ...expressions: any[]
+    ): typeof Component<P, S, M>;
+
+    /**
+     * Props passed from the parent component, stored as a `Model` for reactive updates.
+     * Accessible directly (`this.props.foo`) or via `Model` API (`this.props.get('foo')`).
+     */
+    props: Model<P> & P;
+
+    /**
+     * A `Model` or any emitter object containing data and business logic, to be used as internal
+     * state. The component will listen to `change` events and call `onChange` lifecycle method.
+     */
+    state?: S;
+
+    /** The original options object passed to the constructor. */
+    options: ComponentOptions<P, S, M>;
+
+    /** Template function returning the view's inner HTML. */
+    template: (...args: any[]) => string;
+
+    /**
+     * @param options Component options. Keys `model`, `state`, `key`, `onCreate`, `onChange`,
+     * `onHydrate`, `onBeforeRecycle`, `onRecycle`, `onBeforeUpdate`, `onUpdate`, `onDestroy`
+     * are merged into `this`. Any remaining options become `this.props`.
+     */
+    constructor(options?: ComponentOptions<P, S, M>, ...args: any[]);
+
+    /**
+     * Tagged template helper bound to the component instance.
+     * Returns a `Partial` that preserves structure for position-based recycling.
+     * String literals are marked as safe HTML automatically.
+     *
+     * @example
+     * renderHeader() {
+     *     return this.partial`<header><${Title}>${this.model.title}</${Title}></header>`;
+     * }
+     */
+    partial(strings: TemplateStringsArray, ...expressions: any[]): Partial;
+
+    /**
+     * Subscribes to a `change` event on a model or emitter and invokes `onChange`.
+     * Cleaned up automatically on destroy. By default the component subscribes to
+     * `this.model`, `this.state` and `this.props`.
+     */
+    subscribe(model: object, type?: string, listener?: (...args: any[]) => void): this;
+
+    /**
+     * Render the component.
+     *
+     * - **First render** (`this.el` absent): renders as a string inside a `DocumentFragment`
+     *   and hydrates it. `onHydrate` is called.
+     * - **Update render** (`this.el` present): updates root attributes and interpolation content.
+     *   `onBeforeUpdate` and `onUpdate` are called.
+     */
+    render(): this;
+
+    /** Lifecycle. Called at the end of the constructor. Runs on both client and server. */
+    onCreate(...args: any[]): void;
+
+    /** Lifecycle. Called when model/state/props emit `change`. Default: triggers `render`. */
+    onChange(model: object, changed: object, ...args: any[]): void;
+
+    /** Lifecycle. Called after the first render hydrates the DOM. Client only. */
+    onHydrate(): void;
+
+    /** Lifecycle. Called at the start of `recycle`, before any recycling happens. */
+    onBeforeRecycle(): void;
+
+    /** Lifecycle. Called when the component is recycled and its props are updated. */
+    onRecycle(): void;
+
+    /** Lifecycle. Called at the start of `render` on update. */
+    onBeforeUpdate(): void;
+
+    /** Lifecycle. Called at the end of `render` on update. */
+    onUpdate(): void;
+}
+
+declare const _default: typeof Component;
+export default _default;
+export { Component };

package/types/Emitter.d.ts

@@ -0,0 +1,111 @@
+export type EventMap = Record<string, (...args: any[]) => void>;
+
+/**
+ * `Emitter` is a class that provides an easy way to implement the observer pattern
+ * in your applications.
+ *
+ * It can be extended to create new classes that have the ability to emit and bind custom named events.
+ * Emitter is used by `Model` and `View` classes, which inherit from it to implement
+ * event-driven functionality.
+ *
+ * ## Inverse of Control Pattern
+ *
+ * The Emitter class includes "inverse of control" methods (`listenTo`, `listenToOnce`, `stopListening`)
+ * that allow an object to manage its own listening relationships, making cleanup easier and
+ * preventing memory leaks.
+ *
+ * @example
+ * import { Emitter } from 'rasti';
+ * class ShoppingCart extends Emitter {
+ *     constructor() {
+ *         super();
+ *         this.items = [];
+ *     }
+ *     addItem(item) {
+ *         this.items.push(item);
+ *         this.emit('itemAdded', item);
+ *     }
+ * }
+ */
+export default class Emitter<E extends EventMap = EventMap> {
+    /** Registered event listeners, keyed by event type. */
+    listeners?: { [K in keyof E]?: Array<E[K]> };
+    /** Active `listenTo` subscriptions, tracked so `stopListening` can clean them up. */
+    listeningTo?: Array<{
+        emitter: Emitter<any>;
+        type: string;
+        listener: (...args: any[]) => void;
+    }>;
+
+    /**
+     * Adds event listener.
+     * @param type Type of the event (e.g. `change`).
+     * @param listener Callback function to be called when the event is emitted.
+     * @return A function to remove the listener.
+     * @example
+     * this.model.on('change', this.render.bind(this));
+     */
+    on<K extends keyof E>(type: K, listener: E[K]): () => void;
+
+    /**
+     * Adds event listener that executes once.
+     * @param type Type of the event (e.g. `change`).
+     * @param listener Callback function to be called when the event is emitted.
+     * @return A function to remove the listener.
+     * @example
+     * this.model.once('change', () => console.log('This will happen once'));
+     */
+    once<K extends keyof E>(type: K, listener: E[K]): () => void;
+
+    /**
+     * Removes event listeners with flexible parameter combinations.
+     *
+     * - `off()` - Removes ALL listeners from this emitter
+     * - `off(type)` - Removes all listeners for the specified event type
+     * - `off(type, listener)` - Removes the specific listener for the specified event type
+     */
+    off(): void;
+    off<K extends keyof E>(type: K, listener?: E[K]): void;
+
+    /**
+     * Emits event of specified type. Listeners will receive specified arguments.
+     * @param type Type of the event (e.g. `change`).
+     * @param args Optional arguments to be passed to listeners.
+     * @example
+     * this.emit('change', { field: 'name', value: 'John' });
+     */
+    emit<K extends keyof E>(type: K, ...args: Parameters<E[K]>): void;
+
+    /**
+     * Listen to an event of another emitter (Inverse of Control pattern).
+     *
+     * Allows this object to track and clean up all its listeners at once via `stopListening()`.
+     * @param emitter The emitter to listen to.
+     * @param type The type of the event to listen to.
+     * @param listener The listener to call when the event is emitted.
+     * @return A function to stop listening to the event.
+     * @example
+     * this.listenTo(otherModel, 'change', this.render.bind(this));
+     */
+    listenTo(emitter: Emitter<any>, type: string, listener: (...args: any[]) => void): () => void;
+
+    /**
+     * Listen to an event of another emitter and remove the listener after it is called.
+     * Similar to `listenTo()` but the listener runs only once.
+     * @param emitter The emitter to listen to.
+     * @param type The type of the event to listen to.
+     * @param listener The listener to call when the event is emitted.
+     * @return A function to stop listening to the event.
+     */
+    listenToOnce(emitter: Emitter<any>, type: string, listener: (...args: any[]) => void): () => void;
+
+    /**
+     * Stop listening to events from other emitters.
+     *
+     * - `stopListening()` - Stops listening to ALL events from ALL emitters
+     * - `stopListening(emitter)` - Stops listening to all events from the specified emitter
+     * - `stopListening(emitter, type)` - Stops listening to the specified event type from the specified emitter
+     * - `stopListening(emitter, type, listener)` - Stops the specific listener for the specific event
+     */
+    stopListening(emitter?: Emitter<any>, type?: string, listener?: (...args: any[]) => void): void;
+}

package/types/Model.d.ts

@@ -0,0 +1,123 @@
+import Emitter from './Emitter.js';
+
+/** Extracts the attribute type `A` from a Model subclass. */
+export type Attrs<M> = M extends Model<infer A> ? A : never;
+
+export type ModelEvents<A> =
+    & {
+        change: (model: Model<A>, changed: Partial<A>, ...args: any[]) => void;
+        [event: string]: (...args: any[]) => void;
+    }
+    & {
+        [K in keyof A & string as `change:${K}`]: (model: Model<A>, value: A[K], ...args: any[]) => void;
+    };
+
+/**
+ * - Orchestrates data and business logic.
+ * - Emits events when data changes.
+ *
+ * A `Model` manages an internal table of data attributes and triggers change events when
+ * any of its data is modified. Models may handle syncing data with a persistence layer.
+ *
+ * ## Construction Flow
+ * 1. `preinitialize()` is called with all constructor arguments
+ * 2. `this.defaults` are resolved (if function, it's called and bound to the model)
+ * 3. `parse()` is called with all constructor arguments to process the data
+ * 4. `this.attributes` is built by merging defaults and parsed data
+ * 5. Getters/setters are generated for each attribute to emit change events
+ *
+ * @example
+ * import { Model } from 'rasti';
+ * class User extends Model {
+ *     preinitialize() {
+ *         this.defaults = { name: '', email: '', role: 'user' };
+ *     }
+ * }
+ */
+export default class Model<A = any> extends Emitter<ModelEvents<A>> {
+    /**
+     * Static property that defines a prefix for generated getters/setters.
+     * When set, all attribute properties will be prefixed (e.g., 'attr_name' instead of 'name').
+     * @default ''
+     */
+    static attributePrefix: string;
+
+    /**
+     * Default attributes for the model, merged into `this.attributes` during construction.
+     * Can be a plain object, or a function (called bound to the instance) that returns the
+     * defaults. Assign it on the prototype, or via `this.defaults` inside
+     * `preinitialize`.
+     */
+    defaults?: Partial<A> | (() => Partial<A>);
+
+    /** Primary data object holding the model attributes. */
+    attributes: A;
+
+    /** Object containing previous attributes when a change occurs. */
+    previous: Partial<A>;
+
+    /**
+     * @param attributes Primary data object containing model attributes.
+     * @param args Additional arguments passed to `preinitialize` and `parse`.
+     */
+    constructor(attributes?: Partial<A>, ...args: any[]);
+
+    /**
+     * Called before any instantiation logic runs for the Model.
+     * Receives all constructor arguments, allowing for flexible initialization patterns.
+     * Use this to set up `defaults`, configure the model, or handle custom constructor arguments.
+     * @example
+     * class User extends Model {
+     *     preinitialize(attributes, options = {}) {
+     *         this.defaults = { name: '', role: options.defaultRole || 'user' };
+     *         this.apiEndpoint = options.apiEndpoint || '/users';
+     *     }
+     * }
+     */
+    preinitialize(attributes?: Partial<A>, ...args: any[]): void;
+
+    /**
+     * Generate getter/setter for the given attribute key to emit `change` events.
+     * Called internally by the constructor for each key in `this.attributes`.
+     * Override with an empty method if you don't want automatic getters/setters.
+     */
+    defineAttribute(key: keyof A & string): void;
+
+    /**
+     * Get an attribute from `this.attributes`.
+     * @param key Attribute key.
+     * @return The attribute value.
+     */
+    get<K extends keyof A>(key: K): A[K];
+    get(key: string): any;
+
+    /**
+     * Set one or more attributes into `this.attributes` and emit change events.
+     * Supports two call signatures: `set(key, value, ...args)` or `set(object, ...args)`.
+     * Additional arguments are passed to change event listeners.
+     *
+     * Emits `change` (listeners receive `(model, changedAttributes, ...args)`) and
+     * `change:<attribute>` (listeners receive `(model, newValue, ...args)`).
+     *
+     * @return This model instance for chaining.
+     * @example
+     * model.set('name', 'Alice');
+     * model.set({ name: 'Alice', age: 30 });
+     * model.set('name', 'Bob', { silent: false });
+     */
+    set<K extends keyof A>(key: K, value: A[K], ...args: any[]): this;
+    set(attrs: Partial<A>, ...args: any[]): this;
+
+    /**
+     * Transforms and validates data before it becomes model attributes.
+     * Called during construction with all constructor arguments.
+     * Override this method to transform incoming data, create nested models, or handle different data formats.
+     */
+    parse(data?: Partial<A>, ...args: any[]): Partial<A>;
+
+    /**
+     * Return object representation of the model to be used for JSON serialization.
+     * By default returns a copy of `this.attributes`.
+     */
+    toJSON(): A;
+}

package/types/View.d.ts

@@ -0,0 +1,173 @@
+import Emitter from './Emitter.js';
+
+export interface ViewOptions<M = any> {
+    el?: HTMLElement | (() => HTMLElement);
+    tag?: string | (() => string);
+    attributes?: Record<string, any> | (() => Record<string, any>);
+    events?: Record<string, string | Function> | (() => Record<string, string | Function>);
+    model?: M;
+    template?: (...args: any[]) => string;
+    onDestroy?: (...args: any[]) => void;
+}
+
+/**
+ * - Listens for changes and renders the UI.
+ * - Handles user input and interactivity.
+ * - Sends captured input to the model.
+ *
+ * A `View` is an atomic unit of the user interface that can render data from a specific model or multiple models.
+ * Each `View` has a root element, `this.el`, used for event delegation. All element lookups are scoped to it.
+ * If `this.el` is not present, an element will be created using `this.tag` (defaulting to `div`) and `this.attributes`.
+ *
+ * @example
+ * import { View, Model } from 'rasti';
+ * class Timer extends View {
+ *     constructor(options) {
+ *         super(options);
+ *         this.model = new Model({ seconds: 0 });
+ *         this.model.on('change:seconds', this.render.bind(this));
+ *     }
+ *     template(model) {
+ *         return `Seconds: <span>${View.sanitize(model.seconds)}</span>`;
+ *     }
+ *     render() {
+ *         if (this.template) this.el.innerHTML = this.template(this.model);
+ *         return this;
+ *     }
+ * }
+ */
+export default class View<M = any> extends Emitter {
+    /**
+     * Escape HTML entities in a string.
+     * Use this method to sanitize user-generated content before inserting it into the DOM.
+     */
+    static sanitize(value: string): string;
+
+    /**
+     * Reset the unique ID counter to 0.
+     * Useful for server-side rendering scenarios to ensure generated unique IDs match the client,
+     * enabling seamless hydration of components.
+     */
+    static resetUid(): void;
+
+    /** Root DOM element of the view. */
+    el: HTMLElement;
+
+    /** A model or any object containing data and business logic. */
+    model?: M;
+
+    /** Tag used to create the root element when `el` is not provided (default `div`). */
+    tag?: string | (() => string);
+
+    /** Attributes used to create the root element when `el` is not provided. */
+    attributes?: Record<string, any> | (() => Record<string, any>);
+
+    /** Declarative DOM event listeners in the form `{'event selector': listener}`. */
+    events?: Record<string, string | Function> | (() => Record<string, string | Function>);
+
+    /** Function returning the view's inner HTML, used by `render`. */
+    template?: (...args: any[]) => string;
+
+    /** Unique identifier for the view instance. */
+    uid: string;
+
+    /** Child views. Destroyed automatically when the parent is destroyed. */
+    children: View[];
+
+    /** Whether `destroy()` has been called on this view. */
+    destroyed: boolean;
+
+    /**
+     * Functions run on `destroy()`. Push cleanup callbacks here for external subscriptions
+     * Rasti doesn't manage (DOM events, timers, third-party libraries).
+     */
+    destroyQueue: Array<() => void>;
+
+    /**
+     * @param options View options. The following keys are merged into the view instance:
+     * `el`, `tag`, `attributes`, `events`, `model`, `template`, `onDestroy`.
+     */
+    constructor(options?: ViewOptions<M>, ...args: any[]);
+
+    /**
+     * If you define a preinitialize method, it will be invoked when the view is first created,
+     * before any instantiation logic is run. Receives all constructor arguments.
+     */
+    preinitialize(options?: ViewOptions<M>, ...args: any[]): void;
+
+    /**
+     * Returns the first element that matches the selector, scoped to the view's root element
+     * (`this.el`), or `null` if none matches. Defaults to `HTMLElement`; pass a type argument
+     * to narrow (e.g. `this.$<HTMLInputElement>('input.edit')`).
+     */
+    $<E extends Element = HTMLElement>(selector: string): E | null;
+
+    /**
+     * Returns a list of elements matching the selector, scoped to the view's root element
+     * (`this.el`). Defaults to `HTMLElement`; pass a type argument to narrow.
+     */
+    $$<E extends Element = HTMLElement>(selector: string): NodeListOf<E>;
+
+    /**
+     * Destroy the view.
+     * Destroys children views, undelegates events, stops listening to events, calls `onDestroy`.
+     * @return This view for chaining.
+     */
+    destroy(...args: any[]): this;
+
+    /**
+     * Lifecycle method called after the view is destroyed. Override with your cleanup code.
+     */
+    onDestroy(...args: any[]): void;
+
+    /**
+     * Add a view as a child. Children are stored in `this.children` and destroyed when the parent is destroyed.
+     * @return The child view for chaining.
+     */
+    addChild(child: View): View;
+
+    /** Call `destroy()` on children views. */
+    destroyChildren(): void;
+
+    /** Ensure the view has a unique id at `this.uid`. */
+    ensureUid(): void;
+
+    /**
+     * Ensure the view has a root element at `this.el`.
+     * Called from the constructor. Override for custom element-creation logic.
+     */
+    ensureElement(): void;
+
+    /**
+     * Create a DOM element. Called from the constructor if `this.el` is undefined.
+     * @param tag Tag for the element (default `div`).
+     * @param attributes Attributes for the element.
+     */
+    createElement(tag?: string, attributes?: Record<string, any>): HTMLElement;
+
+    /** Remove `this.el` from the DOM. */
+    removeElement(): this;
+
+    /**
+     * Provide declarative listeners for DOM events. The events object follows
+     * `{'event selector': 'listener'}` — listener may be a function or a method name on the view.
+     *
+     * Listener signature: `(event, view, matched)`.
+     *
+     * @example
+     * class Modal extends View {
+     *     onClickOk() { this.close(); }
+     * }
+     * Modal.prototype.events = { 'click button.ok': 'onClickOk' };
+     */
+    delegateEvents(events?: Record<string, string | Function>): this;
+
+    /** Removes all of the view's delegated events. */
+    undelegateEvents(): this;
+
+    /**
+     * Core render function. Override to populate the view's element (`this.el`) with HTML.
+     * Convention: always return `this`.
+     */
+    render(): this;
+}

package/types/index.d.ts

@@ -0,0 +1,15 @@
+export { default as Emitter, EventMap } from './Emitter.js';
+export { default as Model, ModelEvents, Attrs } from './Model.js';
+export { default as View, ViewOptions } from './View.js';
+export {
+    default as Component,
+    ComponentOptions,
+    ComponentReservedOptions,
+    SafeHTML,
+    Partial,
+    EventHandler,
+    RenderExpression,
+    Props,
+    State,
+    ComponentModel,
+} from './Component.js';