@source-crafter/xzor-runtime 0.0.0-stage → 0.1.1

package/index.d.ts

@@ -0,0 +1,233 @@
+type Handler = (e: Event) => unknown;
+type Modifier = "preventDefault" | "stopPropagation";
+type Modifiers = Partial<Record<Modifier, boolean>>;
+export type VText = {
+    kind: "text";
+    text: string;
+    dom?: Text;
+};
+export type VElement = {
+    kind: "element";
+    tag: string;
+    attrs: Record<string, string>;
+    events: Record<string, Handler>;
+    modifiers: Record<string, Modifiers>;
+    children: VNode[];
+    key?: unknown;
+    ref?: (el: Element) => void;
+    dom?: Element;
+};
+/** One `@cascade:name(value)` provider; created on the region's first render and carried across the next ones. */
+type CascadeRecord = {
+    name: string;
+    value: unknown;
+    fixed: boolean;
+    consumers: Set<ComponentBase> | undefined;
+    parent: CascadeRecord | undefined;
+};
+/** Output of one `@if`/`@for`/`@switch`/`@cascade`; its contents are diffed in isolation. */
+export type VRegion = {
+    kind: "region";
+    children: VNode[];
+    anchor?: Comment;
+    name?: string;
+    value?: unknown;
+    fixed?: boolean;
+    cascade?: CascadeRecord;
+};
+/** A child component; the diff decides whether it keeps its previous instance. */
+export type VComponent = {
+    kind: "component";
+    type: Ctor<ComponentBase>;
+    props: Record<string, unknown>;
+    slots?: object;
+    key?: unknown;
+    ref?: (c: ComponentBase) => void;
+    instance?: ComponentBase;
+    mounted?: Mounted;
+    onError?: (err: unknown, nav: number) => void;
+    nav?: number;
+};
+export type VNode = VText | VElement | VRegion | VComponent;
+/** One entry of the generated `.xzor/routes.ts` table; `match` converts the path segments or rejects them. */
+export type RouteEntry = {
+    tag: string | undefined;
+    pattern: string;
+    /** The page's shortest pattern this one extends: routes of one family share the page instance. */
+    family?: string;
+    component: unknown;
+    match: (s: string[]) => Record<string, unknown> | null;
+};
+/** The project's routes, in precedence order. */
+export type RouteTable = readonly RouteEntry[];
+/**
+ * The state of the current navigation, published to the routes block and as the cascading value `route`.
+ * `Tags` maps each route tag to its params; the generated table fixes it (`AppRoute`) so `is` checks tags.
+ */
+export declare class Route<P = Record<string, unknown>, Tags extends object = Record<string, Record<string, unknown>>> {
+    #private;
+    readonly path: string;
+    readonly tag: (keyof Tags & string) | undefined;
+    readonly params: P;
+    readonly query: URLSearchParams;
+    readonly match: Record<string, string>;
+    constructor(path: string, tag: (keyof Tags & string) | undefined, params: P, query: URLSearchParams, match: Record<string, string>, nav?: Navigation);
+    /** Narrows `params` to the routes carrying `tag`. */
+    is<K extends keyof Tags & string>(tag: K): this is Route<Tags[K], Tags> & {
+        readonly tag: K;
+    };
+    /** History navigation under `@ClientRoutes`; `@ServerRoutes` loads the url. */
+    navigate(url: string, opts?: {
+        replace?: boolean;
+    }): void;
+}
+/** One section of a `@ClientRoutes`/`@ServerRoutes` block; xzor emits these in source order. */
+export type RouteSection = {
+    kind: "tag";
+    tag: string;
+    render: (route: Route, page: RenderFragment) => RenderFragment;
+} | {
+    kind: "regex";
+    re: RegExp;
+    page: boolean;
+    render: (route: Route, page: RenderFragment) => RenderFragment;
+} | {
+    kind: "pattern";
+    match: (segments: string[]) => Record<string, string> | null;
+    page: boolean;
+    render: (route: Route, page: RenderFragment) => RenderFragment;
+} | {
+    kind: "notFound";
+    render: (route: Route) => RenderFragment;
+} | {
+    kind: "catch";
+    render: (route: Route, error: unknown) => RenderFragment;
+} | {
+    kind: "default";
+    render: (route: Route, page: RenderFragment) => RenderFragment;
+};
+/** How `@ClientRoutes` reaches the browser's history; `setNavigationForTests` swaps it. */
+export type Navigation = {
+    current(): URL;
+    navigate(url: string, replace: boolean): void;
+    subscribe(fn: () => void): () => void;
+    /** Like `subscribe`, without taking over link clicks (a `NavLink` only watches). Defaults to `subscribe`. */
+    observe?(fn: () => void): () => void;
+};
+/** @internal Swaps in a memory navigation; set it before mounting the routes block. */
+export declare function setNavigationForTests(nav: Navigation | undefined): void;
+/** The path of `<base href>` without its last segment: "" without one, "/docs" under `<base href="/docs/">`. */
+export declare function basePath(): string;
+type Ctor<C extends ComponentBase> = new (...args: any[]) => C;
+type Mounted = {
+    tree: VNode[];
+    anchor: Comment;
+    app: IApplication | undefined;
+    scope: CascadeRecord | undefined;
+    latest: VComponent | undefined;
+    pass: number;
+    nav?: number;
+};
+/** Builds components that need injected services; generated by xzor from `@Mount` and `@ServiceProvider`. */
+export interface IApplication {
+    onStarted?(): void | Promise<void>;
+    /** Consulted only for component classes with a non-empty `static inject`; returns the component, a promise for it, or `undefined` (the runtime then throws). */
+    createComponent?(type: Function): ComponentBase | Promise<ComponentBase> | undefined;
+}
+type DisposeSymbols = {
+    dispose: symbol;
+    asyncDispose: symbol;
+};
+/** @internal Engines without explicit resource management get the registry symbols that TypeScript's downlevel helpers use. */
+export declare function polyfillDisposeSymbols(target: Partial<DisposeSymbols>): void;
+type ServiceDecorator = {
+    <T>(impl: new (...a: any[]) => T): ClassDecorator;
+    <T>(key: string, factory: (...a: any[]) => T | Promise<T>): ClassDecorator;
+};
+export declare const ServiceProvider: () => ClassDecorator;
+export declare const Mount: (_component: Function, _target: string) => ClassDecorator;
+export declare const Import: (..._providers: Function[]) => ClassDecorator;
+export declare const Singleton: ServiceDecorator;
+export declare const Scoped: ServiceDecorator;
+export declare const Transient: ServiceDecorator;
+export declare const SharedInstance: unique symbol;
+declare const FRAGMENT: unique symbol;
+type Fragment = ((builder: RenderTreeBuilder) => void) & {
+    readonly [FRAGMENT]: true;
+};
+/** Markup held as a value (Blazor's RenderFragment); render it with `@member`. */
+export type RenderFragment = Fragment;
+export type Renderer = RenderFragment;
+/** A component event; invoking it re-renders the component that passed it in. */
+export type EventCallback<T = void> = (arg: T) => unknown;
+/** The DOM element type for a tag name, as `document.createElement` would return it. */
+export type ElementOf<T extends string> = T extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[T] : T extends keyof SVGElementTagNameMap ? SVGElementTagNameMap[T] : HTMLElement;
+export declare abstract class ComponentBase {
+    /** Wraps builder calls as a RenderFragment; xzor emits this for markup used as a value. */
+    static fragment(build: (builder: RenderTreeBuilder) => void): RenderFragment;
+    /** Reads a bound input's new value, converted to the bound field's current type. */
+    static bindValue<T>(e: Event, current: T): T;
+    /** Content the parent passed for each `@slot`; xzor declares the exact type per component. */
+    slots: {};
+    protected abstract buildRenderTree(builder: RenderTreeBuilder): void;
+    protected onInitialized(): void;
+    protected onInitializedAsync(): Promise<void> | void;
+    protected onParametersSet(): void;
+    protected onParametersSetAsync(): Promise<void> | void;
+    protected onAfterRender(_firstRender: boolean): void;
+    protected onAfterRenderAsync(_firstRender: boolean): Promise<void> | void;
+    protected shouldRender(): boolean;
+    /** Called when the component leaves the tree. */
+    protected dispose(): void;
+    /** Re-renders this component. Event handlers it owns do this automatically. */
+    stateHasChanged(): void;
+}
+export declare class RenderTreeBuilder {
+    #private;
+    private readonly owner;
+    constructor(owner: ComponentBase);
+    get nodes(): VNode[];
+    openElement(tag: string): void;
+    closeElement(): void;
+    openRegion(): void;
+    /** `@cascade:name(value)`: a region whose children see `value` under `name`; `fixed` keeps the first value. */
+    openCascade(name: string, value: unknown, fixed?: boolean): void;
+    closeRegion(): void;
+    /** `@ClientRoutes`/`@ServerRoutes`: renders the section that matches the current navigation. */
+    addRoutes(engine: "client" | "server", table: RouteTable, sections: readonly RouteSection[]): void;
+    addAttribute(name: string, value: unknown): void;
+    /** `@attributes`: each entry is added in order, so later attributes override it. */
+    addAttributes(attrs: Record<string, unknown> | null | undefined): void;
+    /** `@onclick:preventDefault` and `@onclick:stopPropagation`, with or without a handler. */
+    addEventModifier(event: string, modifier: Modifier, enabled: boolean): void;
+    /** `@key`: list diffs match this element by key instead of position. */
+    setKey(key: unknown): void;
+    /** `@ref`: receives the DOM element (typed from its tag) after each render. */
+    setRef<T extends string>(_tag: T, ref: (el: ElementOf<T>) => void): void;
+    addEventHandler<K extends keyof HTMLElementEventMap>(event: K, handler: (e: HTMLElementEventMap[K]) => unknown): void;
+    addEventHandler(event: string, handler: Handler): void;
+    addText(text: string): void;
+    addContent(value: unknown): void;
+    addComponent<C extends ComponentBase>(type: Ctor<C>, props: Partial<C>, slots?: C["slots"], extra?: {
+        key?: unknown;
+        ref?: (c: C) => void;
+    }): void;
+    /** Wraps a handler passed to a child as an EventCallback (re-renders this owner). */
+    callback<T>(handler: (arg: T) => unknown): EventCallback<T>;
+}
+/** `target` is an element, an element id, or a selector (anything containing `#`, `.` or `[`). */
+export declare function mount<C extends ComponentBase>(type: Ctor<C>, target: string | Element, app?: IApplication): C;
+/** An `<a>` that carries `activeClass` while the current URL is on its `href`; it follows navigation itself. */
+export declare class NavLink extends ComponentBase {
+    #private;
+    href: string;
+    activeClass: string;
+    match: "prefix" | "exact";
+    slots: {
+        default?: () => RenderFragment;
+    };
+    protected onInitialized(): void;
+    protected dispose(): void;
+    protected buildRenderTree(b: RenderTreeBuilder): void;
+}
+export {};