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

package/dist/esm/context.js

@@ -0,0 +1,185 @@
+import { Message } from "./interfaces.js";
+import { Metadata } from "./metadata.js";
+import { FAST } from "./platform.js";
+const contextsByName = new Map();
+const contextEventType = "context-request";
+let requestStrategy;
+/**
+ * Enables using:
+ * {@link https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md | W3C Community Context protocol.}
+ * @public
+ */
+export const Context = Object.freeze({
+    /**
+     * The event type used for W3C Context Protocol requests.
+     */
+    eventType: contextEventType,
+    /**
+     * Returns a FASTContext object from the global context registry matching the given name if found.
+     * Otherwise, returns a new FASTContext with this name.
+     * @param name - The name of the FASTContext to get or create.
+     * @returns A FASTContext object.
+     */
+    for(name) {
+        let c = contextsByName.get(name);
+        if (c === void 0) {
+            c = Context.create(name);
+            contextsByName.set(name, c);
+        }
+        return c;
+    },
+    /**
+     * Creates a W3C Community Protocol-based Context object to use in requesting/providing
+     * context through the DOM.
+     * @param name - The name to use for the connext. Useful in debugging.
+     * @param initialValue - An optional initial value to use if a context handler isn't found.
+     */
+    create(name, initialValue) {
+        const Interface = function (target, property, index) {
+            if (target == null || new.target !== undefined) {
+                throw FAST.error(Message.noRegistrationForContext, {
+                    name: Interface.name,
+                });
+            }
+            if (property) {
+                Context.defineProperty(target, property, Interface);
+            }
+            else {
+                const types = Metadata.getOrCreateAnnotationParamTypes(target);
+                types[index] = Interface;
+            }
+        };
+        Interface.$isInterface = true;
+        Interface.initialValue = initialValue;
+        Reflect.defineProperty(Interface, "name", { value: name });
+        Interface.handle = (target, callback) => Context.handle(target, callback, Interface);
+        Interface.provide = (target, value) => Context.provide(target, Interface, value);
+        Interface.get = (target) => Context.get(target, Interface);
+        Interface.request = (target, callback, multiple) => Context.request(target, Interface, callback, multiple);
+        Interface.toString = () => `Context<${Interface.name}>`;
+        return Interface;
+    },
+    /**
+     * Sets the strategy used by all FAST-specific context requests made through the
+     * Context.request, Context.get, Context.defineProperty, and ContextDecorator APIs.
+     * @param strategy - The strategy to use. By default, the strategy is Context.dispatch.
+     */
+    setDefaultRequestStrategy(strategy) {
+        requestStrategy = strategy;
+    },
+    /**
+     * Gets the context value for the target node or returns the initial value if
+     * a context handler is not found.
+     * @param target - The target to get the context for.
+     * @param context - The context to locate.
+     * @returns The context value.
+     * @remarks
+     * Uses the default request strategy to locate the context. If no context is found
+     * then the initial value of the context is returned.
+     */
+    get(target, context) {
+        var _a;
+        let value;
+        requestStrategy(target, context, found => (value = found), false);
+        return (_a = value) !== null && _a !== void 0 ? _a : context.initialValue;
+    },
+    /**
+     * Requests the context value for the target node.
+     * @param target - The target to request the context for.
+     * @param context - The context to locate.
+     * @param callback - A callback to invoke with the context value.
+     * @param multiple - Whether the context requestor expects to handle updates
+     * to the context value after the initial request.
+     * @remarks
+     * Uses the default request strategy to locate the context.
+     */
+    request(target, context, callback, multiple = false) {
+        requestStrategy(target, context, callback, multiple);
+    },
+    /**
+     *
+     * @param target - The target to dispatch the context event on.
+     * @param context - The context to locate.
+     * @param callback - The callback to invoke with the context value.
+     * @param multiple - Whether the context requestor expects to handle updates
+     * to the context value after the initial request.
+     * @remarks
+     * This API does NOT use the default request strategy. It always dispatches
+     * an event through the DOM.
+     */
+    dispatch(target, context, callback, multiple = false) {
+        target.dispatchEvent(new ContextEvent(context, callback, multiple));
+    },
+    /**
+     * 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.
+     */
+    provide(target, context, value) {
+        Context.handle(target, (event) => {
+            event.stopImmediatePropagation();
+            event.callback(value);
+        }, context);
+    },
+    /**
+     *
+     * @param target - The target on which to handle context requests.
+     * @param callback - The callback to invoke when a context request is received.
+     * @param context - The context to handle requests for.
+     * @remarks
+     * If a context is not provided then the callback will be invoked for all context
+     * requests that are received on the target.
+     */
+    handle(target, callback, context) {
+        if (context) {
+            target.addEventListener(contextEventType, (event) => {
+                if (event.context === context) {
+                    callback(event);
+                }
+            });
+        }
+        else {
+            target.addEventListener(contextEventType, callback);
+        }
+    },
+    /**
+     * 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.
+     * @remarks
+     * Uses the default request strategy to locate the context and will return the
+     * initialValue if the context isn't handled.
+     */
+    defineProperty(target, propertyName, context) {
+        const field = Symbol.for(`fast:di:${propertyName}`);
+        Reflect.defineProperty(target, propertyName, {
+            get: function () {
+                var _a;
+                return (_a = this[field]) !== null && _a !== void 0 ? _a : (this[field] = Context.get(this, context));
+            },
+        });
+    },
+});
+Context.setDefaultRequestStrategy(Context.dispatch);
+/**
+ * An event fired by a context requester to signal it desires a named context.
+ *
+ * A provider should inspect the `context` property of the event to determine if it has a value that can
+ * satisfy the request, calling the `callback` with the requested value if so.
+ *
+ * If the requested context event contains a truthy `multiple` value, then a provider can call the callback
+ * multiple times if the value is changed, if this is the case the provider should pass a `dispose`
+ * method to the callback which requesters can invoke to indicate they no longer wish to receive these updates.
+ * @public
+ */
+export class ContextEvent extends Event {
+    constructor(context, callback, multiple) {
+        super(contextEventType, { bubbles: true, composed: true });
+        this.context = context;
+        this.callback = callback;
+        this.multiple = multiple;
+    }
+}

package/dist/esm/debug.js

@@ -0,0 +1,71 @@
+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.",
+    [1203 /* twoWayBindingRequiresObservables */]: "View=>Model update skipped. To use twoWay binding, the target property must be observable.",
+    [1204 /* hostBindingWithoutHost */]: "No host element is present. Cannot bind host with ${name}.",
+    [1205 /* unsupportedBindingBehavior */]: "The requested binding behavior is not supported by the binding engine.",
+    [1206 /* directCallToHTMLTagNotAllowed */]: "Calling html`` as a normal function invalidates the security guarantees provided by FAST.",
+    [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.",
+    [1503 /* invalidResolverStrategy */]: "Invalid dependency injection resolver strategy specified '${strategy}'.",
+    [1504 /* cannotAutoregisterDependency */]: "Unable to autoregister dependency.",
+    [1505 /* cannotResolveKey */]: "Unable to resolve dependency injection key '${key}'.",
+    [1506 /* cannotConstructNativeFunction */]: 
+    /* eslint-disable-next-line max-len */
+    "'${name}' is a native function and therefore cannot be safely constructed by DI. If this is intentional, please use a callback or cachedCallback resolver.",
+    [1507 /* cannotJITRegisterNonConstructor */]: "Attempted to jitRegister something that is not a constructor '${value}'. Did you forget to register this dependency?",
+    [1508 /* cannotJITRegisterIntrinsic */]: "Attempted to jitRegister an intrinsic type '${value}'. Did you forget to add @inject(Key)?",
+    [1509 /* cannotJITRegisterInterface */]: "Attempted to jitRegister an interface '${value}'.",
+    [1510 /* invalidResolver */]: "A valid resolver was not returned from the register method.",
+    [1511 /* invalidKey */]: "Key/value cannot be null or undefined. Are you trying to inject/register something that doesn't exist with DI?",
+    [1512 /* noDefaultResolver */]: "'${key}' not registered. Did you forget to add @singleton()?",
+    [1513 /* cyclicDependency */]: "Cyclic dependency found '${name}'.",
+    [1514 /* connectUpdateRequiresController */]: "Injected properties that are updated on changes to DOM connectivity require the target object to be an instance of FASTElement.",
+    [1601 /* invalidAttributeMarkerName */]: "Invalid attribute marker name: ${name}. Expected format is ${expectedFormat}.",
+    [1602 /* invalidCompactAttributeMarkerValues */]: "Invalid compact attribute marker values in ${markerName}. Both index and count must be positive integers.",
+    [1604 /* invalidCompactAttributeMarkerName */]: "Invalid compact attribute marker name: ${name}. Expected format is ${expectedFormat}.",
+};
+const allPlaceholders = /(\$\{\w+?})/g;
+const placeholder = /\$\{(\w+?)}/g;
+const noValues = Object.freeze({});
+function formatMessage(message, values) {
+    return message
+        .split(allPlaceholders)
+        .map(v => {
+        var _a;
+        const replaced = v.replace(placeholder, "$1");
+        return String((_a = values[replaced]) !== null && _a !== void 0 ? _a : v);
+    })
+        .join("");
+}
+/**
+ * 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,10 @@
+export { AttributeConfiguration, AttributeDefinition, } from "../components/attributes.js";
+export { FASTElementDefinition, } from "../components/fast-definitions.js";
+export { Schema, schemaRegistry, } from "../components/schema.js";
+export { DOMAspect } from "../dom.js";
+export { DOMPolicy, } from "../dom-policy.js";
+export { ElementStyles, } from "../styles/element-styles.js";
+export { ViewTemplate, } from "../templating/template.js";
+export { HTMLView } from "../templating/view.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 = {}));