elegance-js 2.1.22 → 2.1.24

package/dist/client/effect.d.ts

@@ -0,0 +1,27 @@
+import { ServerSubject } from "./state";
+import type { ClientSubject } from "./runtime";
+type EffectCallback<D extends readonly ServerSubject<unknown>[]> = (...dependencies: {
+    [K in keyof D]: ClientSubject<D[K]["value"]>;
+}) => any;
+declare class Effect<const T extends readonly ServerSubject<unknown>[]> {
+    callback: EffectCallback<T>;
+    dependencies: string[];
+    id: string;
+    constructor(callback: EffectCallback<T>, dependencies: [...T], id: string);
+    serialize(): string;
+}
+/**
+ * Creates a browser-side callback that is called upon navigation to a given page.
+ * It may return a cleanup function which will be called when the Effect goes out of scope.
+ * If it is declared within a layout, is it pathname scoped, and it's cleanupFunction will be called when the layout is no longer active.
+ * Eg. Navigation from /recipes/cake to /recipes will call the cleanup of /recipes/cake's page, and it's layout, but not /recipes, since it's pathname is in the new pathname we're navigating to.
+ *
+ * **IMPORTANT**: The callback is *browser-code*, and thus does not have any context of your page.ts or layout.ts file.
+ * The callback function is sent *literally* to the browser, as-is.
+ *
+ * @param callback The browser-side contextless code the Effect will run.
+ * @param dependencies A dependency of state that will be passed into this Effect
+ */
+declare function effect<const T extends readonly ServerSubject<unknown>[]>(callback: EffectCallback<T>, dependencies: [...T]): void;
+export { effect, Effect };
+export type { EffectCallback, };

package/dist/client/effect.js

@@ -0,0 +1,37 @@
+import { compilerStore } from "../compilation/compiler.js";
+class Effect {
+    constructor(callback, dependencies, id) {
+        this.callback = callback;
+        this.dependencies = dependencies.map(d => d.id);
+        this.id = id;
+    }
+    serialize() {
+        let result = "{";
+        result += `callback:${this.callback.toString()},`;
+        result += `dependencies:[${this.dependencies.map(d => `"${d}"`).join(",")}],`;
+        result += `id:"${this.id}",`;
+        result += "}";
+        return result;
+    }
+}
+/**
+ * Creates a browser-side callback that is called upon navigation to a given page.
+ * It may return a cleanup function which will be called when the Effect goes out of scope.
+ * If it is declared within a layout, is it pathname scoped, and it's cleanupFunction will be called when the layout is no longer active.
+ * Eg. Navigation from /recipes/cake to /recipes will call the cleanup of /recipes/cake's page, and it's layout, but not /recipes, since it's pathname is in the new pathname we're navigating to.
+ *
+ * **IMPORTANT**: The callback is *browser-code*, and thus does not have any context of your page.ts or layout.ts file.
+ * The callback function is sent *literally* to the browser, as-is.
+ *
+ * @param callback The browser-side contextless code the Effect will run.
+ * @param dependencies A dependency of state that will be passed into this Effect
+ */
+function effect(callback, dependencies) {
+    const store = compilerStore.getStore();
+    if (!store)
+        throw new Error("Illegal invocation of effect(). Ensure that the effect() function is only called inside components, and never at the top-level of a page or layout.");
+    const id = store.generateId();
+    const effect = new Effect(callback, dependencies, id);
+    store.addClientToken(effect);
+}
+export { effect, Effect };

package/dist/client/eventListener.d.ts

@@ -0,0 +1,39 @@
+import { EleganceElement, SpecialElementOption } from "../elements/element";
+import { ServerSubject } from "./state";
+import { ClientSubject } from "./runtime";
+type SetEvent<E extends Event = Event, T extends EventTarget = EventTarget> = E & {
+    target: T;
+    currentTarget: T;
+};
+type ToClientTuple<T extends readonly ServerSubject<any>[]> = {
+    [K in keyof T]: T[K] extends ServerSubject<infer V> ? ClientSubject<V> : never;
+};
+type EventListenerCallback<T extends readonly ServerSubject<any>[]> = (event: SetEvent, ...dependencies: ToClientTuple<T>) => void;
+declare class EventListenerOption extends SpecialElementOption {
+    id: string;
+    constructor(id: string);
+    mutate(element: EleganceElement<any, any>, optionName: string): void;
+    serialize(optionName: string, elementKey: string): string;
+}
+declare class EventListener<T extends readonly ServerSubject<any>[]> {
+    id: string;
+    callback: EventListenerCallback<T>;
+    dependencies: string[];
+    constructor(id: string, callback: EventListenerCallback<T>, dependencies: [...T]);
+    serialize(): string;
+}
+/**
+ * Creates, an event listener, which is a callback that is called when the event that it is attached to, is triggered.
+ * If you intend to use the same eventListener many times, declare it once, and use the returned special element option as the reference to it.
+ * This ships less code to the browser.
+ *
+ * **IMPORTANT**: The callback is *browser-code*, and thus does not have any context of your page.ts or layout.ts file.
+ * The callback function is sent *literally* to the browser, as-is.
+ *
+ * @param callback The function to be called when the event that this eventListener is attached to is triggered.
+ * @param dependencies An array of ServerSubject's that should be passed into the callback when it is run.
+ * @returns A special element option that you can use as a value on an option of an EleganceElement.
+ */
+declare function eventListener<T extends readonly ServerSubject<any>[]>(callback: EventListenerCallback<T>, dependencies: [...T]): EventListenerOption;
+export { eventListener, EventListenerOption, EventListener };
+export type { EventListenerCallback, SetEvent, ToClientTuple };

package/dist/client/eventListener.js

@@ -0,0 +1,52 @@
+import { SpecialElementOption } from "../elements/element.js";
+import { compilerStore } from "../compilation/compiler.js";
+class EventListenerOption extends SpecialElementOption {
+    constructor(id) {
+        super();
+        this.id = id;
+    }
+    mutate(element, optionName) {
+        // this cast is fine
+        delete element.options[optionName];
+    }
+    serialize(optionName, elementKey) {
+        let result = "{";
+        result += `option:"${optionName.toLowerCase()}",`;
+        result += `key:"${elementKey}",`;
+        result += `id:"${this.id}"`;
+        result += "}";
+        return result;
+    }
+}
+class EventListener {
+    constructor(id, callback, dependencies) {
+        this.id = id;
+        this.callback = callback;
+        this.dependencies = dependencies.map(d => d.id);
+    }
+    serialize() {
+        return `{id:\"${this.id}\",callback:${this.callback.toString()},dependencies:[${this.dependencies.map(d => `"${d}"`).join(",")}]}`;
+    }
+}
+/**
+ * Creates, an event listener, which is a callback that is called when the event that it is attached to, is triggered.
+ * If you intend to use the same eventListener many times, declare it once, and use the returned special element option as the reference to it.
+ * This ships less code to the browser.
+ *
+ * **IMPORTANT**: The callback is *browser-code*, and thus does not have any context of your page.ts or layout.ts file.
+ * The callback function is sent *literally* to the browser, as-is.
+ *
+ * @param callback The function to be called when the event that this eventListener is attached to is triggered.
+ * @param dependencies An array of ServerSubject's that should be passed into the callback when it is run.
+ * @returns A special element option that you can use as a value on an option of an EleganceElement.
+ */
+function eventListener(callback, dependencies) {
+    const store = compilerStore.getStore();
+    if (!store)
+        throw new Error("Illegal invocation of eventListener(). Ensure that the eventListener() function is only called inside components, and never at the top-level of a page or layout.");
+    const id = store.generateId();
+    const listener = new EventListener(id, callback, dependencies);
+    store.addClientToken(listener);
+    return new EventListenerOption(id);
+}
+export { eventListener, EventListenerOption, EventListener };

package/dist/client/loadHook.d.ts

@@ -0,0 +1,34 @@
+import { ServerSubject } from "./state";
+import type { ClientSubject } from "./runtime";
+declare enum LoadHookKind {
+    LAYOUT_LOADHOOK = 0,
+    PAGE_LOADHOOK = 1
+}
+type LoadHookCleanupFunction = (() => void);
+type LoadHookCallback<D extends readonly ServerSubject<unknown>[]> = (...dependencies: {
+    [K in keyof D]: ClientSubject<D[K]["value"]>;
+}) => LoadHookCleanupFunction | void;
+declare class LoadHook<const T extends readonly ServerSubject<unknown>[]> {
+    pathname?: string;
+    kind: LoadHookKind;
+    callback: LoadHookCallback<T>;
+    dependencies: string[];
+    id: string;
+    constructor(callback: LoadHookCallback<T>, dependencies: [...T], kind: LoadHookKind, id: string, pathname?: string);
+    serialize(): string;
+}
+/**
+ * Creates a browser-side callback that is called upon navigation to a given page.
+ * It may return a cleanup function which will be called when the loadHook goes out of scope.
+ * If it is declared within a layout, is it pathname scoped, and it's cleanupFunction will be called when the layout is no longer active.
+ * Eg. Navigation from /recipes/cake to /recipes will call the cleanup of /recipes/cake's page, and it's layout, but not /recipes, since it's pathname is in the new pathname we're navigating to.
+ *
+ * **IMPORTANT**: The callback is *browser-code*, and thus does not have any context of your page.ts or layout.ts file.
+ * The callback function is sent *literally* to the browser, as-is.
+ *
+ * @param callback The browser-side contextless code the loadHook will run.
+ * @param dependencies A dependency of state that will be passed into this loadHook
+ */
+declare function loadHook<const T extends readonly ServerSubject<unknown>[]>(callback: LoadHookCallback<T>, dependencies: [...T]): void;
+export { loadHook, LoadHook };
+export type { LoadHookCallback, LoadHookCleanupFunction, LoadHookKind, };

package/dist/client/loadHook.js

@@ -0,0 +1,52 @@
+import { compilerStore } from "../compilation/compiler.js";
+var LoadHookKind;
+(function (LoadHookKind) {
+    LoadHookKind[LoadHookKind["LAYOUT_LOADHOOK"] = 0] = "LAYOUT_LOADHOOK";
+    LoadHookKind[LoadHookKind["PAGE_LOADHOOK"] = 1] = "PAGE_LOADHOOK";
+})(LoadHookKind || (LoadHookKind = {}));
+;
+class LoadHook {
+    constructor(callback, dependencies, kind, id, pathname) {
+        this.pathname = pathname;
+        this.callback = callback;
+        this.kind = kind;
+        this.dependencies = dependencies.map(d => d.id);
+        this.id = id;
+    }
+    serialize() {
+        let result = "{";
+        result += `callback:${this.callback.toString()},`;
+        result += `dependencies:[${this.dependencies.map(d => `"${d}"`).join(",")}],`;
+        result += `id:"${this.id}",`;
+        result += `kind:${this.kind}`;
+        if (this.kind === LoadHookKind.LAYOUT_LOADHOOK && this.pathname) {
+            result += `,pathname:"${this.pathname}"`;
+        }
+        result += "}";
+        return result;
+    }
+}
+/**
+ * Creates a browser-side callback that is called upon navigation to a given page.
+ * It may return a cleanup function which will be called when the loadHook goes out of scope.
+ * If it is declared within a layout, is it pathname scoped, and it's cleanupFunction will be called when the layout is no longer active.
+ * Eg. Navigation from /recipes/cake to /recipes will call the cleanup of /recipes/cake's page, and it's layout, but not /recipes, since it's pathname is in the new pathname we're navigating to.
+ *
+ * **IMPORTANT**: The callback is *browser-code*, and thus does not have any context of your page.ts or layout.ts file.
+ * The callback function is sent *literally* to the browser, as-is.
+ *
+ * @param callback The browser-side contextless code the loadHook will run.
+ * @param dependencies A dependency of state that will be passed into this loadHook
+ */
+function loadHook(callback, dependencies) {
+    const store = compilerStore.getStore();
+    if (!store)
+        throw new Error("Illegal invocation of loadHook(). Ensure that the loadHook() function is only called inside components, and never at the top-level of a page or layout.");
+    const isLayoutLoadHook = store.compilationContext.kind === "layout";
+    const loadHookKind = isLayoutLoadHook === true ? LoadHookKind.LAYOUT_LOADHOOK : LoadHookKind.PAGE_LOADHOOK;
+    const pathname = loadHookKind === LoadHookKind.LAYOUT_LOADHOOK ? store.compilationContext.pathname : undefined;
+    const id = store.generateId();
+    const loadHook = new LoadHook(callback, dependencies, loadHookKind, id, pathname);
+    store.addClientToken(loadHook);
+}
+export { loadHook, LoadHook };

package/dist/client/observer.d.ts

@@ -0,0 +1,36 @@
+import { EleganceElement, SpecialElementOption } from "../elements/element";
+import { ServerSubject } from "./state";
+import { ClientSubject } from "./runtime";
+type ObserverCallback<T extends readonly ServerSubject<unknown>[]> = (this: HTMLElement, ...dependencies: {
+    [K in keyof T]: ClientSubject<T[K]["value"]>["value"];
+}) => string | boolean | number | Record<string, unknown>;
+declare class ObserverOption extends SpecialElementOption {
+    id: string;
+    constructor(id: string);
+    mutate(element: EleganceElement<any, any>, optionName: string): void;
+    serialize(optionName: string, elementKey: string): string;
+}
+declare class ServerObserver<const T extends readonly ServerSubject<unknown>[]> {
+    id: string;
+    callback: ObserverCallback<T>;
+    dependencies: string[];
+    constructor(id: string, callback: ObserverCallback<T>, dependencies: [...T]);
+    serialize(): string;
+}
+/**
+ * Create an observer.
+ *
+ * [Read More](https://elegance.js.org/observers)
+ * @param callbackOrSubject A callback to call whenever any of the `dependencies` changes.
+ * @param dependencies An array of dependencies to watch.
+ * @returns A special element option you attach to any attribute of an element.
+ */
+declare function observer<T extends ServerSubject<unknown>>(subject: T): ObserverOption;
+declare function observer<const T extends readonly ServerSubject<unknown>[]>(callback: ObserverCallback<T>, dependencies: [...T]): ObserverOption;
+/**
+ *
+ * @returns The HTML Element this observer is attached to.
+ */
+declare const getSelf: () => HTMLElement;
+export { observer, ServerObserver, ObserverOption, getSelf, };
+export type { ObserverCallback, };

package/dist/client/observer.js

@@ -0,0 +1,66 @@
+import { SpecialElementOption } from "../elements/element.js";
+import { compilerStore } from "../compilation/compiler.js";
+class ObserverOption extends SpecialElementOption {
+    constructor(id) {
+        super();
+        this.id = id;
+    }
+    mutate(element, optionName) {
+        delete element.options[optionName];
+    }
+    serialize(optionName, elementKey) {
+        let result = "{";
+        result += `option:"${optionName}",`;
+        result += `key:"${elementKey}",`;
+        result += `id:"${this.id}"`;
+        result += "}";
+        return result;
+    }
+}
+class ServerObserver {
+    constructor(id, callback, dependencies) {
+        this.id = id;
+        this.callback = callback;
+        this.dependencies = dependencies.map(d => d.id);
+    }
+    serialize() {
+        let result = "{";
+        result += `id:"${this.id}",`;
+        result += `callback:${this.callback.toString()},`;
+        result += `dependencies:[${this.dependencies.map(d => `"${d}"`).join(",")}],`;
+        result += "}";
+        return result;
+    }
+}
+function observer(callbackOrSubject, dependencies) {
+    const store = compilerStore.getStore();
+    if (!store) {
+        throw new Error("Illegal invocation of observer(). Ensure that the observer() function is only called inside components, and never at the top-level of a page or layout.");
+    }
+    let callback;
+    let deps;
+    if (dependencies) {
+        callback = callbackOrSubject;
+        deps = dependencies;
+    }
+    else {
+        const subject = callbackOrSubject;
+        callback = (s) => `${s.value}`;
+        deps = [subject];
+    }
+    const id = store.generateId();
+    const listener = new ServerObserver(id, callback, deps);
+    store.addClientToken(listener);
+    return new ObserverOption(id);
+}
+/**
+ *
+ * @returns The HTML Element this observer is attached to.
+ */
+const getSelf = function () {
+    // this is just a stub, the implementation exists only in the browser,
+    // but we need typescript to sh
+    //@ts-ignore
+    return "CLIENT_SIDE_FUNCTION";
+};
+export { observer, ServerObserver, ObserverOption, getSelf, };

package/dist/client/runtime.d.ts

@@ -0,0 +1,105 @@
+import type { EventListener, EventListenerCallback } from "./eventListener";
+import type { LoadHook } from "./loadHook";
+import type { ServerObserver } from "./observer";
+import type { ServerSubject } from "./state";
+import type { Effect } from "./effect";
+/**
+ * A ServerSubject that has been serialized, shipped to the browser, and re-created as it's final form.
+ *
+ * Setting the `value` of this ClientSubject will trigger it's observers callbacks.
+ *
+ * To listen for changes in `value`, you may call the `observe()` method.
+ */
+declare class ClientSubject<T> {
+    readonly id: string;
+    private _value;
+    private readonly observers;
+    constructor(id: string, value: T);
+    get value(): T;
+    set value(newValue: T);
+    /**
+     * Manually trigger each of this subject's observers, with the subject's current value.
+     *
+     * Useful if you're mutating for example fields of an object, or pushing to an array.
+     */
+    triggerObservers(): void;
+    /**
+     * Add a new observer to this subject, `callback` is called whenever the value setter is called on this subject.
+     *
+     * Note: if an ID is already in use it's callback will just be overwritten with whatever you give it.
+     *
+     * Note: this triggers `callback` with the current value of this subject.
+     *
+     * @param id The unique id of this observer
+     * @param callback Called whenever the value of this subject changes.
+     */
+    observe(id: string, callback: (newValue: T) => void): void;
+    /**
+     * Remove an observer from this subject.
+     * @param id The unique id of the observer.
+     */
+    unobserve(id: string): void;
+}
+declare class StateManager {
+    private readonly subjects;
+    constructor();
+    loadValues(values: ServerSubject<any>[], doOverwrite?: boolean): void;
+    get(id: string): ClientSubject<any> | undefined;
+    getAll(ids: string[]): Array<ClientSubject<any>>;
+}
+type ClientEventListenerOption = {
+    /** The html attribute name this option should be attached to */
+    option: string;
+    /** The key of the element this option should be attached to. */
+    key: string;
+    /** The event listener id this option is referencing. */
+    id: string;
+};
+/**
+ * An event listener after it has been generated on the server, processed into pagedata, and reconstructed on the client.
+ */
+declare class ClientEventListener {
+    id: string;
+    callback: EventListenerCallback<any>;
+    dependencies: string[];
+    constructor(id: string, callback: EventListenerCallback<any>, depencencies: string[]);
+    call(ev: Event): void;
+}
+declare class EventListenerManager {
+    private readonly eventListeners;
+    constructor();
+    loadValues(serverEventListeners: EventListener<any>[], doOverride?: boolean): void;
+    hookCallbacks(eventListenerOptions: ClientEventListenerOption[]): void;
+    get(id: string): ClientEventListener | undefined;
+}
+type ClientObserverOption = {
+    /** The html attribute name this option should be attached to */
+    option: string;
+    /** The key of the element this option should be attached to. */
+    key: string;
+    /** The event listener id this option is referencing. */
+    id: string;
+};
+declare class ObserverManager {
+    private readonly clientObservers;
+    constructor();
+    loadValues(serverObservers: ServerObserver<any>[], doOverride?: boolean): void;
+    hookCallbacks(observerOptions: ClientObserverOption[]): void;
+    /**
+     * Take the results of ServerSubject.generateObserverNode(), replace their HTML placeins for text nodes, and turn those into observers.
+     */
+    transformSubjectObserverNodes(): void;
+}
+declare class EffectManager {
+    private activeEffects;
+    private cleanupProcedures;
+    loadValues(effects: Effect<any>[]): void;
+}
+declare class LoadHookManager {
+    private cleanupProcedures;
+    private activeLoadHooks;
+    constructor();
+    loadValues(loadHooks: LoadHook<any>[]): void;
+    callCleanupFunctions(): void;
+}
+export { ClientSubject, StateManager, ObserverManager, LoadHookManager, EventListenerManager, EffectManager, };