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

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,8 @@ 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.",
+    [1211 /* duplicateRenderInstruction */]: "Replacing existing RenderInstruction for '${type}' with name '${name}'.",
     [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 +46,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));
+        },
+    });
+}

package/dist/esm/declarative/attribute-map.js

@@ -0,0 +1,122 @@
+import { AttributeDefinition } from "../components/attributes.js";
+import { setDefinitionSchemaTransform } from "../components/definition-schema-transforms.js";
+import { hasFASTElementTemplateResolver, trackLateAttributeDefinition, } from "../components/fast-definitions.js";
+import { Observable } from "../observation/observable.js";
+export { Schema, schemaRegistry, } from "../components/schema.js";
+const attributeMapSchemaTransformKey = "attribute-map";
+const attributeMapSchemaTransformPriority = 0;
+function defineAttributeMap(definition, schema, config) {
+    new AttributeMap(definition.type.prototype, schema, definition, config).defineProperties();
+}
+/**
+ * Creates a FAST element extension that enables schema-driven attribute mapping
+ * for the resolved definition. When called without arguments, uses the default
+ * attribute-mapping behavior. The extension uses `definition.schema` immediately
+ * for manual schemas, or the schema generated/augmented by `declarativeTemplate()`.
+ * @public
+ */
+export function attributeMap(config = {}) {
+    return definition => {
+        const hasTemplateResolver = hasFASTElementTemplateResolver(definition);
+        if (definition.schema && !hasTemplateResolver) {
+            defineAttributeMap(definition, definition.schema, config);
+            return;
+        }
+        if (!hasTemplateResolver) {
+            throw new Error("attributeMap requires a schema. Provide one via FASTElement definition or use declarativeTemplate().");
+        }
+        setDefinitionSchemaTransform(definition, attributeMapSchemaTransformKey, ({ definition, schema }) => defineAttributeMap(definition, schema, config), attributeMapSchemaTransformPriority);
+    };
+}
+/**
+ * Converts a camelCase string to kebab-case.
+ *
+ * @example camelToKebab("fooBar")       // "foo-bar"
+ * @example camelToKebab("myCustomProp") // "my-custom-prop"
+ * @example camelToKebab("label")        // "label"
+ */
+function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
+}
+/**
+ * AttributeMap provides functionality for detecting simple (leaf) properties in
+ * a generated JSON schema and defining them as attr properties on a class prototype.
+ *
+ * A property is a candidate for attr when its schema entry has no nested `properties`,
+ * no `type`, and no `anyOf` — for example, a plain `foo` binding.
+ *
+ * When `attribute-name-strategy` is `"camelCase"` (the default), the binding key is treated as a
+ * camelCase property name and the HTML attribute name is derived by converting it to
+ * kebab-case (e.g. property `fooBar` → attribute `foo-bar`). This matches the
+ * build-time `attribute-name-strategy` option in `@microsoft/fast-build`.
+ *
+ * When `attribute-name-strategy` is `"none"`, the binding key is used
+ * as both the attribute name and property name — no normalization is applied.
+ *
+ * Properties already decorated with `attr` or `observable` on the class are left
+ * untouched.
+ * @public
+ */
+export class AttributeMap {
+    constructor(classPrototype, schema, definition, config) {
+        this.classPrototype = classPrototype;
+        this.schema = schema;
+        this.definition = definition;
+        this.config = config;
+    }
+    defineProperties() {
+        var _a;
+        var _b;
+        const propertyNames = this.schema.getRootProperties();
+        const existingAccessorNames = new Set(Observable.getAccessors(this.classPrototype).map(a => a.name));
+        const strategy = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a["attribute-name-strategy"]) !== null && _b !== void 0 ? _b : "camelCase";
+        for (const propertyName of propertyNames) {
+            const propertySchema = this.schema.getSchema(propertyName);
+            // Only create @attr for leaf properties:
+            // - no nested properties (not a dot-syntax path)
+            // - no type (not an explicitly typed value like an array)
+            // - no anyOf (not a child element reference)
+            if (!propertySchema ||
+                propertySchema.properties ||
+                propertySchema.type ||
+                propertySchema.anyOf) {
+                continue;
+            }
+            // Skip if the property already has an accessor (from @attr or @observable)
+            if (existingAccessorNames.has(propertyName)) {
+                continue;
+            }
+            // Derive the HTML attribute name from the property name.
+            // With "camelCase" strategy, convert camelCase to kebab-case
+            // (e.g. fooBar → foo-bar). With "none", use the property name as-is.
+            const attributeName = strategy === "camelCase" ? camelToKebab(propertyName) : propertyName;
+            const attrDef = new AttributeDefinition(this.classPrototype.constructor, propertyName, attributeName);
+            Observable.defineProperty(this.classPrototype, attrDef);
+            // Mutate the existing observedAttributes array on the class.
+            // FAST's FASTElementDefinition sets observedAttributes via
+            // Reflect.defineProperty with a concrete array value (non-configurable,
+            // non-writable), so the descriptor cannot be replaced. However, the
+            // array itself is mutable, and pushing into it works because
+            // registry.define() — which causes the browser to snapshot
+            // observedAttributes — is called AFTER this method runs.
+            const existingObservedAttrs = this.classPrototype.constructor.observedAttributes;
+            if (Array.isArray(existingObservedAttrs) &&
+                !existingObservedAttrs.includes(attributeName)) {
+                existingObservedAttrs.push(attributeName);
+            }
+            if (this.definition) {
+                this.definition.attributeLookup[attributeName] = attrDef;
+                this.definition.propertyLookup[propertyName] = attrDef;
+                const attrs = this.definition.attributes;
+                if (Array.isArray(attrs) &&
+                    !attrs.some((existing) => existing.name === attrDef.name ||
+                        existing.attribute === attrDef.attribute)) {
+                    attrs.push(attrDef);
+                }
+                if (this.definition.isDefined) {
+                    trackLateAttributeDefinition(this.definition, attrDef);
+                }
+            }
+        }
+    }
+}

package/dist/esm/declarative/debug.js

@@ -0,0 +1,4 @@
+export const debugMessages = {
+    [2000 /* noTemplateProvided */]: "The first child of the <f-template> must be a <template>, this is missing from ${name}.",
+    [2001 /* moreThanOneTemplateProvided */]: "There can only be one <template> inside the <f-template>; remove any extra <template> elements and keep exactly one for ${name}.",
+};

package/dist/esm/declarative/index.js

@@ -0,0 +1,4 @@
+export { Schema, schemaRegistry, } from "../components/schema.js";
+export { DOMPolicy, } from "../dom-policy.js";
+export { declarativeTemplate } from "./template.js";
+export { TemplateParser } from "./template-parser.js";

package/dist/esm/declarative/interfaces.js

@@ -0,0 +1,9 @@
+/**
+ * Warning and error messages.
+ * @internal
+ */
+export var Message;
+(function (Message) {
+    Message[Message["noTemplateProvided"] = 2000] = "noTemplateProvided";
+    Message[Message["moreThanOneTemplateProvided"] = 2001] = "moreThanOneTemplateProvided";
+})(Message || (Message = {}));