diff --git a/change/@microsoft-fast-element-78e81f3e-f6be-4ebe-be05-ec6b62829ace.json b/change/@microsoft-fast-element-78e81f3e-f6be-4ebe-be05-ec6b62829ace.json new file mode 100644 index 00000000000..535d3c70ac7 --- /dev/null +++ b/change/@microsoft-fast-element-78e81f3e-f6be-4ebe-be05-ec6b62829ace.json @@ -0,0 +1,7 @@ +{ + "type": "prerelease", + "comment": "feat: allow declarativeTemplate callbacks to resolve templates from f-template strings", + "packageName": "@microsoft/fast-element", + "email": "7559015+janechu@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/packages/fast-element/DESIGN.md b/packages/fast-element/DESIGN.md index 752c5f110e5..d23cb16483d 100644 --- a/packages/fast-element/DESIGN.md +++ b/packages/fast-element/DESIGN.md @@ -351,6 +351,16 @@ the imperative `html` API: - The internal `` publisher parses HTML and returns concrete `ViewTemplate` instances through the registry-aware declarative template bridge. +- `declarativeTemplate({ callback })` registers a transient string publisher for + the definition's name. The callback receives the element definition and a + `templateStringResolver()` function, so it can load template markup with + async flows such as `import()` or `fetch()`. The resolver accepts either a + string or `Promise`, validates that the resolved string contains + exactly one ``, preserves attributes on that element, and then + routes it through the same publisher path as a connected ``. The + callback must return or await the resolver promise; if it completes + successfully without calling `templateStringResolver()`, template resolution + rejects with a diagnostic error instead of waiting indefinitely. - `TemplateParser` lowers declarative syntax to the same `strings` / `values` shape used by `ViewTemplate.create()`. - `attributeMap()` and `observerMap()` are `FASTElementExtension` factories @@ -577,7 +587,7 @@ src/ │ └── di.ts # DI container, decorators, resolvers, Registration ├── context.ts # Context, FASTContext, Context protocol ├── declarative/ -│ ├── template.ts # declarativeTemplate() and internal f-template publisher +│ ├── template.ts # declarativeTemplate(), string callback, internal f-template publisher │ ├── template-parser.ts # Declarative HTML parser → ViewTemplate strings/values │ ├── schema.ts # Compatibility re-export for Schema │ ├── definition-options.ts # Compatibility re-export for schema transforms diff --git a/packages/fast-element/README.md b/packages/fast-element/README.md index 6d4a720f3ee..66fe8524099 100644 --- a/packages/fast-element/README.md +++ b/packages/fast-element/README.md @@ -139,6 +139,40 @@ MyElement.define({ before `define()` resolves. Consumers should not import or define the `` implementation directly. +When template markup needs to be loaded or generated by JavaScript, pass a +`callback` to `declarativeTemplate()`. The callback receives +`templateStringResolver`, can perform async work such as dynamic imports or +`fetch()`, and must return or await the resolver promise. The resolver accepts a +string or `Promise` that contains exactly one `` element. If +the callback completes successfully without calling the resolver, template +resolution rejects with a diagnostic error. The `` can include +attributes such as `name`, and it must contain exactly one child `