@lushly-dev/fast-element 3.0.1-preview.0 → 3.0.1-preview.2

package/dist/esm/components/hydration-tracker.js

@@ -0,0 +1,211 @@
+import { FASTElementDefinition } from "./fast-definitions.js";
+/**
+ * Describes when FAST should stop hydrating newly connected prerendered elements.
+ * @public
+ */
+export const StopHydration = Object.freeze({
+    /**
+     * Stop hydrating new prerendered elements after the active hydration batch completes.
+     */
+    hydrationComplete: "hydration-complete",
+    /**
+     * Keep the hydration hook active for later prerendered elements.
+     */
+    never: "never",
+});
+/**
+ * Tracks prerendered elements through the hydration lifecycle and
+ * exposes the active global hydration completion promise.
+ *
+ * @public
+ */
+export class HydrationTracker {
+    constructor(options) {
+        var _a;
+        this.elements = new Set();
+        this.elementTags = new WeakMap();
+        this.tagHydrationStates = new Map();
+        this.started = false;
+        this.completed = false;
+        this.checkTimer = null;
+        this.resolveWhenHydrated = null;
+        this.prepareHydrationPromise();
+        this.stopHydration = (_a = options.stopHydration) !== null && _a !== void 0 ? _a : StopHydration.hydrationComplete;
+    }
+    /**
+     * Resolves when the active hydration batch completes, or when hydration work
+     * for the specified tag name completes.
+     */
+    whenHydrated(tagName) {
+        if (tagName !== void 0) {
+            return this.getTagHydrationPromise(tagName);
+        }
+        return this._whenHydrated;
+    }
+    /**
+     * Indicates whether the hydration hook should attempt to hydrate
+     * prerendered elements.
+     */
+    get shouldHydrate() {
+        return !this.completed || this.stopHydration === StopHydration.never;
+    }
+    /**
+     * Registers an element as pending hydration.
+     */
+    add(element) {
+        var _a;
+        var _b;
+        this.completed = false;
+        if (!this.started) {
+            this.started = true;
+            if (this.resolveWhenHydrated === null) {
+                this.prepareHydrationPromise();
+            }
+        }
+        if (!this.elements.has(element)) {
+            const tagName = (_b = (_a = FASTElementDefinition.getForInstance(element)) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : element.localName;
+            this.elements.add(element);
+            this.elementTags.set(element, tagName);
+            this.addTagHydration(tagName);
+        }
+    }
+    /**
+     * Removes an element from the pending set and schedules
+     * a debounced completion check.
+     */
+    remove(element) {
+        if (this.elements.delete(element)) {
+            const tagName = this.elementTags.get(element);
+            if (tagName !== void 0) {
+                this.elementTags.delete(element);
+                this.removeTagHydration(tagName);
+            }
+        }
+        // Debounce: reset on every removal so we wait until no
+        // new elements arrive before declaring complete.
+        if (this.checkTimer !== null) {
+            clearTimeout(this.checkTimer);
+        }
+        if (this.elements.size === 0) {
+            this.checkTimer = setTimeout(() => {
+                this.checkTimer = null;
+                if (this.elements.size === 0) {
+                    if (this.stopHydration !== StopHydration.never) {
+                        this.resolveHydrationPromise();
+                        this.completed = true;
+                    }
+                    this.started = false;
+                }
+            }, 0);
+        }
+    }
+    /**
+     * Merges additional options into the tracker.
+     */
+    mergeOptions(incoming) {
+        if (incoming.stopHydration !== void 0) {
+            this.stopHydration = incoming.stopHydration;
+            if (incoming.stopHydration === StopHydration.never &&
+                this.resolveWhenHydrated === null) {
+                this.prepareHydrationPromise();
+            }
+        }
+    }
+    prepareHydrationPromise() {
+        this._whenHydrated = new Promise(resolve => {
+            this.resolveWhenHydrated = resolve;
+        });
+    }
+    getTagHydrationPromise(tagName) {
+        const state = this.getTagHydrationState(tagName);
+        if (this.completed && this.stopHydration !== StopHydration.never) {
+            this.resolveTagHydrationState(state);
+        }
+        return state.promise;
+    }
+    addTagHydration(tagName) {
+        const state = this.getTagHydrationState(tagName);
+        if (state.resolveTimer !== null) {
+            clearTimeout(state.resolveTimer);
+            state.resolveTimer = null;
+        }
+        if (state.resolved) {
+            this.prepareTagHydrationState(state);
+        }
+        state.pendingCount++;
+    }
+    removeTagHydration(tagName) {
+        const state = this.getTagHydrationState(tagName);
+        if (state.pendingCount > 0) {
+            state.pendingCount--;
+        }
+        if (state.pendingCount === 0) {
+            this.scheduleTagHydrationResolution(state);
+        }
+    }
+    getTagHydrationState(tagName) {
+        const normalizedTagName = tagName.toLowerCase();
+        let state = this.tagHydrationStates.get(normalizedTagName);
+        if (state === void 0) {
+            state = this.createTagHydrationState();
+            this.tagHydrationStates.set(normalizedTagName, state);
+        }
+        return state;
+    }
+    createTagHydrationState() {
+        let resolve;
+        const promise = new Promise(settle => {
+            resolve = settle;
+        });
+        return {
+            promise,
+            pendingCount: 0,
+            resolve,
+            resolveTimer: null,
+            resolved: false,
+        };
+    }
+    prepareTagHydrationState(state) {
+        let resolve;
+        state.promise = new Promise(settle => {
+            resolve = settle;
+        });
+        state.resolve = resolve;
+        state.resolved = false;
+    }
+    resolveTagHydrationState(state) {
+        if (state.resolved) {
+            return;
+        }
+        if (state.resolveTimer !== null) {
+            clearTimeout(state.resolveTimer);
+            state.resolveTimer = null;
+        }
+        state.resolved = true;
+        state.resolve();
+    }
+    scheduleTagHydrationResolution(state) {
+        if (state.resolveTimer !== null) {
+            clearTimeout(state.resolveTimer);
+        }
+        state.resolveTimer = setTimeout(() => {
+            state.resolveTimer = null;
+            if (state.pendingCount === 0) {
+                this.resolveTagHydrationState(state);
+            }
+        }, 0);
+    }
+    resolveTagHydrationPromises() {
+        for (const state of this.tagHydrationStates.values()) {
+            if (state.pendingCount === 0) {
+                this.resolveTagHydrationState(state);
+            }
+        }
+    }
+    resolveHydrationPromise() {
+        const resolve = this.resolveWhenHydrated;
+        this.resolveWhenHydrated = null;
+        resolve === null || resolve === void 0 ? void 0 : resolve();
+        this.resolveTagHydrationPromises();
+    }
+}

package/dist/esm/components/hydration.js

@@ -0,0 +1,187 @@
+import { Message } from "../interfaces.js";
+import { FAST } from "../platform.js";
+/**
+ * Data-free sequential hydration markers.
+ *
+ * All markers use the `fe:` prefix to namespace them to FAST Element. The closing
+ * marker uses `/` following HTML/XML convention. Markers carry zero
+ * embedded data — the hydration walker derives factory-to-node mappings
+ * by maintaining a sequential pointer through the factories array.
+ *
+ * Content binding markers bracket text/template content:
+ *   <!--fe:b--> ...content... <!--fe:/b-->
+ *
+ * Repeat item markers bracket each repeated item:
+ *   <!--fe:r--> ...item... <!--fe:/r-->
+ *
+ * Element boundary markers demarcate nested custom elements:
+ *   <!--fe:e--> ...shadow content... <!--fe:/e-->
+ *
+ * Attribute bindings use a single `data-fe` attribute whose value is
+ * the count of attribute binding factories targeting the element:
+ *   <div data-fe="3"> (3 attribute bindings)
+ *
+ * WebUI versions that predate the data-free marker format still emit indexed
+ * markers. The parser below accepts those legacy markers so existing WebUI SSR
+ * output can hydrate against the newer FAST runtime.
+ */
+const legacyBindingStartMarker = /fe-b\$\$start\$\$(\d+)\$\$(.+)\$\$fe-b/;
+const legacyBindingEndMarker = /fe-b\$\$end\$\$(\d+)\$\$(.+)\$\$fe-b/;
+const legacyRepeatViewStartMarker = /fe-repeat\$\$start\$\$(\d+)\$\$fe-repeat/;
+const legacyRepeatViewEndMarker = /fe-repeat\$\$end\$\$(\d+)\$\$fe-repeat/;
+const legacyElementBoundaryStartMarker = /^(?:.{0,1000})fe-eb\$\$start\$\$(.+?)\$\$fe-eb/;
+const legacyElementBoundaryEndMarker = /fe-eb\$\$end\$\$(.{0,1000})\$\$fe-eb(?:.{0,1000})$/;
+function isComment(node) {
+    return node && node.nodeType === Node.COMMENT_NODE;
+}
+/**
+ * Markup utilities to aid in template hydration.
+ * @internal
+ */
+export const HydrationMarkup = Object.freeze({
+    // Single attribute marker format (count only)
+    attributeMarkerName: "data-fe",
+    legacyAttributeMarkerName: "data-fe-b",
+    legacyCompactAttributeMarkerName: "data-fe-c",
+    // Content binding markers (no arguments)
+    contentBindingStartMarker() {
+        return "fe:b";
+    },
+    contentBindingEndMarker() {
+        return "fe:/b";
+    },
+    // Repeat item markers (no arguments)
+    repeatStartMarker() {
+        return "fe:r";
+    },
+    repeatEndMarker() {
+        return "fe:/r";
+    },
+    // Element boundary markers (no arguments)
+    elementBoundaryStartMarker() {
+        return "fe:e";
+    },
+    elementBoundaryEndMarker() {
+        return "fe:/e";
+    },
+    // Detection — simple string equality
+    isContentBindingStartMarker(data) {
+        return data === "fe:b" || legacyBindingStartMarker.test(data);
+    },
+    isContentBindingEndMarker(data) {
+        return data === "fe:/b" || legacyBindingEndMarker.test(data);
+    },
+    isRepeatViewStartMarker(data) {
+        return data === "fe:r" || legacyRepeatViewStartMarker.test(data);
+    },
+    isRepeatViewEndMarker(data) {
+        return data === "fe:/r" || legacyRepeatViewEndMarker.test(data);
+    },
+    isElementBoundaryStartMarker(node) {
+        return (isComment(node) &&
+            (node.data === "fe:e" || legacyElementBoundaryStartMarker.test(node.data)));
+    },
+    isElementBoundaryEndMarker(node) {
+        return (isComment(node) &&
+            (node.data === "fe:/e" || legacyElementBoundaryEndMarker.test(node.data)));
+    },
+    /**
+     * Returns the count of attribute bindings on the element, or null
+     * if no attribute binding marker is present.
+     *
+     * Parses the `data-fe="N"` attribute format where N is the count
+     * of attribute binding factories targeting this element.
+     */
+    parseAttributeBindingCount(node) {
+        const attr = node.getAttribute(this.attributeMarkerName);
+        if (attr === null) {
+            return null;
+        }
+        const trimmed = attr.trim();
+        if (!/^\d+$/.test(trimmed)) {
+            throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                value: attr,
+            });
+        }
+        const count = parseInt(trimmed, 10);
+        if (count < 1) {
+            throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                value: attr,
+            });
+        }
+        return count;
+    },
+    parseLegacyAttributeBindingIndices(node) {
+        const indices = [];
+        const attr = node.getAttribute(this.legacyAttributeMarkerName);
+        if (attr !== null) {
+            for (const value of attr.trim().split(/\s+/)) {
+                if (value === "") {
+                    continue;
+                }
+                const index = Number(value);
+                if (!Number.isInteger(index) || index < 0) {
+                    throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                        value: attr,
+                    });
+                }
+                indices.push(index);
+            }
+        }
+        const enumeratedPrefix = `${this.legacyAttributeMarkerName}-`;
+        const compactPrefix = `${this.legacyCompactAttributeMarkerName}-`;
+        for (const name of node.getAttributeNames()) {
+            if (name.startsWith(enumeratedPrefix)) {
+                const index = Number(name.slice(enumeratedPrefix.length));
+                if (!Number.isInteger(index) || index < 0) {
+                    throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                        value: name,
+                    });
+                }
+                indices.push(index);
+            }
+            else if (name.startsWith(compactPrefix)) {
+                const [start, count] = name
+                    .slice(compactPrefix.length)
+                    .split("-")
+                    .map(value => Number(value));
+                if (!Number.isInteger(start) ||
+                    !Number.isInteger(count) ||
+                    start < 0 ||
+                    count < 1) {
+                    throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                        value: name,
+                    });
+                }
+                for (let i = 0; i < count; i++) {
+                    indices.push(start + i);
+                }
+            }
+        }
+        return indices.length === 0 ? null : indices;
+    },
+    removeLegacyAttributeBindingMarkers(node) {
+        node.removeAttribute(this.legacyAttributeMarkerName);
+        for (const name of node.getAttributeNames()) {
+            if (name.startsWith(`${this.legacyAttributeMarkerName}-`) ||
+                name.startsWith(`${this.legacyCompactAttributeMarkerName}-`)) {
+                node.removeAttribute(name);
+            }
+        }
+    },
+    parseLegacyContentBindingStartIndex(data) {
+        return parseLegacyIntMarker(legacyBindingStartMarker, data);
+    },
+});
+function parseLegacyIntMarker(pattern, data) {
+    const match = pattern.exec(data);
+    return match === null ? null : Number(match[1]);
+}
+/**
+ * @internal
+ */
+export const Hydratable = Symbol.for("fe-hydration");
+/** @beta */
+export function isHydratable(value) {
+    return value[Hydratable] === Hydratable;
+}

package/dist/esm/components/schema.js

@@ -0,0 +1,253 @@
+// The context, in most cases the array property e.g. users
+export const fastContextMetaData = "$fast_context";
+// The list of contexts preceeding this context, the first of which should be the root property
+export const fastContextsMetaData = "$fast_parent_contexts";
+export const defsPropertyName = "$defs";
+export const refPropertyName = "$ref";
+/**
+ * Module-level registry that maps custom element names to their schema maps.
+ * Used for cross-element `$ref` resolution (e.g. nested element schemas).
+ * Each Schema instance registers itself here on construction.
+ * @public
+ */
+export const schemaRegistry = new Map();
+/**
+ * A constructed JSON schema from a template
+ * @public
+ */
+export class Schema {
+    constructor(name) {
+        this.customElementName = name;
+        this.schemaMap = new Map();
+        schemaRegistry.set(name, this.schemaMap);
+    }
+    /**
+     * Add a path to a schema
+     * @param config - The path registration configuration.
+     */
+    addPath(config) {
+        var _a, _b, _c;
+        const splitPath = this.getSplitPath(config.pathConfig.path);
+        let schema = this.schemaMap.get(config.rootPropertyName);
+        let childRef = null;
+        // Create a root level property JSON
+        if (!schema) {
+            this.addNewSchema(config.rootPropertyName);
+            schema = this.schemaMap.get(config.rootPropertyName);
+        }
+        if (config.childrenMap) {
+            childRef = this.getSchemaId(config.childrenMap.customElementName, config.childrenMap.attributeName);
+            if (splitPath.length === 1) {
+                schema.anyOf
+                    ? schema.anyOf.push({ [refPropertyName]: childRef })
+                    : (schema.anyOf = [{ [refPropertyName]: childRef }]);
+            }
+        }
+        switch (config.pathConfig.type) {
+            case "default":
+            case "access": {
+                if (splitPath.length > 1) {
+                    if (config.pathConfig.currentContext === null) {
+                        this.addPropertiesToAnObject(schema, splitPath.slice(1), config.pathConfig.currentContext, childRef);
+                    }
+                    else {
+                        if (!((_a = schema[defsPropertyName]) === null || _a === void 0 ? void 0 : _a[splitPath[0]])) {
+                            schema[defsPropertyName] = Object.assign(Object.assign({}, schema[defsPropertyName]), { [splitPath[0]]: {} });
+                        }
+                        this.addPropertiesToAContext(schema[defsPropertyName][splitPath[0]], splitPath.slice(1), config.pathConfig.currentContext, childRef);
+                    }
+                }
+                break;
+            }
+            case "repeat": {
+                this.addContext(schema, splitPath[splitPath.length - 1], // example items
+                config.pathConfig.currentContext, // example item
+                config.pathConfig.parentContext);
+                if (splitPath.length > 2) {
+                    let updatedSchema = schema;
+                    const hasParentContext = !!config.pathConfig.parentContext;
+                    if (hasParentContext) {
+                        updatedSchema = this.addPropertiesToAnObject((_b = schema[defsPropertyName]) === null || _b === void 0 ? void 0 : _b[config.pathConfig.parentContext], splitPath.slice(1, -1), config.pathConfig.parentContext, childRef);
+                    }
+                    this.addPropertiesToAnObject(updatedSchema, hasParentContext ? splitPath.slice(2) : splitPath.slice(1), config.pathConfig.currentContext, childRef, "array");
+                }
+                else if (splitPath.length > 1) {
+                    let schemaDefinition;
+                    if (config.pathConfig.parentContext) {
+                        schemaDefinition = (_c = schema === null || schema === void 0 ? void 0 : schema[defsPropertyName]) === null || _c === void 0 ? void 0 : _c[config.pathConfig.parentContext];
+                    }
+                    this.addPropertiesToAnObject(schemaDefinition !== null && schemaDefinition !== void 0 ? schemaDefinition : schema, splitPath.slice(1), config.pathConfig.currentContext, childRef, "array");
+                }
+                else {
+                    schema.type = "array";
+                    schema[refPropertyName] = this.getDefsPath(config.pathConfig.currentContext);
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * Gets the JSON schema for a property name
+     * @param rootPropertyName - the root property the JSON schema is mapped to
+     * @returns The JSON schema for the root property
+     */
+    getSchema(rootPropertyName) {
+        var _a;
+        return (_a = this.schemaMap.get(rootPropertyName)) !== null && _a !== void 0 ? _a : null;
+    }
+    /**
+     * Gets root properties
+     * @returns IterableIterator<string>
+     */
+    getRootProperties() {
+        return this.schemaMap.keys();
+    }
+    /**
+     * Get a path split into property names
+     * @param path - The dot syntax path, e.g. `a.b.c`.
+     * @returns An array of items in the path
+     */
+    getSplitPath(path) {
+        return path.split(".");
+    }
+    /**
+     * Gets the path to the $def
+     * @param context - The context name. For example, `item in items` creates the `item` context.
+     * @returns A string to use as a $ref
+     */
+    getDefsPath(context) {
+        return `#/${defsPropertyName}/${context}`;
+    }
+    /**
+     * Get the schema $id
+     * @param customElementName - The custom element name
+     * @param propertyName - The property name
+     * @returns The ID that can be used in the JSON schema as $id
+     */
+    getSchemaId(customElementName, propertyName) {
+        return `https://fast.design/schemas/${customElementName}/${propertyName}.json`;
+    }
+    /**
+     * Add a new JSON schema to the JSON schema map
+     * @param propertyName - The name of the property to assign this JSON schema to.
+     */
+    addNewSchema(propertyName) {
+        this.schemaMap.set(propertyName, {
+            $schema: "https://json-schema.org/draft/2019-09/schema",
+            $id: this.getSchemaId(this.customElementName, propertyName),
+            [defsPropertyName]: {},
+        });
+    }
+    /**
+     * Add properties to a context
+     * @param schema - The schema to add the properties to.
+     * @param splitPath - The path split into property/context names.
+     * @param context - The path context.
+     */
+    addPropertiesToAContext(schema, splitPath, context, childRef) {
+        schema.type = "object";
+        if (schema.properties && !schema.properties[splitPath[0]]) {
+            schema.properties[splitPath[0]] = {};
+        }
+        else if (!schema.properties) {
+            schema.properties = {
+                [splitPath[0]]: {},
+            };
+        }
+        if (splitPath.length > 1) {
+            this.addPropertiesToAnObject(schema.properties[splitPath[0]], splitPath.slice(1), context, childRef);
+        }
+        else if (childRef) {
+            if (schema.properties[splitPath[0]].anyOf) {
+                schema.properties[splitPath[0]].anyOf.push({
+                    [refPropertyName]: childRef,
+                });
+            }
+            else {
+                schema.properties[splitPath[0]].anyOf = [{ [refPropertyName]: childRef }];
+            }
+        }
+    }
+    /**
+     * Add properties to an object
+     * @param schema - The schema to add the properties to.
+     * @param splitPath - The path split into property/context names.
+     * @param context - The path context.
+     * @param type - The data type (see JSON schema for details).
+     */
+    addPropertiesToAnObject(schema, splitPath, context, childRef, type = "object") {
+        schema.type = "object";
+        if (schema.properties && !schema.properties[splitPath[0]]) {
+            schema.properties[splitPath[0]] = {};
+        }
+        else if (!schema.properties) {
+            schema.properties = {
+                [splitPath[0]]: {},
+            };
+        }
+        if (type === "object" && splitPath.length > 1) {
+            return this.addPropertiesToAnObject(schema.properties[splitPath[0]], splitPath.slice(1), context, childRef, type);
+        }
+        else if (type === "array") {
+            if (splitPath.length > 1) {
+                return this.addPropertiesToAnObject(schema.properties[splitPath[0]], splitPath.slice(1), context, childRef, type);
+            }
+            else {
+                return this.addArrayToAnObject(schema.properties[splitPath[0]], context);
+            }
+        }
+        if (schema.properties[splitPath[0]].anyOf && childRef) {
+            schema.properties[splitPath[0]].anyOf.push({ [refPropertyName]: childRef });
+        }
+        else if (childRef) {
+            schema.properties[splitPath[0]].anyOf = [{ [refPropertyName]: childRef }];
+        }
+        return schema.properties[splitPath[0]];
+    }
+    /**
+     * Add an array to an object property
+     * @param schema - The schema to add the properties to.
+     * @param context - The name of the context.
+     */
+    addArrayToAnObject(schema, context) {
+        schema.type = "array";
+        schema.items = {
+            [refPropertyName]: this.getDefsPath(context),
+        };
+        return schema.items;
+    }
+    /**
+     * Add a context to the $defs property
+     * @param schema - The schema to use.
+     * @param propertyName - The name of the property the context belongs to.
+     * @param currentContext - The current context.
+     * @param parentContext - The parent context.
+     * @returns
+     */
+    addContext(schema, propertyName, // e.g items
+    currentContext, // e.g. item
+    parentContext) {
+        if (schema[defsPropertyName][currentContext]) {
+            return;
+        }
+        schema[defsPropertyName][currentContext] = {
+            [fastContextMetaData]: propertyName,
+            [fastContextsMetaData]: this.getParentContexts(schema, parentContext),
+        };
+    }
+    /**
+     * Get parent contexts
+     * @param schema - The schema to use.
+     * @param parentContext - The parent context.
+     * @param contexts - A list of parent contexts.
+     * @returns
+     */
+    getParentContexts(schema, parentContext, contexts = []) {
+        var _a;
+        if (parentContext === null) {
+            return [null, ...contexts];
+        }
+        const parentParentContext = (_a = schema === null || schema === void 0 ? void 0 : schema[defsPropertyName]) === null || _a === void 0 ? void 0 : _a[parentContext][fastContextsMetaData];
+        return this.getParentContexts(schema, parentParentContext[parentParentContext.length - 1], [parentContext, ...contexts]);
+    }
+}