docs: add alpha tags to unfinished binding APIs (#5665)

* docs: add alpha tags to unfinished binding APIs * Change files Co-authored-by: EisenbergEffect <[email protected]>
microsoft · May 3, 2022 · 75fbcaf · 75fbcaf
1 parent cc2341b
commit 75fbcaf
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 9 deletions.
diff --git a/change/@microsoft-fast-element-d6062145-f143-437a-ae17-b8a923f1208e.json 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": "[email protected]",
+  "dependentChangeType": "none"
+}
diff --git a/packages/web-components/fast-element/docs/api-report.md b/packages/web-components/fast-element/docs/api-report.md
@@ -60,26 +60,26 @@ export interface Behavior<TSource = any, TParent = any, TGrandparent = any> {
     unbind(source: TSource, context: ExecutionContext<TParent, TGrandparent>): void;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export function bind<T = any>(binding: Binding<T>, config?: BindingConfig<T> | DefaultBindingOptions): CaptureType<T>;
 
 // @public
 export type Binding<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
 
-// @public (undocumented)
+// @alpha (undocumented)
 export type BindingBehaviorFactory = {
     createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
 };
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface BindingConfig<T = any> {
     // (undocumented)
     mode: BindingMode;
     // (undocumented)
     options: any;
 }
 
-// @public (undocumented)
+// @alpha (undocumented)
 export interface BindingMode {
     // (undocumented)
     attribute: BindingType;
@@ -104,7 +104,7 @@ export interface BindingObserver<TSource = any, TReturn = any, TParent = any> 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<AttributeConfiguration, "property">;
 
-// @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<DefaultBindingOptions> & BindingConfigResolver<DefaultBindingOptions>;
 
-// @public (undocumented)
+// @alpha (undocumented)
 export const oneTime: BindingConfig<DefaultBindingOptions> & BindingConfigResolver<DefaultBindingOptions>;
 
 // @public

diff --git 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<T = any> {
     mode: BindingMode;
     options: any;
@@ -268,6 +285,9 @@ class OneTimeBinding extends TargetUpdateBinding {
 
 const signals: Record<string, undefined | Function | Function[]> = 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,18 +477,27 @@ 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)
 );
 
 const signalMode: BindingMode = OnSignalBinding.createBindingMode();
 
+/**
+ * @alpha
+ */
 export const signal = <T = any>(options: string | Binding<T>): BindingConfig<T> => {
     return { mode: signalMode, options };
 };
@@ -537,6 +569,9 @@ export class HTMLBindingDirective extends InlinableHTMLDirective {
     }
 }
 
+/**
+ * @alpha
+ */
 export function bind<T = any>(
     binding: Binding<T>,
     config: BindingConfig<T> | DefaultBindingOptions = onChange