@microsoft/fast-element 2.10.4 → 3.0.0-rc.1

package/dist/esm/components/hydration.js

@@ -1,27 +1,26 @@
+import { Message } from "../interfaces.js";
 import { FAST } from "../platform.js";
 /**
- * Regex patterns for parsing hydration markers embedded as HTML comments by the SSR renderer.
- * Each marker type encodes factory indices so the client can map markers back to ViewBehaviorFactories.
+ * 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$$start$$<factoryIndex>$$<uniqueId>$$fe-b -->
- *   ...content...
- *   <!-- fe-b$$end$$<factoryIndex>$$<uniqueId>$$fe-b -->
+ *   <!--fe:b--> ...content... <!--fe:/b-->
+ *
+ * Repeat item markers bracket each repeated item:
+ *   <!--fe:r--> ...item... <!--fe:/r-->
  *
- * Repeat markers bracket each repeated item:
- *   <!-- fe-repeat$$start$$<itemIndex>$$fe-repeat -->
- *   <!-- fe-repeat$$end$$<itemIndex>$$fe-repeat -->
+ * Element boundary markers demarcate nested custom elements:
+ *   <!--fe:e--> ...shadow content... <!--fe:/e-->
  *
- * Element boundary markers demarcate nested custom elements so parent walkers can skip them:
- *   <!-- fe-eb$$start$$<elementId>$$fe-eb -->
- *   <!-- fe-eb$$end$$<elementId>$$fe-eb -->
+ * 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)
  */
-const bindingStartMarker = /fe-b\$\$start\$\$(\d+)\$\$(.+)\$\$fe-b/;
-const bindingEndMarker = /fe-b\$\$end\$\$(\d+)\$\$(.+)\$\$fe-b/;
-const repeatViewStartMarker = /fe-repeat\$\$start\$\$(\d+)\$\$fe-repeat/;
-const repeatViewEndMarker = /fe-repeat\$\$end\$\$(\d+)\$\$fe-repeat/;
-const elementBoundaryStartMarker = /^(?:.{0,1000})fe-eb\$\$start\$\$(.+?)\$\$fe-eb/;
-const elementBoundaryEndMarker = /fe-eb\$\$end\$\$(.{0,1000})\$\$fe-eb(?:.{0,1000})$/;
 function isComment(node) {
     return node && node.nodeType === Node.COMMENT_NODE;
 }
@@ -30,151 +29,75 @@ function isComment(node) {
  * @internal
  */
 export const HydrationMarkup = Object.freeze({
-    attributeMarkerName: "data-fe-b",
-    compactAttributeMarkerName: "data-fe-c",
-    attributeBindingSeparator: " ",
-    contentBindingStartMarker(index, uniqueId) {
-        return `fe-b$$start$$${index}$$${uniqueId}$$fe-b`;
+    // Single attribute marker format (count only)
+    attributeMarkerName: "data-fe",
+    // Content binding markers (no arguments)
+    contentBindingStartMarker() {
+        return "fe:b";
+    },
+    contentBindingEndMarker() {
+        return "fe:/b";
+    },
+    // Repeat item markers (no arguments)
+    repeatStartMarker() {
+        return "fe:r";
     },
-    contentBindingEndMarker(index, uniqueId) {
-        return `fe-b$$end$$${index}$$${uniqueId}$$fe-b`;
+    repeatEndMarker() {
+        return "fe:/r";
     },
-    repeatStartMarker(index) {
-        return `fe-repeat$$start$$${index}$$fe-repeat`;
+    // Element boundary markers (no arguments)
+    elementBoundaryStartMarker() {
+        return "fe:e";
     },
-    repeatEndMarker(index) {
-        return `fe-repeat$$end$$${index}$$fe-repeat`;
+    elementBoundaryEndMarker() {
+        return "fe:/e";
     },
-    isContentBindingStartMarker(content) {
-        return bindingStartMarker.test(content);
+    // Detection — simple string equality
+    isContentBindingStartMarker(data) {
+        return data === "fe:b";
     },
-    isContentBindingEndMarker(content) {
-        return bindingEndMarker.test(content);
+    isContentBindingEndMarker(data) {
+        return data === "fe:/b";
     },
-    isRepeatViewStartMarker(content) {
-        return repeatViewStartMarker.test(content);
+    isRepeatViewStartMarker(data) {
+        return data === "fe:r";
     },
-    isRepeatViewEndMarker(content) {
-        return repeatViewEndMarker.test(content);
+    isRepeatViewEndMarker(data) {
+        return data === "fe:/r";
     },
     isElementBoundaryStartMarker(node) {
-        return isComment(node) && elementBoundaryStartMarker.test(node.data.trim());
+        return isComment(node) && node.data === "fe:e";
     },
     isElementBoundaryEndMarker(node) {
-        return isComment(node) && elementBoundaryEndMarker.test(node.data);
+        return isComment(node) && node.data === "fe:/e";
     },
     /**
-     * Returns the indexes of the ViewBehaviorFactories affecting
-     * attributes for the element, or null if no factories were found.
+     * Returns the count of attribute bindings on the element, or null
+     * if no attribute binding marker is present.
      *
-     * This method parses the space-separated format: `data-fe-b="0 1 2"`.
+     * Parses the `data-fe="N"` attribute format where N is the count
+     * of attribute binding factories targeting this element.
      */
-    parseAttributeBinding(node) {
+    parseAttributeBindingCount(node) {
         const attr = node.getAttribute(this.attributeMarkerName);
-        return attr === null
-            ? attr
-            : attr.split(this.attributeBindingSeparator).map(i => parseInt(i));
-    },
-    /**
-     * Returns the indexes of the ViewBehaviorFactories affecting
-     * attributes for the element, or null if no factories were found.
-     *
-     * This method parses the enumerated format: `data-fe-b-0`, `data-fe-b-1`, `data-fe-b-2`.
-     * This is an alternative format that uses separate attributes for each binding index.
-     */
-    parseEnumeratedAttributeBinding(node) {
-        const attrs = [];
-        const prefixLength = this.attributeMarkerName.length + 1;
-        const prefix = `${this.attributeMarkerName}-`;
-        for (const attr of node.getAttributeNames()) {
-            if (attr.startsWith(prefix)) {
-                const count = Number(attr.slice(prefixLength));
-                if (!Number.isNaN(count)) {
-                    attrs.push(count);
-                }
-                else {
-                    throw FAST.error(1601 /* invalidAttributeMarkerName */, {
-                        name: attr,
-                        expectedFormat: `${prefix}<number>`,
-                    });
-                }
-            }
-        }
-        return attrs.length === 0 ? null : attrs;
-    },
-    /**
-     * Returns the indexes of the ViewBehaviorFactories affecting
-     * attributes for the element, or null if no factories were found.
-     *
-     * This method parses the compact format: `data-fe-c-{index}-{count}`.
-     */
-    parseCompactAttributeBinding(node) {
-        const prefix = `${this.compactAttributeMarkerName}-`;
-        const attrName = node.getAttributeNames().find(name => name.startsWith(prefix));
-        if (!attrName) {
+        if (attr === null) {
             return null;
         }
-        const suffix = attrName.slice(prefix.length);
-        const parts = suffix.split("-");
-        const startIndex = parseInt(parts[0], 10);
-        const count = parseInt(parts[1], 10);
-        if (parts.length !== 2 ||
-            Number.isNaN(startIndex) ||
-            Number.isNaN(count) ||
-            startIndex < 0 ||
-            count < 1) {
-            throw FAST.error(1604 /* invalidCompactAttributeMarkerName */, {
-                name: attrName,
-                expectedFormat: `${this.compactAttributeMarkerName}-{index}-{count}`,
+        const trimmed = attr.trim();
+        if (!/^\d+$/.test(trimmed)) {
+            throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                value: attr,
             });
         }
-        const indexes = [];
-        for (let i = 0; i < count; i++) {
-            indexes.push(startIndex + i);
+        const count = parseInt(trimmed, 10);
+        if (count < 1) {
+            throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                value: attr,
+            });
         }
-        return indexes;
-    },
-    /**
-     * Parses the ViewBehaviorFactory index from string data. Returns
-     * the binding index or null if the index cannot be retrieved.
-     */
-    parseContentBindingStartMarker(content) {
-        return parseIndexAndIdMarker(bindingStartMarker, content);
-    },
-    parseContentBindingEndMarker(content) {
-        return parseIndexAndIdMarker(bindingEndMarker, content);
-    },
-    /**
-     * Parses the index of a repeat directive from a content string.
-     */
-    parseRepeatStartMarker(content) {
-        return parseIntMarker(repeatViewStartMarker, content);
-    },
-    parseRepeatEndMarker(content) {
-        return parseIntMarker(repeatViewEndMarker, content);
-    },
-    /**
-     * Parses element Id from element boundary markers
-     */
-    parseElementBoundaryStartMarker(content) {
-        return parseStringMarker(elementBoundaryStartMarker, content.trim());
-    },
-    parseElementBoundaryEndMarker(content) {
-        return parseStringMarker(elementBoundaryEndMarker, content);
+        return count;
     },
 });
-function parseIntMarker(regex, content) {
-    const match = regex.exec(content);
-    return match === null ? match : parseInt(match[1]);
-}
-function parseStringMarker(regex, content) {
-    const match = regex.exec(content);
-    return match === null ? match : match[1];
-}
-function parseIndexAndIdMarker(regex, content) {
-    const match = regex.exec(content);
-    return match === null ? match : [parseInt(match[1]), match[2]];
-}
 /**
  * @internal
  */
@@ -183,8 +106,3 @@ export const Hydratable = Symbol.for("fe-hydration");
 export function isHydratable(value) {
     return value[Hydratable] === Hydratable;
 }
-/**
- * The attribute used to defer hydration of an element.
- * @beta
- */
-export const deferHydrationAttribute = "defer-hydration";

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]);
+    }
+}

package/dist/esm/context.js

@@ -112,9 +112,9 @@ export const Context = Object.freeze({
     },
     /**
      * Enables an event target to provide a context value.
-     * @param target The target to provide the context value for.
-     * @param context The context to provide the value for.
-     * @param value The value to provide for the context.
+     * @param target - The target to provide the context value for.
+     * @param context - The context to provide the value for.
+     * @param value - The value to provide for the context.
      */
     provide(target, context, value) {
         Context.handle(target, (event) => {
@@ -146,9 +146,9 @@ export const Context = Object.freeze({
     /**
      * Defines a getter-only property on the target that will return the context
      * value for the target.
-     * @param target The target to define the property on.
-     * @param propertyName The name of the property to define.
-     * @param context The context that will be used to retrieve the property value.
+     * @param target - The target to define the property on.
+     * @param propertyName - The name of the property to define.
+     * @param context - The context that will be used to retrieve the property value.
      * @remarks
      * Uses the default request strategy to locate the context and will return the
      * initialValue if the context isn't handled.

package/dist/esm/css.js

@@ -0,0 +1,3 @@
+export { css } from "./styles/css.js";
+export { CSSDirective, cssDirective, } from "./styles/css-directive.js";
+export { ElementStyles, } from "./styles/element-styles.js";

package/dist/esm/debug.js

@@ -1,13 +1,5 @@
-if (globalThis.FAST === void 0) {
-    Reflect.defineProperty(globalThis, "FAST", {
-        value: Object.create(null),
-        configurable: false,
-        enumerable: false,
-        writable: false,
-    });
-}
-const FAST = globalThis.FAST;
-const debugMessages = {
+import { FAST, getDebugMessageLookup } from "./platform.js";
+const baseDebugMessages = {
     [1101 /* needsArrayObservation */]: "Must call ArrayObserver.enable() before observing arrays.",
     [1201 /* onlySetDOMPolicyOnce */]: "The DOM Policy can only be set once.",
     [1202 /* bindingInnerHTMLRequiresTrustedTypes */]: "To bind innerHTML, you must use a TrustedTypesPolicy.",
@@ -18,6 +10,7 @@ const debugMessages = {
     [1207 /* onlySetTemplatePolicyOnce */]: "The DOM Policy for an HTML template can only be set once.",
     [1208 /* cannotSetTemplatePolicyAfterCompilation */]: "The DOM Policy cannot be set after a template is compiled.",
     [1209 /* blockedByDOMPolicy */]: "'${aspectName}' on '${tagName}' is blocked by the current DOMPolicy.",
+    [1210 /* invalidHydrationAttributeMarker */]: "Invalid data-fe attribute value '${value}'. Expected a positive integer.",
     [1401 /* missingElementDefinition */]: "Missing FASTElement definition.",
     [1501 /* noRegistrationForContext */]: "No registration for Context/Interface '${name}'.",
     [1502 /* noFactoryForResolver */]: "Dependency injection resolver for '${key}' returned a null factory.",
@@ -52,19 +45,26 @@ function formatMessage(message, values) {
     })
         .join("");
 }
-Object.assign(FAST, {
-    addMessages(messages) {
-        Object.assign(debugMessages, messages);
-    },
-    warn(code, values = noValues) {
-        var _a;
-        const message = (_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Warning";
-        console.warn(formatMessage(message, values));
-    },
-    error(code, values = noValues) {
-        var _a;
-        const message = (_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Error";
-        return new Error(formatMessage(message, values));
-    },
-});
-export {};
+/**
+ * Enables human-readable FAST debug messages.
+ * @public
+ */
+export function enableDebug() {
+    const debugMessages = getDebugMessageLookup();
+    Object.assign(debugMessages, baseDebugMessages);
+    Object.assign(FAST, {
+        addMessages(messages) {
+            Object.assign(debugMessages, messages);
+        },
+        warn(code, values = noValues) {
+            var _a;
+            const message = (_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Warning";
+            console.warn(formatMessage(message, values));
+        },
+        error(code, values = noValues) {
+            var _a;
+            const message = (_a = debugMessages[code]) !== null && _a !== void 0 ? _a : "Unknown Error";
+            return new Error(formatMessage(message, values));
+        },
+    });
+}