feat(web-components): improve ergonomics of the fluent design system (m…

…icrosoft#19056)

* feat(web-components): improve ergonomics of the fluent design system

* Change files

* fix(web-components): address lint issue

* chore(web-components): update api-report

Co-authored-by: EisenbergEffect <roeisenb@microsoft.com>

change/@fluentui-web-components-366f5ffe-df49-4c8d-9348-8218b334dbd1.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat(web-components): improve ergonomics of the fluent design system",
+  "packageName": "@fluentui/web-components",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/web-components/docs/api-report.md

@@ -21,11 +21,13 @@ import { CheckboxOptions } from '@microsoft/fast-foundation';
 import { Combobox as Combobox_2 } from '@microsoft/fast-foundation';
 import { ComboboxOptions } from '@microsoft/fast-foundation';
 import { Constructable } from '@microsoft/fast-element';
+import type { Container } from '@microsoft/fast-foundation';
 import { CSSDesignToken } from '@microsoft/fast-foundation';
 import { CSSDirective } from '@microsoft/fast-element';
 import { DataGrid } from '@microsoft/fast-foundation';
 import { DataGridCell } from '@microsoft/fast-foundation';
 import { DataGridRow } from '@microsoft/fast-foundation';
+import { DesignSystem } from '@microsoft/fast-foundation';
 import { DesignToken } from '@microsoft/fast-foundation';
 import { Dialog } from '@microsoft/fast-foundation';
 import { Direction } from '@microsoft/fast-web-utilities';
@@ -201,6 +203,7 @@ export const allComponents: {
     fluentTooltip: (overrideDefinition?: OverrideFoundationElementDefinition<FoundationElementDefinition> | undefined) => FoundationElementRegistry<FoundationElementDefinition, Tooltip>;
     fluentTreeView: (overrideDefinition?: OverrideFoundationElementDefinition<FoundationElementDefinition> | undefined) => FoundationElementRegistry<FoundationElementDefinition, TreeView>;
     fluentTreeItem: (overrideDefinition?: OverrideFoundationElementDefinition<TreeItemOptions> | undefined) => FoundationElementRegistry<TreeItemOptions, Constructable<FoundationElement>>;
+    register(container?: Container | undefined): void;
 };
 
 // Warning: (ae-internal-missing-underscore) The name "ambientShadow" should be prefixed with an underscore because the declaration is marked as @internal
@@ -1099,6 +1102,9 @@ export const progressRingStyles: (context: ElementDefinitionContext, definition:
 // @public
 export const progressStyles: (context: ElementDefinitionContext, definition: ProgressOptions) => ElementStyles;
 
+// @public
+export function provideFluentDesignSystem(element?: HTMLElement): DesignSystem;
+
 export { Radio }
 
 export { RadioGroup }
@@ -1322,12 +1328,12 @@ export const typeRampPlus6LineHeight: CSSDesignToken<string>;
 
 // Warnings were encountered during analysis:
 //
-// dist/dts/custom-elements.d.ts:47:5 - (ae-incompatible-release-tags) The symbol "fluentAnchor" is marked as @public, but its signature references "Anchor" which is marked as @internal
-// dist/dts/custom-elements.d.ts:49:5 - (ae-incompatible-release-tags) The symbol "fluentBadge" is marked as @public, but its signature references "Badge" which is marked as @internal
-// dist/dts/custom-elements.d.ts:52:5 - (ae-incompatible-release-tags) The symbol "fluentButton" is marked as @public, but its signature references "Button" which is marked as @internal
-// dist/dts/custom-elements.d.ts:89:5 - (ae-incompatible-release-tags) The symbol "fluentTextArea" is marked as @public, but its signature references "TextArea" which is marked as @internal
-// dist/dts/custom-elements.d.ts:90:5 - (ae-incompatible-release-tags) The symbol "fluentTextField" is marked as @public, but its signature references "TextField" which is marked as @internal
-// dist/dts/custom-elements.d.ts:91:5 - (ae-incompatible-release-tags) The symbol "fluentTooltip" is marked as @public, but its signature references "Tooltip" which is marked as @internal
+// dist/dts/custom-elements.d.ts:48:5 - (ae-incompatible-release-tags) The symbol "fluentAnchor" is marked as @public, but its signature references "Anchor" which is marked as @internal
+// dist/dts/custom-elements.d.ts:50:5 - (ae-incompatible-release-tags) The symbol "fluentBadge" is marked as @public, but its signature references "Badge" which is marked as @internal
+// dist/dts/custom-elements.d.ts:53:5 - (ae-incompatible-release-tags) The symbol "fluentButton" is marked as @public, but its signature references "Button" which is marked as @internal
+// dist/dts/custom-elements.d.ts:90:5 - (ae-incompatible-release-tags) The symbol "fluentTextArea" is marked as @public, but its signature references "TextArea" which is marked as @internal
+// dist/dts/custom-elements.d.ts:91:5 - (ae-incompatible-release-tags) The symbol "fluentTextField" is marked as @public, but its signature references "TextField" which is marked as @internal
+// dist/dts/custom-elements.d.ts:92:5 - (ae-incompatible-release-tags) The symbol "fluentTooltip" is marked as @public, but its signature references "Tooltip" which is marked as @internal
 
 // (No @packageDocumentation comment for this package)
 

packages/web-components/src/custom-elements.ts

@@ -1,6 +1,7 @@
 /**
  * Export all custom element definitions
  */
+import type { Container } from '@microsoft/fast-foundation';
 import { fluentAccordion, fluentAccordionItem } from './accordion/index';
 import { fluentAnchor } from './anchor/index';
 import { fluentAnchoredRegion } from './anchored-region/index';
@@ -127,4 +128,19 @@ export const allComponents = {
   fluentTooltip,
   fluentTreeView,
   fluentTreeItem,
+  register(container?: Container) {
+      if (!container) {
+          // preserve backward compatibility with code that loops through
+          // the values of this object and calls them as funcs with no args
+          return;
+      }
+
+      for (const key in this) {
+          if (key === "register") {
+              continue;
+          }
+
+          this[key]().register(container);
+      }
+  },
 };

packages/web-components/src/fluent-design-system.ts

@@ -0,0 +1,12 @@
+import { DesignSystem } from "@microsoft/fast-foundation";
+
+/**
+ * Provides a design system for the specified element either by returning one that was
+ * already created for that element or creating one.
+ * @param element - The element to root the design system at. By default, this is the body.
+ * @returns A Fluent Design System
+ * @public
+ */
+export function provideFluentDesignSystem(element?: HTMLElement): DesignSystem {
+    return DesignSystem.getOrCreate(element).withPrefix("fluent");
+}

packages/web-components/src/index-rollup.ts

@@ -1,13 +1,14 @@
 // TODO: Is exporting Foundation still necessary with the updated API's?
 // export * from "@microsoft/fast-element";
-import { DesignSystem } from '@microsoft/fast-foundation';
 import { allComponents } from './custom-elements';
+import { provideFluentDesignSystem } from './fluent-design-system';
 
 export * from './index';
 
-/**
- * TODO rename this to FluentDesignSystem when {@link @FluentDesignSystem} interface is removed.
+  /**
+ * The global Fluent Design System.
+ * @remarks
+ * Only available if the components are added through a script tag
+ * rather than a module/build system.
  */
-export const fluentDesignSystem = DesignSystem.getOrCreate()
-  .withPrefix('fluent')
-  .register(...Object.values(allComponents).map(definition => definition()));
+export const FluentDesignSystem = provideFluentDesignSystem().register(allComponents);

packages/web-components/src/index.ts

@@ -2,7 +2,7 @@
  * Export all custom element definitions.
  */
 export * from './custom-elements';
-
+export * from "./fluent-design-system";
 export * from './accordion/';
 export * from './anchor/';
 export * from './anchored-region';