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

package/dist/dts/components/schema.d.ts

@@ -0,0 +1,205 @@
+type FastContextMetaData = "$fast_context";
+type FastContextsMetaData = "$fast_parent_contexts";
+/**
+ * Describes a child custom element binding referenced by a schema path.
+ * @public
+ */
+export interface ChildrenMap {
+    customElementName: string;
+    attributeName: string;
+}
+/**
+ * A reusable JSON schema definition.
+ * @public
+ */
+export interface JSONSchemaDefinition extends JSONSchemaCommon {
+    $fast_context: string;
+    $fast_parent_contexts: Array<string>;
+}
+/**
+ * Common properties shared by schema nodes.
+ * @public
+ */
+export interface JSONSchemaCommon {
+    type?: string;
+    properties?: any;
+    items?: any;
+    anyOf?: Array<any>;
+    $ref?: string;
+    /**
+     * Stamped by `applyConfigToSchema` when an `ObserverMapConfig` excludes
+     * this path. When `false`, the proxy system skips observation for this
+     * node and (if all descendants are also `false`) its subtree.
+     */
+    $observe?: boolean;
+}
+/**
+ * A JSON schema describing a root property.
+ * @public
+ */
+export interface JSONSchema extends JSONSchemaCommon {
+    $schema: string;
+    $id: string;
+    $defs?: Record<string, JSONSchemaDefinition>;
+}
+/**
+ * Common metadata for paths cached while parsing a template.
+ * @public
+ */
+export interface CachedPathCommon {
+    parentContext: string | null;
+    currentContext: string | null;
+    path: string;
+}
+/**
+ * A path discovered from an access expression.
+ * @public
+ */
+export interface AccessCachedPath extends CachedPathCommon {
+    type: "access";
+}
+/**
+ * A path discovered from a default binding.
+ * @public
+ */
+export interface DefaultCachedPath extends CachedPathCommon {
+    type: "default";
+}
+/**
+ * A path discovered from an event binding.
+ * @public
+ */
+export interface EventCachedPath extends CachedPathCommon {
+    type: "event";
+}
+/**
+ * A path discovered from a repeat directive.
+ * @public
+ */
+export interface RepeatCachedPath extends CachedPathCommon {
+    type: "repeat";
+}
+/**
+ * A path discovered while parsing a template.
+ * @public
+ */
+export type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+/**
+ * A map from element names and root properties to JSON schemas.
+ * @public
+ */
+export type CachedPathMap = Map<string, Map<string, JSONSchema>>;
+/**
+ * Configuration for registering a path with a schema.
+ * @public
+ */
+export interface RegisterPathConfig {
+    rootPropertyName: string;
+    pathConfig: CachedPath;
+    childrenMap: ChildrenMap | null;
+}
+export declare const fastContextMetaData: FastContextMetaData;
+export declare const fastContextsMetaData: FastContextsMetaData;
+export declare const defsPropertyName = "$defs";
+export declare 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 declare const schemaRegistry: CachedPathMap;
+/**
+ * A constructed JSON schema from a template
+ * @public
+ */
+export declare class Schema {
+    /**
+     * The name of the custom element
+     */
+    private customElementName;
+    /**
+     * Instance-level JSON schema map describing each root property
+     */
+    private schemaMap;
+    constructor(name: string);
+    /**
+     * Add a path to a schema
+     * @param config - The path registration configuration.
+     */
+    addPath(config: RegisterPathConfig): void;
+    /**
+     * 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: string): JSONSchema | null;
+    /**
+     * Gets root properties
+     * @returns IterableIterator<string>
+     */
+    getRootProperties(): IterableIterator<string>;
+    /**
+     * 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
+     */
+    private getSplitPath;
+    /**
+     * 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
+     */
+    private getDefsPath;
+    /**
+     * 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
+     */
+    private getSchemaId;
+    /**
+     * Add a new JSON schema to the JSON schema map
+     * @param propertyName - The name of the property to assign this JSON schema to.
+     */
+    private addNewSchema;
+    /**
+     * 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.
+     */
+    private addPropertiesToAContext;
+    /**
+     * 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).
+     */
+    private addPropertiesToAnObject;
+    /**
+     * Add an array to an object property
+     * @param schema - The schema to add the properties to.
+     * @param context - The name of the context.
+     */
+    private addArrayToAnObject;
+    /**
+     * 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
+     */
+    private addContext;
+    /**
+     * Get parent contexts
+     * @param schema - The schema to use.
+     * @param parentContext - The parent context.
+     * @param contexts - A list of parent contexts.
+     * @returns
+     */
+    private getParentContexts;
+}
+export {};

package/dist/dts/context.d.ts

@@ -56,7 +56,7 @@ export declare const Context: Readonly<{
      * @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<T_1 = unknown>(name: string, initialValue?: T_1 | undefined): FASTContext<T_1>;
+    create<T = unknown>(name: string, initialValue?: T): FASTContext<T>;
     /**
      * Sets the strategy used by all FAST-specific context requests made through the
      * Context.request, Context.get, Context.defineProperty, and ContextDecorator APIs.
@@ -73,7 +73,7 @@ export declare const Context: Readonly<{
      * Uses the default request strategy to locate the context. If no context is found
      * then the initial value of the context is returned.
      */
-    get<T_2 extends UnknownContext>(target: EventTarget, context: T_2): ContextType<T_2>;
+    get<T extends UnknownContext>(target: EventTarget, context: T): ContextType<T>;
     /**
      * Requests the context value for the target node.
      * @param target - The target to request the context for.
@@ -84,7 +84,7 @@ export declare const Context: Readonly<{
      * @remarks
      * Uses the default request strategy to locate the context.
      */
-    request<T_3 extends UnknownContext>(target: EventTarget, context: T_3, callback: ContextCallback<ContextType<T_3>>, multiple?: boolean): void;
+    request<T extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple?: boolean): void;
     /**
      *
      * @param target - The target to dispatch the context event on.
@@ -96,14 +96,14 @@ export declare const Context: Readonly<{
      * This API does NOT use the default request strategy. It always dispatches
      * an event through the DOM.
      */
-    dispatch<T_4 extends UnknownContext>(target: EventTarget, context: T_4, callback: ContextCallback<ContextType<T_4>>, multiple?: boolean): void;
+    dispatch<T extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple?: boolean): void;
     /**
      * 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<T_5 extends UnknownContext>(target: EventTarget, context: T_5, value: ContextType<T_5>): void;
+    provide<T extends UnknownContext>(target: EventTarget, context: T, value: ContextType<T>): void;
     /**
      *
      * @param target - The target on which to handle context requests.
@@ -113,18 +113,18 @@ export declare const Context: Readonly<{
      * If a context is not provided then the callback will be invoked for all context
      * requests that are received on the target.
      */
-    handle<T_6 extends UnknownContext>(target: EventTarget, callback: (event: ContextEvent<T_6>) => void, context?: T_6 | undefined): void;
+    handle<T extends UnknownContext>(target: EventTarget, callback: (event: ContextEvent<T>) => void, context?: T): void;
     /**
      * 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.
      */
-    defineProperty<T_7 extends UnknownContext>(target: Constructable<EventTarget> | EventTarget, propertyName: string, context: T_7): void;
+    defineProperty<T extends UnknownContext>(target: Constructable<EventTarget> | EventTarget, propertyName: string, context: T): void;
 }>;
 /**
  * An unknown context type.

package/dist/dts/css.d.ts

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

package/dist/dts/debug.d.ts

@@ -1 +1,5 @@
-export {};
+/**
+ * Enables human-readable FAST debug messages.
+ * @public
+ */
+export declare function enableDebug(): void;

package/dist/dts/declarative/attribute-map.d.ts

@@ -0,0 +1,58 @@
+import { type FASTElementExtension } from "../components/fast-definitions.js";
+import type { Schema } from "../components/schema.js";
+export { type AccessCachedPath, type CachedPath, type CachedPathCommon, type CachedPathMap, type ChildrenMap, type DefaultCachedPath, type EventCachedPath, type JSONSchema, type JSONSchemaCommon, type JSONSchemaDefinition, type RegisterPathConfig, type RepeatCachedPath, Schema, schemaRegistry, } from "../components/schema.js";
+/**
+ * Configuration object for the attributeMap extension.
+ * Omitting all fields uses the default attribute-mapping behavior.
+ * @public
+ */
+export interface AttributeMapConfig {
+    /**
+     * Strategy for mapping template binding keys to HTML attribute names.
+     *
+     * - `"camelCase"` (default): the binding key is treated as a camelCase property
+     *   name and the attribute name is derived by converting it to
+     *   kebab-case (e.g. `{{fooBar}}` → property `fooBar`, attribute
+     *   `foo-bar`). This matches the build-time `attribute-name-strategy`
+     *   option in `@microsoft/fast-build`.
+     * - `"none"`: the binding key is used as-is for both the
+     *   property name and the attribute name (e.g. `{{foo-bar}}` →
+     *   property `foo-bar`, attribute `foo-bar`).
+     */
+    "attribute-name-strategy"?: "none" | "camelCase";
+}
+/**
+ * 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 declare function attributeMap(config?: AttributeMapConfig): FASTElementExtension;
+/**
+ * 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 declare class AttributeMap {
+    private schema;
+    private classPrototype;
+    private definition;
+    private config;
+    constructor(classPrototype: any, schema: Schema, definition?: any, config?: AttributeMapConfig);
+    defineProperties(): void;
+}

package/dist/dts/declarative/debug.d.ts

@@ -0,0 +1,4 @@
+export declare const debugMessages: {
+    [2000]: string;
+    [2001]: string;
+};

package/dist/dts/declarative/index.d.ts

@@ -0,0 +1,14 @@
+export type { AttributeConfiguration, AttributeDefinition, AttributeMode, ValueConverter, } from "../components/attributes.js";
+export type { FASTElementDefinition, FASTElementExtension, FASTElementTemplateResolver, PartialFASTElementDefinition, ShadowRootOptions, TemplateLifecycleCallbacks, } from "../components/fast-definitions.js";
+export { type AccessCachedPath, type CachedPath, type CachedPathCommon, type CachedPathMap, type ChildrenMap, type DefaultCachedPath, type EventCachedPath, type JSONSchema, type JSONSchemaCommon, type JSONSchemaDefinition, type RegisterPathConfig, type RepeatCachedPath, Schema, schemaRegistry, } from "../components/schema.js";
+export type { DOMAspect, DOMSink } from "../dom.js";
+export { type DOMAspectGuards, type DOMElementGuards, type DOMGuards, DOMPolicy, type DOMPolicyOptions, type DOMSinkGuards, } from "../dom-policy.js";
+export type { Constructable, TrustedTypesPolicy } from "../interfaces.js";
+export type { Accessor } from "../observation/observable.js";
+export type { ComposableStyles, ConstructibleStyleStrategy, ElementStyles, } from "../styles/element-styles.js";
+export type { StyleStrategy, StyleTarget } from "../styles/style-strategy.js";
+export type { ViewBehavior, ViewBehaviorFactory, } from "../templating/html-directive.js";
+export type { CaptureType, ElementViewTemplate, HTMLTemplateCompilationResult, SyntheticViewTemplate, TemplateValue, ViewTemplate, } from "../templating/template.js";
+export type { ElementView, HTMLView } from "../templating/view.js";
+export { declarativeTemplate } from "./template.js";
+export { type ResolvedStringsAndValues, TemplateParser } from "./template-parser.js";

package/dist/dts/declarative/interfaces.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Warning and error messages.
+ * @internal
+ */
+export declare const enum Message {
+    noTemplateProvided = 2000,
+    moreThanOneTemplateProvided = 2001
+}

package/dist/dts/declarative/observer-map-utilities.d.ts

@@ -0,0 +1,58 @@
+import { type JSONSchema, type JSONSchemaDefinition } from "../components/schema.js";
+/**
+ * Find a definition
+ * This may exist as a $ref at the root or as a $ref in any anyOf or not at all
+ * if the Observer Map has not been enabled on a child component
+ * @param schema - The JSON schema to find the ref in
+ * @returns The definition or null
+ * @public
+ */
+export declare function findDef(schema: JSONSchema | JSONSchemaDefinition): string | null;
+/**
+ * Assign observables to data
+ * @param schema - The schema
+ * @param rootSchema - The root schema mapping to the root property
+ * @param data - The data
+ * @param target - The target custom element
+ * @param rootProperty - The root property
+ * @returns
+ * @public
+ */
+export declare function assignObservables(schema: JSONSchema | JSONSchemaDefinition, rootSchema: JSONSchema, data: any, target: any, rootProperty: string): typeof Proxy;
+/**
+ * Assign a proxy to an object
+ * @param schema - The current schema
+ * @param rootSchema - The root schema for the root property
+ * @param target - The target custom element
+ * @param rootProperty - The root property
+ * @param object - The object to assign the proxy to
+ * @returns Proxy object
+ * @public
+ */
+export declare function assignProxy(schema: JSONSchema | JSONSchemaDefinition, rootSchema: JSONSchema, target: any, rootProperty: string, object: any): typeof Proxy;
+/**
+ * Deeply compares two objects for equality.
+ *
+ * @param obj1 - First object to compare
+ * @param obj2 - Second object to compare
+ * @returns True if the objects are deeply equal, false otherwise
+ * @public
+ */
+export declare function deepEqual(obj1: any, obj2: any): boolean;
+/**
+ * Checks if a value is a plain object (not an array, null, or other type).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ * @public
+ */
+export declare function isPlainObject(value: any): value is Record<string, any>;
+/**
+ * Deeply merges the source object into the target object.
+ *
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns boolean indicating whether changes were made
+ * @public
+ */
+export declare function deepMerge(target: any, source: any): boolean;

package/dist/dts/declarative/observer-map.d.ts

@@ -0,0 +1,89 @@
+import { type FASTElementExtension } from "../components/fast-definitions.js";
+import type { Schema } from "../components/schema.js";
+export { type AccessCachedPath, type CachedPath, type CachedPathCommon, type CachedPathMap, type ChildrenMap, type DefaultCachedPath, type EventCachedPath, type JSONSchema, type JSONSchemaCommon, type JSONSchemaDefinition, type RegisterPathConfig, type RepeatCachedPath, Schema, schemaRegistry, } from "../components/schema.js";
+/**
+ * A node in the observer-map path tree.
+ *
+ * - `true`  → observe this path and all descendants (unless overridden by children).
+ * - `false` → do NOT observe this path or its descendants (unless overridden by children).
+ * - `ObserverMapPathNode` → configure child paths individually;
+ *       the node itself is observed if `$observe` is true (default when parent is observed).
+ * @public
+ */
+export type ObserverMapPathEntry = boolean | ObserverMapPathNode;
+/**
+ * A node object in the observer-map path tree.
+ *
+ * `$observe` controls whether this node itself is observed.
+ * When omitted the value is inherited from the nearest ancestor
+ * that explicitly sets `$observe`. At the root level the default is `true`.
+ *
+ * Child property overrides are keyed by property name.
+ * @public
+ */
+export interface ObserverMapPathNode {
+    $observe?: boolean;
+    [propertyName: string]: ObserverMapPathEntry | undefined;
+}
+/**
+ * Configuration object for the observerMap extension.
+ * `schema` enables non-declarative/manual schema use.
+ * When `properties` is omitted, every root property is observed. When
+ * `properties` is present, only listed root properties participate in
+ * observer-map observation.
+ * @public
+ */
+export interface ObserverMapConfig {
+    /**
+     * The schema to use for observer-map configuration.
+     * Pass this for non-declarative/manual schema use. When omitted, the
+     * extension uses the schema on the FAST element definition.
+     */
+    schema?: Schema;
+    /**
+     * Per-root-property observation control.
+     * Keys are root property names discovered in the template schema.
+     * Only root properties listed here participate in observer-map observation.
+     * Omitting this field observes every discovered root property.
+     */
+    properties?: {
+        [rootProperty: string]: ObserverMapPathEntry;
+    };
+}
+/**
+ * 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 declare function observerMap(config?: ObserverMapConfig): FASTElementExtension;
+/**
+ * ObserverMap provides functionality for caching binding paths, extracting root properties,
+ * and defining observable properties on class prototypes
+ * @public
+ */
+export declare class ObserverMap {
+    private schema;
+    private classPrototype;
+    private config;
+    constructor(classPrototype: any, schema: Schema, config?: ObserverMapConfig);
+    defineProperties(): void;
+    /**
+     * 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
+     */
+    private getAndAssignObservables;
+    /**
+     * 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
+     */
+    private defineChanged;
+}

package/dist/dts/declarative/runtime.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Installs the declarative runtime debug messages.
+ * @internal
+ */
+export declare function ensureDeclarativeRuntime(): void;

package/dist/dts/declarative/syntax.d.ts

@@ -0,0 +1,21 @@
+export declare const attributeDirectivePrefix: string;
+export declare const clientSideCloseExpression: string;
+export declare const clientSideOpenExpression: string;
+export declare const closeExpression: string;
+/**
+ * Event argument accessor for declarative event bindings.
+ * @public
+ */
+export declare const eventArgAccessor: string;
+/**
+ * Execution context accessor for declarative event bindings.
+ * @public
+ */
+export declare const executionContextAccessor: string;
+export declare const openExpression: string;
+export declare const repeatDirectiveClose: string;
+export declare const repeatDirectiveOpen: string;
+export declare const unescapedCloseExpression: string;
+export declare const unescapedOpenExpression: string;
+export declare const whenDirectiveClose: string;
+export declare const whenDirectiveOpen: string;

package/dist/dts/declarative/template-bridge.d.ts

@@ -0,0 +1,33 @@
+import type { FASTElementDefinition } from "../components/fast-definitions.js";
+import type { ElementViewTemplate } from "../templating/template.js";
+/**
+ * Publishes a concrete template for a definition.
+ * @internal
+ */
+export interface TemplatePublisher {
+    publishTemplate(definition: FASTElementDefinition): ElementViewTemplate | Promise<ElementViewTemplate>;
+}
+/**
+ * Coordinates declarative template publishers and FAST element definitions.
+ * Requests are keyed by registry + element name so scoped registries can
+ * resolve templates independently.
+ * @internal
+ */
+export declare class DeclarativeTemplateBridge {
+    private readonly buckets;
+    requestTemplate(definition: FASTElementDefinition): Promise<ElementViewTemplate>;
+    registerPublisher(registry: CustomElementRegistry, name: string | undefined, publisher: TemplatePublisher): void;
+    unregisterPublisher(registry: CustomElementRegistry, name: string | undefined, publisher: TemplatePublisher): void;
+    movePublisher(registry: CustomElementRegistry, previousName: string | undefined, nextName: string | undefined, publisher: TemplatePublisher): void;
+    private getBucket;
+    private processBucket;
+    private resetPublisherRequests;
+    private resolveRequest;
+    private rejectRequest;
+    private cleanupBucket;
+}
+/**
+ * Shared template bridge storage for the current FAST runtime.
+ * @internal
+ */
+export declare const declarativeTemplateBridge: DeclarativeTemplateBridge;