diff --git a/change/@microsoft-fast-element-d6062145-f143-437a-ae17-b8a923f1208e.json b/change/@microsoft-fast-element-d6062145-f143-437a-ae17-b8a923f1208e.json new file mode 100644 index 00000000000..8c74cab22c6 --- /dev/null +++ b/change/@microsoft-fast-element-d6062145-f143-437a-ae17-b8a923f1208e.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "docs: add alpha tags to unfinished binding APIs", + "packageName": "@microsoft/fast-element", + "email": "roeisenb@microsoft.com", + "dependentChangeType": "none" +} diff --git a/packages/web-components/fast-element/docs/api-report.md b/packages/web-components/fast-element/docs/api-report.md index e38a9a06d73..7bdd2112ad4 100644 --- a/packages/web-components/fast-element/docs/api-report.md +++ b/packages/web-components/fast-element/docs/api-report.md @@ -60,18 +60,18 @@ export interface Behavior { unbind(source: TSource, context: ExecutionContext): void; } -// @public (undocumented) +// @alpha (undocumented) export function bind(binding: Binding, config?: BindingConfig | DefaultBindingOptions): CaptureType; // @public export type Binding = (source: TSource, context: ExecutionContext) => TReturn; -// @public (undocumented) +// @alpha (undocumented) export type BindingBehaviorFactory = { createBehavior(targets: ViewBehaviorTargets): ViewBehavior; }; -// @public (undocumented) +// @alpha (undocumented) export interface BindingConfig { // (undocumented) mode: BindingMode; @@ -79,7 +79,7 @@ export interface BindingConfig { options: any; } -// @public (undocumented) +// @alpha (undocumented) export interface BindingMode { // (undocumented) attribute: BindingType; @@ -104,7 +104,7 @@ export interface BindingObserver ex // Warning: (ae-forgotten-export) The symbol "HTMLBindingDirective" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @alpha (undocumented) export type BindingType = (directive: HTMLBindingDirective) => BindingBehaviorFactory; // @public @@ -196,7 +196,7 @@ export function customElement(nameOrDef: string | PartialFASTElementDefinition): // @public export type DecoratorAttributeConfiguration = Omit; -// @public (undocumented) +// @alpha (undocumented) export type DefaultBindingOptions = { capture?: boolean; }; @@ -415,10 +415,10 @@ export interface ObservationRecord { // Warning: (ae-forgotten-export) The symbol "BindingConfigResolver" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @alpha (undocumented) export const onChange: BindingConfig & BindingConfigResolver; -// @public (undocumented) +// @alpha (undocumented) export const oneTime: BindingConfig & BindingConfigResolver; // @public diff --git a/packages/web-components/fast-element/src/templating/binding.ts b/packages/web-components/fast-element/src/templating/binding.ts index cefec33ba7e..a333a04969e 100644 --- a/packages/web-components/fast-element/src/templating/binding.ts +++ b/packages/web-components/fast-element/src/templating/binding.ts @@ -15,15 +15,30 @@ import { import type { CaptureType } from "./template.js"; import type { SyntheticView } from "./view.js"; +// TODO: Fix the code docs in this file. + +/** + * @alpha + */ export type BindingBehaviorFactory = { createBehavior(targets: ViewBehaviorTargets): ViewBehavior; }; +/** + * @alpha + */ export type BindingType = (directive: HTMLBindingDirective) => BindingBehaviorFactory; + +/** + * @alpha + */ export const notSupportedBindingType: BindingType = () => { throw new Error(); }; +/** + * @alpha + */ export interface BindingMode { attribute: BindingType; booleanAttribute: BindingType; @@ -33,7 +48,9 @@ export interface BindingMode { event: BindingType; } -/* eslint-disable-next-line @typescript-eslint/no-unused-vars */ +/** + * @alpha + */ export interface BindingConfig { mode: BindingMode; options: any; @@ -268,6 +285,9 @@ class OneTimeBinding extends TargetUpdateBinding { const signals: Record = Object.create(null); +/** + * @alpha + */ export function sendSignal(signal: string): void { const found = signals[signal]; if (found) { @@ -446,6 +466,9 @@ class OneTimeEventListener extends EventListener { } } +/** + * @alpha + */ export type DefaultBindingOptions = { capture?: boolean; }; @@ -454,11 +477,17 @@ const defaultBindingOptions: DefaultBindingOptions = { capture: false, }; +/** + * @alpha + */ export const onChange = OnChangeBinding.createBindingConfig( defaultBindingOptions, directive => new EventListener(directive) ); +/** + * @alpha + */ export const oneTime = OneTimeBinding.createBindingConfig( defaultBindingOptions, directive => new OneTimeEventListener(directive) @@ -466,6 +495,9 @@ export const oneTime = OneTimeBinding.createBindingConfig( const signalMode: BindingMode = OnSignalBinding.createBindingMode(); +/** + * @alpha + */ export const signal = (options: string | Binding): BindingConfig => { return { mode: signalMode, options }; }; @@ -537,6 +569,9 @@ export class HTMLBindingDirective extends InlinableHTMLDirective { } } +/** + * @alpha + */ export function bind( binding: Binding, config: BindingConfig | DefaultBindingOptions = onChange