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

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

@@ -0,0 +1,216 @@
+import { setDefinitionSchemaTransform } from "../components/definition-schema-transforms.js";
+import { hasFASTElementTemplateResolver, } from "../components/fast-definitions.js";
+import { Observable } from "../observation/observable.js";
+import { assignObservables, deepMerge } from "./observer-map-utilities.js";
+export { Schema, schemaRegistry, } from "../components/schema.js";
+const observerMapSchemaTransformKey = "observer-map";
+const observerMapSchemaTransformPriority = 1;
+function defineObserverMap(definition, schema, config) {
+    new ObserverMap(definition.type.prototype, schema, config).defineProperties();
+}
+/**
+ * Creates a FAST element extension that enables schema-driven observer mapping
+ * for the resolved definition. When called without arguments, observes every
+ * discovered root property. The extension uses `config.schema`,
+ * `definition.schema`, or the schema generated by `declarativeTemplate()`.
+ * @public
+ */
+export function observerMap(config = {}) {
+    return definition => {
+        var _a;
+        const schema = (_a = config.schema) !== null && _a !== void 0 ? _a : definition.schema;
+        const hasTemplateResolver = hasFASTElementTemplateResolver(definition);
+        if (schema && !hasTemplateResolver) {
+            defineObserverMap(definition, schema, config);
+            return;
+        }
+        if (!hasTemplateResolver) {
+            throw new Error("observerMap requires a schema. Pass observerMap({ schema }), provide a schema on the FASTElement definition, or use declarativeTemplate().");
+        }
+        setDefinitionSchemaTransform(definition, observerMapSchemaTransformKey, ({ definition, schema }) => {
+            var _a;
+            defineObserverMap(definition, (_a = config.schema) !== null && _a !== void 0 ? _a : schema, config);
+        }, observerMapSchemaTransformPriority);
+    };
+}
+/**
+ * Determines whether a config entry (or any of its descendants) enables observation.
+ * Used to decide whether a root property needs an observable accessor and change handler.
+ */
+function hasObservedPath(entry) {
+    if (typeof entry === "boolean") {
+        return entry;
+    }
+    // ObserverMapPathNode
+    if (entry.$observe === true) {
+        return true;
+    }
+    for (const key of Object.keys(entry)) {
+        if (key === "$observe") {
+            continue;
+        }
+        const child = entry[key];
+        if (child !== undefined && hasObservedPath(child)) {
+            return true;
+        }
+    }
+    // A node with no explicit $observe and no observed children:
+    // at the root level the default $observe is true, so a node like `{ }` (no children)
+    // is observed. But a node with `$observe: false` and no observed children is not.
+    return entry.$observe !== false;
+}
+/**
+ * Stamps `$observe` flags onto schema nodes based on the config tree.
+ * After this one-time pass the proxy system can check `schema.$observe`
+ * instead of needing a separate config parameter threaded through every call.
+ *
+ * @param schema - A schema node (must have `properties` to recurse)
+ * @param entry  - The corresponding config path entry
+ * @param inherited - The inherited `$observe` value from the parent
+ */
+function applyConfigToSchema(schema, entry, inherited = true) {
+    var _a;
+    if (entry === false) {
+        stampObserveFalse(schema);
+        return;
+    }
+    if (entry === true) {
+        // Explicitly observed — no stamp needed (default is observed)
+        return;
+    }
+    // ObserverMapPathNode
+    const nodeObserve = (_a = entry.$observe) !== null && _a !== void 0 ? _a : inherited;
+    if (!nodeObserve) {
+        schema.$observe = false;
+    }
+    if (!(schema === null || schema === void 0 ? void 0 : schema.properties)) {
+        return;
+    }
+    for (const key of Object.keys(entry)) {
+        if (key === "$observe") {
+            continue;
+        }
+        const childEntry = entry[key];
+        const childSchema = schema.properties[key];
+        // Paths in config but not in schema are silently ignored
+        if (childEntry !== undefined && childSchema) {
+            applyConfigToSchema(childSchema, childEntry, nodeObserve);
+        }
+    }
+    // For properties in the schema that are NOT listed in the config,
+    // they inherit the parent's $observe value
+    if (!nodeObserve) {
+        for (const key of Object.keys(schema.properties)) {
+            if (!(key in entry) && schema.properties[key]) {
+                stampObserveFalse(schema.properties[key]);
+            }
+        }
+    }
+}
+/**
+ * Recursively stamps `$observe: false` on a schema node and all its descendants.
+ */
+function stampObserveFalse(schema) {
+    if (!schema) {
+        return;
+    }
+    schema.$observe = false;
+    if (schema.properties) {
+        for (const key of Object.keys(schema.properties)) {
+            stampObserveFalse(schema.properties[key]);
+        }
+    }
+}
+/**
+ * ObserverMap provides functionality for caching binding paths, extracting root properties,
+ * and defining observable properties on class prototypes
+ * @public
+ */
+export class ObserverMap {
+    constructor(classPrototype, schema, config) {
+        /**
+         * Creates a property change handler function for observable properties
+         * This handler is called when an observable property transitions from undefined to a defined value
+         * @param propertyName - The name of the property for which to create the change handler
+         * @param existingChangedMethod - Optional existing changed method to call after the instance resolver logic
+         * @returns A function that handles property changes and sets up proxies for object values
+         */
+        this.defineChanged = (propertyName, existingChangedMethod) => {
+            const getAndAssignObservablesAlias = this.getAndAssignObservables;
+            const schema = this.schema;
+            function instanceResolverChanged(prev, next) {
+                const isObjectAssignment = next !== null && typeof next === "object";
+                const isManagedArray = Array.isArray(next) && (next === null || next === void 0 ? void 0 : next.$fastController);
+                const shouldAssignProxy = isObjectAssignment && !(next === null || next === void 0 ? void 0 : next.$isProxy) && !isManagedArray;
+                const hasExistingProxy = prev !== null && typeof prev === "object" && prev.$isProxy;
+                if (shouldAssignProxy) {
+                    if (hasExistingProxy) {
+                        deepMerge(prev, next);
+                        this[`_${propertyName}`] = prev;
+                    }
+                    else {
+                        this[propertyName] = getAndAssignObservablesAlias(this, propertyName, next, schema);
+                    }
+                }
+                else if (!isObjectAssignment) {
+                    this[propertyName] = next;
+                }
+                existingChangedMethod === null || existingChangedMethod === void 0 ? void 0 : existingChangedMethod.call(this, prev, next);
+            }
+            return instanceResolverChanged;
+        };
+        this.classPrototype = classPrototype;
+        this.schema = schema;
+        this.config = config;
+    }
+    defineProperties() {
+        var _a;
+        const propertyNames = this.schema.getRootProperties();
+        const existingAccessors = Observable.getAccessors(this.classPrototype);
+        const configProperties = (_a = this.config) === null || _a === void 0 ? void 0 : _a.properties;
+        for (const propertyName of propertyNames) {
+            // When `properties` is present, skip root properties not listed in the config
+            if (configProperties && !(propertyName in configProperties)) {
+                continue;
+            }
+            // Resolve the config entry for this root property
+            const configEntry = configProperties === null || configProperties === void 0 ? void 0 : configProperties[propertyName];
+            // Skip root properties explicitly set to `false` with no observed descendants
+            if (configEntry === false) {
+                continue;
+            }
+            // Skip ObserverMapPathNode entries with no observed descendants
+            if (typeof configEntry === "object" &&
+                configEntry !== null &&
+                !hasObservedPath(configEntry)) {
+                continue;
+            }
+            // Stamp $observe flags onto the schema so the proxy system
+            // can check schema nodes directly without a separate config tree
+            const rootSchema = this.schema.getSchema(propertyName);
+            if (configEntry && rootSchema) {
+                applyConfigToSchema(rootSchema, configEntry);
+            }
+            // Skip if property already has an accessor (from `@attr` or `@observable` decorator)
+            if (!existingAccessors.some(accessor => accessor.name === propertyName)) {
+                Observable.defineProperty(this.classPrototype, propertyName);
+            }
+            const changedMethodName = `${propertyName}Changed`;
+            const existingChangedMethod = this.classPrototype[changedMethodName];
+            this.classPrototype[changedMethodName] = this.defineChanged(propertyName, existingChangedMethod);
+        }
+    }
+    /**
+     * Creates a proxy for an object that intercepts property mutations and triggers Observable notifications
+     * @param target - The target instance that owns the root property
+     * @param rootProperty - The name of the root property for notification purposes
+     * @param object - The object to wrap with a proxy
+     * @param schema - The schema for the element
+     * @returns A proxy that triggers notifications on property mutations
+     */
+    getAndAssignObservables(target, rootProperty, object, schema) {
+        let proxiedObject = object;
+        proxiedObject = assignObservables(schema.getSchema(rootProperty), schema.getSchema(rootProperty), proxiedObject, target, rootProperty);
+        return proxiedObject;
+    }
+}

package/dist/esm/declarative/runtime.js

@@ -0,0 +1,14 @@
+import { FAST } from "../platform.js";
+import { debugMessages } from "./debug.js";
+let declarativeRuntimeInstalled = false;
+/**
+ * Installs the declarative runtime debug messages.
+ * @internal
+ */
+export function ensureDeclarativeRuntime() {
+    if (declarativeRuntimeInstalled) {
+        return;
+    }
+    FAST.addMessages(debugMessages);
+    declarativeRuntimeInstalled = true;
+}

package/dist/esm/declarative/syntax.js

@@ -0,0 +1,36 @@
+const defaultSyntax = {
+    attributeDirectivePrefix: "f-",
+    clientSideCloseExpression: "}",
+    clientSideOpenExpression: "{",
+    closeExpression: "}}",
+    eventArgAccessor: "$e",
+    executionContextAccessor: "$c",
+    openExpression: "{{",
+    unescapedCloseExpression: "}}}",
+    unescapedOpenExpression: "{{{",
+    repeatDirectiveClose: "</f-repeat>",
+    repeatDirectiveOpen: "<f-repeat",
+    whenDirectiveClose: "</f-when>",
+    whenDirectiveOpen: "<f-when",
+};
+export const attributeDirectivePrefix = defaultSyntax.attributeDirectivePrefix;
+export const clientSideCloseExpression = defaultSyntax.clientSideCloseExpression;
+export const clientSideOpenExpression = defaultSyntax.clientSideOpenExpression;
+export const closeExpression = defaultSyntax.closeExpression;
+/**
+ * Event argument accessor for declarative event bindings.
+ * @public
+ */
+export const eventArgAccessor = defaultSyntax.eventArgAccessor;
+/**
+ * Execution context accessor for declarative event bindings.
+ * @public
+ */
+export const executionContextAccessor = defaultSyntax.executionContextAccessor;
+export const openExpression = defaultSyntax.openExpression;
+export const repeatDirectiveClose = defaultSyntax.repeatDirectiveClose;
+export const repeatDirectiveOpen = defaultSyntax.repeatDirectiveOpen;
+export const unescapedCloseExpression = defaultSyntax.unescapedCloseExpression;
+export const unescapedOpenExpression = defaultSyntax.unescapedOpenExpression;
+export const whenDirectiveClose = defaultSyntax.whenDirectiveClose;
+export const whenDirectiveOpen = defaultSyntax.whenDirectiveOpen;

package/dist/esm/declarative/template-bridge.js

@@ -0,0 +1,170 @@
+import { FAST } from "../platform.js";
+import { Message } from "./interfaces.js";
+/**
+ * Coordinates declarative template publishers and FAST element definitions.
+ * Requests are keyed by registry + element name so scoped registries can
+ * resolve templates independently.
+ * @internal
+ */
+export class DeclarativeTemplateBridge {
+    constructor() {
+        this.buckets = new WeakMap();
+    }
+    requestTemplate(definition) {
+        return new Promise((resolve, reject) => {
+            const bucket = this.getBucket(definition.registry, definition.name, true);
+            const request = {
+                definition,
+                settled: false,
+                resolve,
+                reject,
+            };
+            bucket.requests.add(request);
+            this.processBucket(definition.registry, definition.name);
+        });
+    }
+    registerPublisher(registry, name, publisher) {
+        if (!name) {
+            return;
+        }
+        const bucket = this.getBucket(registry, name, true);
+        bucket.publishers.add(publisher);
+        this.processBucket(registry, name);
+    }
+    unregisterPublisher(registry, name, publisher) {
+        if (!name) {
+            return;
+        }
+        const bucket = this.getBucket(registry, name);
+        if (!bucket) {
+            return;
+        }
+        bucket.publishers.delete(publisher);
+        this.resetPublisherRequests(bucket, publisher);
+        this.processBucket(registry, name);
+        this.cleanupBucket(registry, name, bucket);
+    }
+    movePublisher(registry, previousName, nextName, publisher) {
+        if (previousName === nextName) {
+            return;
+        }
+        this.unregisterPublisher(registry, previousName, publisher);
+        this.registerPublisher(registry, nextName, publisher);
+    }
+    getBucket(registry, name, create = false) {
+        let bucketsByName = this.buckets.get(registry);
+        if (!bucketsByName) {
+            if (!create) {
+                return void 0;
+            }
+            bucketsByName = new Map();
+            this.buckets.set(registry, bucketsByName);
+        }
+        let bucket = bucketsByName.get(name);
+        if (!bucket && create) {
+            bucket = {
+                publishers: new Set(),
+                requests: new Set(),
+            };
+            bucketsByName.set(name, bucket);
+        }
+        return bucket;
+    }
+    processBucket(registry, name) {
+        const bucket = this.getBucket(registry, name);
+        if (!bucket) {
+            return;
+        }
+        const publishers = [...bucket.publishers];
+        if (publishers.length > 1) {
+            const error = FAST.error(Message.moreThanOneMatchingTemplateProvided, {
+                name,
+            });
+            for (const request of [...bucket.requests]) {
+                this.rejectRequest(registry, name, bucket, request, error);
+            }
+            return;
+        }
+        if (publishers.length === 0) {
+            return;
+        }
+        const [publisher] = publishers;
+        for (const request of bucket.requests) {
+            if (request.settled) {
+                continue;
+            }
+            if (request.publisher === publisher && request.publishing) {
+                continue;
+            }
+            request.publisher = publisher;
+            request.publishing = Promise.resolve()
+                .then(() => publisher.publishTemplate(request.definition))
+                .then(template => {
+                if (request.settled) {
+                    return;
+                }
+                const currentBucket = this.getBucket(registry, name);
+                if (!(currentBucket === null || currentBucket === void 0 ? void 0 : currentBucket.publishers.has(publisher))) {
+                    request.publisher = void 0;
+                    request.publishing = void 0;
+                    this.processBucket(registry, name);
+                    return;
+                }
+                this.resolveRequest(registry, name, currentBucket, request, template);
+            })
+                .catch(error => {
+                if (request.settled) {
+                    return;
+                }
+                const currentBucket = this.getBucket(registry, name);
+                if (!currentBucket) {
+                    return;
+                }
+                this.rejectRequest(registry, name, currentBucket, request, error);
+            });
+        }
+    }
+    resetPublisherRequests(bucket, publisher) {
+        for (const request of bucket.requests) {
+            if (request.publisher !== publisher) {
+                continue;
+            }
+            request.publisher = void 0;
+            request.publishing = void 0;
+        }
+    }
+    resolveRequest(registry, name, bucket, request, template) {
+        if (request.settled) {
+            return;
+        }
+        request.settled = true;
+        request.publisher = void 0;
+        request.publishing = void 0;
+        bucket.requests.delete(request);
+        this.cleanupBucket(registry, name, bucket);
+        request.resolve(template);
+    }
+    rejectRequest(registry, name, bucket, request, error) {
+        if (request.settled) {
+            return;
+        }
+        request.settled = true;
+        request.publisher = void 0;
+        request.publishing = void 0;
+        bucket.requests.delete(request);
+        this.cleanupBucket(registry, name, bucket);
+        request.reject(error);
+    }
+    cleanupBucket(registry, name, bucket) {
+        if (bucket.publishers.size > 0 || bucket.requests.size > 0) {
+            return;
+        }
+        const bucketsByName = this.buckets.get(registry);
+        bucketsByName === null || bucketsByName === void 0 ? void 0 : bucketsByName.delete(name);
+    }
+}
+/**
+ * Shared template bridge storage for the current FAST runtime.
+ * @internal
+ */
+export const declarativeTemplateBridge = new DeclarativeTemplateBridge();