elegance-js 2.1.23 → 2.1.26

package/dist/components/ClientComponent.d.ts

@@ -0,0 +1,22 @@
+import { ClientSubject } from "../client/runtime";
+import { ServerSubject } from "../client/state";
+import { EleganceElement } from "../elements/element";
+type ClientComponentCallback<D extends readonly ServerSubject<unknown>[]> = (...dependencies: {
+    [K in keyof D]: ClientSubject<D[K]["value"]>;
+}) => EleganceElement<any, any>;
+/**
+ * Create a component that will be client-side rendered.
+ *
+ * You should really only use this for specific things, not as a top-level component.
+ * Server-side rendering is not only faster and more efficient, but also gives your components access to more things.
+ *
+ * This component exists for specific scenarios, such as if you have client-side data fetching that you need to show react-style "suspense" components for.
+ *
+ * **IMPORTANT** `callback` is sent literally as-is to the browser, and thus has no context of server-side variables, and is untrusted.
+ *
+ * @param callback The component to send to the browser.
+ * @param dependencies Any subjects that the component needs access to.
+ * @returns An HTML element to track the position of the Client Component.
+ */
+declare function ClientComponent<const T extends readonly ServerSubject<unknown>[]>(callback: ClientComponentCallback<T>, dependencies: [...T]): EleganceElement<any, true>;
+export { ClientComponent };

package/dist/components/ClientComponent.js

@@ -0,0 +1,55 @@
+import { loadHook } from "../client/loadHook.js";
+import { state } from "../client/state.js";
+import { compilerStore } from "../compilation/compiler.js";
+/**
+ * Create a component that will be client-side rendered.
+ *
+ * You should really only use this for specific things, not as a top-level component.
+ * Server-side rendering is not only faster and more efficient, but also gives your components access to more things.
+ *
+ * This component exists for specific scenarios, such as if you have client-side data fetching that you need to show react-style "suspense" components for.
+ *
+ * **IMPORTANT** `callback` is sent literally as-is to the browser, and thus has no context of server-side variables, and is untrusted.
+ *
+ * @param callback The component to send to the browser.
+ * @param dependencies Any subjects that the component needs access to.
+ * @returns An HTML element to track the position of the Client Component.
+ */
+function ClientComponent(callback, dependencies) {
+    const callbackState = state(callback);
+    const store = compilerStore.getStore();
+    if (!store) {
+        throw new Error("ClientComponent() can only be invoked during the compilation of a page or layout.");
+    }
+    const componentId = state(store.generateId());
+    loadHook((componentId, callback, ...dependencies) => {
+        let node;
+        function update() {
+            node?.remove();
+            const element = callback.value(...dependencies);
+            const HTMLElement = eleganceClient.createHTMLElementFromElement(element);
+            node = HTMLElement.root;
+            const trackedElement = document.querySelector(`template[component-id="${componentId.value}"]`);
+            if (!trackedElement)
+                return;
+            trackedElement.parentElement.insertBefore(HTMLElement.root, trackedElement);
+        }
+        const observers = [];
+        for (const dep of dependencies) {
+            const id = `${Math.random() * 1000 + Date.now()}`;
+            dep.observe(id, update);
+            observers.push({ subject: dep, id, });
+        }
+        update();
+        return () => {
+            node?.remove();
+            for (const observer of observers) {
+                observer.subject.unobserve(observer.id);
+            }
+        };
+    }, [componentId, callbackState, ...dependencies]);
+    return template({
+        "component-id": componentId.value,
+    });
+}
+export { ClientComponent };

package/dist/components/Link.d.ts

@@ -1 +1,16 @@
-export declare const Link: (options: Record<string, any>, ...children: Child[]) => BuiltElement<"a">;
+import { AnyElement, ElementOptionsOrChild, SpecialElementOption } from "../elements/element";
+/**
+ * Create a custom anchor element that let's you hook into client-side navigation.
+ * If provided a URL that is non-local, it will default to normal navigation.
+ * @param options Standard element optins, must include href for the link to work properly.
+ * @param children Standard element children.
+ * @returns A custom anchor element.
+ */
+type ExtraOptions = {
+    /** Mandatory, where this Link should take the user to. */
+    href: string | SpecialElementOption;
+    /** Set window.scrollTop to 0 whenever this link navigates. */
+    resetScrollOnNav?: boolean;
+};
+declare function Link(options: ElementOptionsOrChild<"a", ExtraOptions>, ...children: AnyElement[]): import("..").EleganceElement<"a", true>;
+export { Link, };

package/dist/components/Link.js

@@ -0,0 +1,22 @@
+import { eventListener } from "../client/eventListener.js";
+import { isAnElement } from "../elements/element.js";
+function Link(options, ...children) {
+    const handler = eventListener((event) => {
+        const targetUrl = new URL(event.currentTarget.href, window.location.href);
+        const currentUrl = new URL(window.location.href);
+        const isSameHost = targetUrl.hostname === currentUrl.hostname &&
+            targetUrl.port === currentUrl.port;
+        if (!isSameHost) {
+            return;
+        }
+        event.preventDefault();
+        eleganceClient.navigateLocally(targetUrl.pathname + targetUrl.search + targetUrl.hash, true);
+    }, []);
+    const extraOptions = options && typeof options === "object" ? options : {};
+    const firstChild = isAnElement(options) ? options : undefined;
+    return a({
+        onClick: handler,
+        ...extraOptions,
+    }, ...(firstChild ? [firstChild, ...children] : children));
+}
+export { Link, };

package/dist/components/Portal.d.ts

@@ -0,0 +1,2 @@
+import { AnyElement } from "../elements/element";
+export declare function Portal(element: AnyElement): void;

package/dist/components/Portal.js

@@ -0,0 +1,2 @@
+export function Portal(element) {
+}

package/dist/elements/element.d.ts

@@ -0,0 +1,87 @@
+import type { EventListenerOption } from "../client/eventListener";
+import type { ServerSubject } from "../client/state";
+import type { SpecificPropsMap } from "./specific_props";
+/** Any valid element that has not been constructed via the use of an element constructor such as h1() */
+type ElementLiteral = boolean | number | string | Array<any> | null | undefined | void;
+type AnyElement = EleganceElement<any, any> | ElementLiteral | ServerSubject<any>;
+type ElementChildren = AnyElement[];
+/** Helper to make SpecialElementOption usable on any prop value while preserving original type enforcement */
+export type MaybeSpecial<T> = T | SpecialElementOption;
+/**
+ * An option that should be treated differently by the compiler.
+ */
+declare abstract class SpecialElementOption {
+    /**
+     * Mutate this option in the element to it's serializeable state.
+     */
+    abstract mutate(element: EleganceElement<any, any>, optionName: string): void;
+    /**
+     * Convert this special element option into a string.
+     */
+    abstract serialize(optionName: string, elementKey: string): string;
+}
+type CommonElementProps = {
+    "map-id"?: string;
+    "component-id"?: string;
+    "key"?: string;
+    className?: MaybeSpecial<string>;
+    style?: MaybeSpecial<Record<string, string | number>>;
+    innerHTML?: MaybeSpecial<string>;
+    innerText?: MaybeSpecial<string>;
+    id?: MaybeSpecial<string>;
+    title?: MaybeSpecial<string>;
+    lang?: MaybeSpecial<string>;
+    dir?: MaybeSpecial<"ltr" | "rtl" | "auto">;
+    tabIndex?: MaybeSpecial<number>;
+    role?: MaybeSpecial<string>;
+    draggable?: MaybeSpecial<boolean>;
+    hidden?: MaybeSpecial<boolean>;
+    onClick?: MaybeSpecial<EventListenerOption>;
+    onDoubleClick?: MaybeSpecial<EventListenerOption>;
+    onContextMenu?: MaybeSpecial<EventListenerOption>;
+    onMouseDown?: MaybeSpecial<EventListenerOption>;
+    onMouseUp?: MaybeSpecial<EventListenerOption>;
+    onMouseEnter?: MaybeSpecial<EventListenerOption>;
+    onMouseLeave?: MaybeSpecial<EventListenerOption>;
+    onMouseMove?: MaybeSpecial<EventListenerOption>;
+    onMouseOver?: MaybeSpecial<EventListenerOption>;
+    onMouseOut?: MaybeSpecial<EventListenerOption>;
+    onWheel?: MaybeSpecial<EventListenerOption>;
+    onKeyDown?: MaybeSpecial<EventListenerOption>;
+    onKeyUp?: MaybeSpecial<EventListenerOption>;
+    onKeyPress?: MaybeSpecial<EventListenerOption>;
+    onFocus?: MaybeSpecial<EventListenerOption>;
+    onBlur?: MaybeSpecial<EventListenerOption>;
+    onFocusIn?: MaybeSpecial<EventListenerOption>;
+    onFocusOut?: MaybeSpecial<EventListenerOption>;
+    onChange?: MaybeSpecial<EventListenerOption>;
+    onInput?: MaybeSpecial<EventListenerOption>;
+    onSubmit?: MaybeSpecial<EventListenerOption>;
+    onInvalid?: MaybeSpecial<EventListenerOption>;
+    onReset?: MaybeSpecial<EventListenerOption>;
+    onScroll?: MaybeSpecial<EventListenerOption>;
+    [key: `aria-${string}`]: MaybeSpecial<string | number | boolean | null | undefined>;
+    [key: `data-${string}`]: MaybeSpecial<string | number | boolean | null | undefined>;
+};
+type SpecificProps<Tag extends AllElementTags> = Tag extends keyof SpecificPropsMap ? SpecificPropsMap[Tag] : {};
+type ElementOptions<Tag extends AllElementTags, ExtraOptions extends object = {}> = CommonElementProps & SpecificProps<Tag> & ExtraOptions;
+type ElementOptionsOrChild<Tag extends AllElementTags, ExtraOptions extends object = {}> = ElementOptions<Tag, ExtraOptions> | AnyElement;
+type HtmlChildrenlessElementTags = "area" | "base" | "br" | "col" | "embed" | "hr" | "img" | "input" | "link" | "meta" | "param" | "source" | "track" | "wbr";
+type HtmlElementTags = "a" | "abbr" | "address" | "article" | "aside" | "audio" | "b" | "bdi" | "bdo" | "blockquote" | "body" | "button" | "canvas" | "caption" | "cite" | "code" | "colgroup" | "data" | "datalist" | "dd" | "del" | "details" | "dfn" | "dialog" | "div" | "dl" | "dt" | "em" | "fieldset" | "figcaption" | "figure" | "footer" | "form" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "head" | "header" | "hgroup" | "html" | "i" | "iframe" | "ins" | "kbd" | "label" | "legend" | "li" | "main" | "map" | "mark" | "menu" | "meter" | "nav" | "noscript" | "object" | "ol" | "optgroup" | "option" | "output" | "p" | "picture" | "pre" | "progress" | "q" | "rp" | "rt" | "ruby" | "s" | "samp" | "script" | "search" | "section" | "select" | "slot" | "small" | "span" | "strong" | "style" | "sub" | "summary" | "sup" | "table" | "tbody" | "td" | "template" | "textarea" | "tfoot" | "th" | "thead" | "time" | "title" | "tr" | "u" | "ul" | "varElement" | "video";
+type SvgChildrenlessElementTags = "path" | "circle" | "ellipse" | "line" | "polygon" | "polyline" | "stop";
+type SvgElementTags = "svg" | "g" | "text" | "tspan" | "textPath" | "defs" | "symbol" | "use" | "image" | "clipPath" | "mask" | "pattern" | "linearGradient" | "radialGradient" | "filter" | "marker" | "view" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence";
+type MathMLChildrenlessElementTags = "mi" | "mn" | "mo";
+type MathMLElementTags = "math" | "ms" | "mtext" | "mrow" | "mfenced" | "msup" | "msub" | "msubsup" | "mfrac" | "msqrt" | "mroot" | "mtable" | "mtr" | "mtd" | "mstyle" | "menclose" | "mmultiscripts";
+type AllElementTags = HtmlChildrenlessElementTags | HtmlElementTags | SvgChildrenlessElementTags | SvgElementTags | MathMLChildrenlessElementTags | MathMLElementTags;
+type EleganceElementBuilder<Tag extends AllElementTags> = Tag extends HtmlChildrenlessElementTags | SvgChildrenlessElementTags | MathMLChildrenlessElementTags ? (options?: ElementOptions<Tag>) => EleganceElement<Tag, false> : (options?: ElementOptionsOrChild<Tag>, ...children: ElementChildren) => EleganceElement<Tag, true>;
+declare function isAnElement(value: any): value is AnyElement;
+declare class EleganceElement<Tag extends AllElementTags, CanHaveChildren extends boolean> {
+    readonly tag: Tag;
+    readonly options: ElementOptions<Tag>;
+    key?: string;
+    children: CanHaveChildren extends true ? ElementChildren : null;
+    constructor(tag: Tag, options?: ElementOptionsOrChild<Tag>, children?: ElementChildren | null);
+    canHaveChildren(): this is EleganceElement<Tag, true>;
+}
+export { EleganceElement, SpecialElementOption, isAnElement, };
+export type { EleganceElementBuilder, AnyElement, ElementChildren, AllElementTags, HtmlElementTags, HtmlChildrenlessElementTags, SvgElementTags, SvgChildrenlessElementTags, MathMLElementTags, MathMLChildrenlessElementTags, ElementOptions, ElementOptionsOrChild, };

package/dist/elements/element.js

@@ -0,0 +1,33 @@
+/**
+ * An option that should be treated differently by the compiler.
+ */
+class SpecialElementOption {
+}
+function isAnElement(value) {
+    if (value !== null &&
+        value !== undefined &&
+        (typeof value !== "object" || Array.isArray(value) || value instanceof EleganceElement))
+        return true;
+    return false;
+}
+class EleganceElement {
+    constructor(tag, options = {}, children = null) {
+        this.tag = tag;
+        if (isAnElement(options)) {
+            if (this.canHaveChildren() === false) {
+                console.error("The element:", this, "is an invalid element. Reason:");
+                throw "The options of an element may not be an element, if the element cannot have children.";
+            }
+            this.children = [options, ...(children ?? [])];
+            this.options = {};
+        }
+        else {
+            this.options = options;
+            this.children = children;
+        }
+    }
+    canHaveChildren() {
+        return this.children !== null;
+    }
+}
+export { EleganceElement, SpecialElementOption, isAnElement, };

package/dist/elements/element_list.d.ts

@@ -0,0 +1,7 @@
+import { EleganceElement, EleganceElementBuilder, ElementChildren } from "./element";
+declare const elements: Record<string, EleganceElementBuilder<any>>;
+declare const childrenlessElements: Record<string, EleganceElementBuilder<any>>;
+declare const allElements: {
+    [x: string]: ((options?: any) => EleganceElement<any, false>) | ((options?: any, ...children: ElementChildren) => EleganceElement<any, true>);
+};
+export { elements, childrenlessElements, allElements, };

package/dist/elements/element_list.js

@@ -0,0 +1,65 @@
+import { EleganceElement, } from "./element.js";
+const htmlChildrenlessElementTags = [
+    "area", "base", "br", "col", "embed", "hr", "img", "input",
+    "link", "meta", "param", "source", "track", "wbr",
+];
+const htmlElementTags = [
+    "a", "abbr", "address", "article", "aside", "audio", "b", "bdi", "bdo",
+    "blockquote", "body", "button", "canvas", "caption", "cite", "code",
+    "colgroup", "data", "datalist", "dd", "del", "details", "dfn", "dialog",
+    "div", "dl", "dt", "em", "fieldset", "figcaption", "figure", "footer",
+    "form", "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hgroup",
+    "html", "i", "iframe", "ins", "kbd", "label", "legend", "li", "main",
+    "map", "mark", "menu", "meter", "nav", "noscript", "object", "ol",
+    "optgroup", "option", "output", "p", "picture", "pre", "progress",
+    "q", "rp", "rt", "ruby", "s", "samp", "script", "search", "section",
+    "select", "slot", "small", "span", "strong", "style", "sub", "summary",
+    "sup", "table", "tbody", "td", "template", "textarea", "tfoot", "th",
+    "thead", "time", "title", "tr", "u", "ul", "varElement", "video",
+];
+const svgChildrenlessElementTags = [
+    "path", "circle", "ellipse", "line", "polygon", "polyline", "stop",
+];
+const svgElementTags = [
+    "svg", "g", "text", "tspan", "textPath", "defs", "symbol", "use",
+    "image", "clipPath", "mask", "pattern", "linearGradient", "radialGradient",
+    "filter", "marker", "view",
+    "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite",
+    "feConvolveMatrix", "feDiffuseLighting", "feDisplacementMap", "feDistantLight",
+    "feFlood", "feFuncA", "feFuncB", "feFuncG", "feFuncR", "feGaussianBlur",
+    "feImage", "feMerge", "feMergeNode", "feMorphology", "feOffset",
+    "fePointLight", "feSpecularLighting", "feSpotLight", "feTile", "feTurbulence",
+];
+const mathmlChildrenlessElementTags = [
+    "mi", "mn", "mo",
+];
+const mathmlElementTags = [
+    "math", "ms", "mtext", "mrow", "mfenced", "msup", "msub", "msubsup",
+    "mfrac", "msqrt", "mroot", "mtable", "mtr", "mtd", "mstyle",
+    "menclose", "mmultiscripts",
+];
+const elements = {};
+const childrenlessElements = {};
+function createElementBuilder(tag) {
+    return ((options, ...children) => new EleganceElement(tag, options, children));
+}
+function createChildrenlessElementBuilder(tag) {
+    return ((options) => new EleganceElement(tag, options, null));
+}
+for (const tag of htmlElementTags)
+    elements[tag] = createElementBuilder(tag);
+for (const tag of svgElementTags)
+    elements[tag] = createElementBuilder(tag);
+for (const tag of mathmlElementTags)
+    elements[tag] = createElementBuilder(tag);
+for (const tag of htmlChildrenlessElementTags)
+    childrenlessElements[tag] = createChildrenlessElementBuilder(tag);
+for (const tag of svgChildrenlessElementTags)
+    childrenlessElements[tag] = createChildrenlessElementBuilder(tag);
+for (const tag of mathmlChildrenlessElementTags)
+    childrenlessElements[tag] = createChildrenlessElementBuilder(tag);
+const allElements = {
+    ...elements,
+    ...childrenlessElements,
+};
+export { elements, childrenlessElements, allElements, };

package/dist/elements/raw.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Make an HTML string not be escaped by the Elegance compiler.
+ *
+ * A wrapped string from process A cannot be unwrapped in process B.
+ *
+ * **IMPORTANT:** Do not use this in client components. This functions exists for the *server* to prevent HTML injection.
+ * For most needs element({ innerHTML: "<p>Hello, World!</p>", }); should be enough.
+ * NOTE: Does not return suitable HTML, must be sent to the compiler for processing.
+ * @param html Any HTML string.
+ * @returns HTML string that will not be escaped by the compiler.
+ */
+declare function raw(html: string): string;
+declare function unwrapAllRaw(input: string): string;
+export { raw, unwrapAllRaw, };

package/dist/elements/raw.js

@@ -0,0 +1,78 @@
+import crypto from "crypto";
+/**
+ * Use cryptographically secure random bytes to generate un-escaped HTML that cannot be replicated by any component in-order to unescape itself.
+ */
+const RAW_SECRET = crypto.randomBytes(32);
+const PREFIX = "\uE000RAW:";
+const SEP = "\uE001";
+const SUFFIX = "\uE002";
+/**
+ * Make an HTML string not be escaped by the Elegance compiler.
+ *
+ * A wrapped string from process A cannot be unwrapped in process B.
+ *
+ * **IMPORTANT:** Do not use this in client components. This functions exists for the *server* to prevent HTML injection.
+ * For most needs element({ innerHTML: "<p>Hello, World!</p>", }); should be enough.
+ * NOTE: Does not return suitable HTML, must be sent to the compiler for processing.
+ * @param html Any HTML string.
+ * @returns HTML string that will not be escaped by the compiler.
+ */
+function raw(html) {
+    const mac = crypto.createHmac("sha256", RAW_SECRET)
+        .update(html)
+        .digest("base64url");
+    return PREFIX + mac + SEP + html + SUFFIX;
+}
+function maybeContainsRaw(s) {
+    return s.includes(PREFIX);
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function unwrapAllRaw(input) {
+    if (!maybeContainsRaw(input))
+        return escapeHtml(input);
+    let out = "";
+    let i = 0;
+    while (i < input.length) {
+        const start = input.indexOf(PREFIX, i);
+        if (start === -1) {
+            out += escapeHtml(input.slice(i));
+            break;
+        }
+        out += escapeHtml(input.slice(i, start));
+        const macStart = start + PREFIX.length;
+        const sepIndex = input.indexOf(SEP, macStart);
+        if (sepIndex === -1) {
+            out += escapeHtml(input.slice(start));
+            break;
+        }
+        const suffixIndex = input.indexOf(SUFFIX, sepIndex + 1);
+        if (suffixIndex === -1) {
+            out += escapeHtml(input.slice(start));
+            break;
+        }
+        const mac = input.slice(macStart, sepIndex);
+        const html = input.slice(sepIndex + 1, suffixIndex);
+        const expected = crypto.createHmac("sha256", RAW_SECRET)
+            .update(html)
+            .digest("base64url");
+        const macBuf = Buffer.from(mac);
+        const expBuf = Buffer.from(expected);
+        if (macBuf.length === expBuf.length &&
+            crypto.timingSafeEqual(macBuf, expBuf)) {
+            out += html;
+        }
+        else {
+            out += escapeHtml(input.slice(start, suffixIndex + 1));
+        }
+        i = suffixIndex + SUFFIX.length;
+    }
+    return out;
+}
+export { raw, unwrapAllRaw, };