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

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 { AttributeConfiguration, AttributeDefinition, type AttributeMode, type ValueConverter, } from "../components/attributes.js";
+export { FASTElementDefinition, type FASTElementExtension, type FASTElementTemplateResolver, type PartialFASTElementDefinition, type ShadowRootOptions, } 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 { DOMAspect, type 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, type 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, type ElementViewTemplate, type HTMLTemplateCompilationResult, type SyntheticViewTemplate, type 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;

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

@@ -0,0 +1,98 @@
+import type { Schema } from "../components/schema.js";
+import { ViewTemplate } from "../templating/template.js";
+/**
+ * The return type for {@link TemplateParser.parse}.
+ * @public
+ */
+export interface ResolvedStringsAndValues {
+    strings: Array<string>;
+    values: Array<any>;
+}
+/**
+ * Converts declarative HTML template markup into the `strings` and `values`
+ * arrays that `ViewTemplate.create()` consumes.
+ *
+ * This class is intentionally stateless across invocations — all mutable
+ * parsing state lives on the call stack or in the `TemplateResolutionContext`.
+ *
+ * The parsing pipeline is fully synchronous — no promises are allocated
+ * during template resolution.
+ * @public
+ */
+export declare class TemplateParser {
+    /**
+     * Parse declarative HTML into strings and values for ViewTemplate creation.
+     * @param innerHTML - The transformed innerHTML to parse.
+     * @param schema - The Schema instance for property tracking.
+     * @returns The resolved strings and values.
+     */
+    parse(innerHTML: string, schema: Schema): ResolvedStringsAndValues;
+    /**
+     * Create a ViewTemplate from resolved strings and values.
+     * @param strings - The strings array.
+     * @param values - The interpreted values.
+     */
+    createTemplate(strings: Array<string>, values: Array<any>): ViewTemplate<any, any>;
+    /**
+     * Resolve strings and values from an innerHTML string.
+     * @param rootPropertyName - The root property name for schema registration.
+     * @param innerHTML - The innerHTML.
+     * @param context - The template resolution context.
+     */
+    private resolveStringsAndValues;
+    /**
+     * Resolve a template directive (when/repeat).
+     * @param rootPropertyName - The root property name for schema registration.
+     * @param behaviorConfig - The directive behavior configuration object.
+     * @param externalValues - The interpreted values from the parent.
+     * @param innerHTML - The innerHTML.
+     * @param context - The template resolution context.
+     */
+    private resolveTemplateDirective;
+    /**
+     * Resolve an attribute directive (children/slotted/ref).
+     * @param name - The name of the directive.
+     * @param propName - The property name to pass to the directive.
+     * @param externalValues - The interpreted values from the parent.
+     */
+    private resolveAttributeDirective;
+    /**
+     * Resolve an access binding — shared by content bindings, boolean-attribute
+     * fallback, and default attribute bindings.
+     * @returns An object with the resolved binding function and the updated rootPropertyName.
+     */
+    private resolveAccessBinding;
+    /**
+     * Resolve an event binding (the "\@" aspect).
+     * @returns An object with the event binding function and the updated rootPropertyName.
+     */
+    private resolveEventBinding;
+    /**
+     * Resolve a content data binding (`{{expression}}` in text content).
+     */
+    private resolveContentBinding;
+    /**
+     * Resolve an attribute data binding (`{{expression}}` in an HTML attribute).
+     * Dispatches to event, expression, or access binding handlers based on aspect.
+     */
+    private resolveAttributeBinding;
+    /**
+     * Resolve an attribute directive binding (`f-children`, `f-slotted`, `f-ref`).
+     */
+    private resolveAttributeDirectiveBinding;
+    /**
+     * Dispatcher for data binding resolution. Routes to the appropriate handler
+     * based on the binding subtype.
+     */
+    private resolveDataBinding;
+    /**
+     * Resolver of the innerHTML string. Finds the next binding or directive
+     * in the HTML and dispatches to the appropriate handler.
+     * @param rootPropertyName - The root property name for schema registration.
+     * @param innerHTML - The innerHTML to parse.
+     * @param strings - Accumulator for literal HTML segments and running previous-string.
+     * @param values - The values array (accumulates binding functions and directives).
+     * @param context - The template resolution context.
+     */
+    private resolveInnerHTML;
+}

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

@@ -0,0 +1,9 @@
+import type { FASTElementTemplateResolver } from "../components/fast-definitions.js";
+import type { Constructable } from "../interfaces.js";
+/**
+ * Returns a declarative template resolver that waits for the matching
+ * `<f-template>` element and resolves it into a concrete `ViewTemplate`.
+ *
+ * @public
+ */
+export declare function declarativeTemplate<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(): FASTElementTemplateResolver<TType>;