feat: add text as new component (#26090)

* add text as a new component

* update main.js to .cjs format for esm due to require syntax

* update style rules to align with FUI react v9, export text options, update stories to leverage object.keys of options

* export text, update node resolution to 16 and fix object.keys for size to object.values

* prettier style files, may need to revert if it does not play nice with selectors

* update display for host to ensure we can layout the element properly margin, etc...

* update latest FAST packages

* leverage ValuesOf type helper

.prettierignore

@@ -34,7 +34,6 @@ packages/fluentui/docs/src/behaviorMenu.json
 packages/fluentui/docs/src/exampleMenus
 packages/fluentui/docs/src/exampleSources
 packages/fluentui/ability-attributes/src/schema.ts
-packages/web-components/src/**/*.styles.ts
 packages/web-components/**/*.spec.ts
 packages/web-components/src/default-palette.ts
 

change/@fluentui-web-components-06188225-69da-4cf6-918c-932a9ceab1b3.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "add text as a new component",
+  "packageName": "@fluentui/web-components",
+  "email": "chhol@microsoft.com",
+  "dependentChangeType": "patch"
+}

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

@@ -4,8 +4,86 @@
 
 ```ts
 
-// @public (undocumented)
-export const empty = "";
+import { ElementStyles } from '@microsoft/fast-element';
+import { ElementViewTemplate } from '@microsoft/fast-element';
+import { FASTElement } from '@microsoft/fast-element';
+import { FASTElementDefinition } from '@microsoft/fast-element';
+import { ValuesOf } from '@microsoft/fast-foundation';
+
+// @public
+class Text_2 extends FASTElement {
+    align: TextAlign;
+    block: boolean;
+    font: TextFont;
+    italic: boolean;
+    nowrap: boolean;
+    size: TextSize;
+    strikethrough: boolean;
+    truncate: boolean;
+    underline: boolean;
+    weight: TextWeight;
+}
+export { Text_2 as Text }
+
+// @public
+export const TextAlign: {
+    readonly start: "start";
+    readonly end: "end";
+    readonly center: "center";
+    readonly justify: "justify";
+};
+
+// @public
+export type TextAlign = ValuesOf<typeof TextAlign>;
+
+// @public
+export const TextDefinition: FASTElementDefinition<typeof Text_2>;
+
+// @public
+export const TextFont: {
+    readonly base: "base";
+    readonly numeric: "numeric";
+    readonly monospace: "monospace";
+};
+
+// @public
+export type TextFont = ValuesOf<typeof TextFont>;
+
+// @public
+export const TextSize: {
+    readonly _100: "100";
+    readonly _200: "200";
+    readonly _300: "300";
+    readonly _400: "400";
+    readonly _500: "500";
+    readonly _600: "600";
+    readonly _700: "700";
+    readonly _800: "800";
+    readonly _900: "900";
+    readonly _1000: "1000";
+};
+
+// @public
+export type TextSize = ValuesOf<typeof TextSize>;
+
+// @public
+export const TextStyles: ElementStyles;
+
+// Warning: (ae-internal-missing-underscore) The name "TextTemplate" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal (undocumented)
+export const TextTemplate: ElementViewTemplate<Text_2>;
+
+// @public
+export const TextWeight: {
+    readonly medium: "medium";
+    readonly regular: "regular";
+    readonly semibold: "semibold";
+    readonly bold: "bold";
+};
+
+// @public
+export type TextWeight = ValuesOf<typeof TextWeight>;
 
 // (No @packageDocumentation comment for this package)
 

packages/web-components/package.json

@@ -19,6 +19,16 @@
   "main": "dist/esm/index.js",
   "types": "dist/web-components.d.ts",
   "unpkg": "dist/web-components.min.js",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "default": "./dist/esm/index.js"
+    },
+    "./text": {
+      "types": "./dist/esm/text/define.d.ts",
+      "default": "./dist/esm/text/define.js"
+    }
+  },
   "scripts": {
     "tsc": "tsc",
     "api-extractor": "api-extractor",
@@ -77,8 +87,8 @@
     "typescript": "4.7.4"
   },
   "dependencies": {
-    "@microsoft/fast-element": "^2.0.0-beta.17",
-    "@microsoft/fast-foundation": "^3.0.0-alpha.21",
+    "@microsoft/fast-element": "^2.0.0-beta.20",
+    "@microsoft/fast-foundation": "^3.0.0-alpha.24",
     "@microsoft/fast-web-utilities": "^6.0.0",
     "@fluentui/tokens": "1.0.0-alpha.2",
     "tslib": "^1.13.0"

packages/web-components/src/__test__/helpers.ts

@@ -0,0 +1,56 @@
+import type { FASTElement, ViewTemplate } from '@microsoft/fast-element';
+import type { AnnotatedStoryFn, Args, ComponentAnnotations, StoryAnnotations } from '@storybook/csf';
+
+/**
+ * A helper that returns a function to bind a Storybook story to a ViewTemplate.
+ *
+ * @param template - The ViewTemplate to render
+ * @returns - a function to bind a Storybook story
+ */
+export function renderComponent<TArgs = Args>(
+  template: ViewTemplate,
+): (args: TArgs) => Element | DocumentFragment | null {
+  return function (args) {
+    const storyFragment = new DocumentFragment();
+    template.render(args, storyFragment);
+    if (storyFragment.childElementCount === 1) {
+      return storyFragment.firstElementChild;
+    }
+    return storyFragment;
+  };
+}
+
+/**
+ * A helper that returns a function to bind a Storybook story to a ViewTemplate.
+ */
+export type FASTFramework = {
+  component: typeof FASTElement;
+  storyResult: FASTElement | Element | DocumentFragment;
+};
+
+/**
+ * Metadata to configure the stories for a component.
+ */
+export type Meta<TArgs = Args> = ComponentAnnotations<FASTFramework, Omit<TArgs, keyof FASTElement>>;
+
+/**
+ * Story function that represents a CSFv3 component example.
+ */
+export declare type StoryObj<TArgs = Args> = StoryAnnotations<FASTFramework, TArgs>;
+
+/**
+ * Story function that represents a CSFv2 component example.
+ */
+export declare type StoryFn<TArgs = Args> = AnnotatedStoryFn<FASTFramework, TArgs>;
+
+/**
+ * Story function that represents a CSFv2 component example.
+ *
+ * NOTE that in Storybook 7.0, this type will be renamed to `StoryFn` and replaced by the current `StoryObj` type.
+ */
+export declare type Story<TArgs = Args> = StoryFn<StoryArgs<TArgs>>;
+
+/**
+ * Combined Storybook story args.
+ */
+export type StoryArgs<TArgs = Args> = Partial<Omit<TArgs, keyof FASTElement>> & Args;

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

@@ -0,0 +1,5 @@
+export const FluentDesignSystem = Object.freeze({
+  prefix: 'fluent',
+  shadowRootMode: 'open',
+  registry: customElements,
+});

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

@@ -1 +1 @@
-export * from './index';
+export * from './index.js';

packages/web-components/src/index.ts

@@ -1 +1 @@
-export const empty = '';
+export * from './text/index.js';

packages/web-components/src/text/define.ts

@@ -0,0 +1,4 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { definition } from './text.definition.js';
+
+definition.define(FluentDesignSystem.registry);

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

@@ -0,0 +1,5 @@
+export * from './text.js';
+export * from './text.options.js';
+export { template as TextTemplate } from './text.template.js';
+export { styles as TextStyles } from './text.styles.js';
+export { definition as TextDefinition } from './text.definition.js';

packages/web-components/src/text/text.definition.ts

@@ -0,0 +1,18 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { Text } from './text.js';
+import { styles } from './text.styles.js';
+import { template } from './text.template.js';
+
+/**
+ * The Fluent Text Element.
+ *
+ *
+ * @public
+ * @remarks
+ * HTML Element: \<fluent-text\>
+ */
+export const definition = Text.compose({
+  name: `${FluentDesignSystem.prefix}-text`,
+  template,
+  styles,
+});

packages/web-components/src/text/text.options.ts

@@ -0,0 +1,75 @@
+import { ValuesOf } from '@microsoft/fast-foundation';
+
+/**
+ * TextSize constants
+ * @public
+ */
+export const TextSize = {
+  _100: '100',
+  _200: '200',
+  _300: '300',
+  _400: '400',
+  _500: '500',
+  _600: '600',
+  _700: '700',
+  _800: '800',
+  _900: '900',
+  _1000: '1000',
+} as const;
+
+/**
+ * The type for TextSize
+ * The font size and line height based on the theme tokens
+ * @public
+ */
+export type TextSize = ValuesOf<typeof TextSize>;
+
+/**
+ * TextFont Constants
+ * @public
+ */
+export const TextFont = {
+  base: 'base',
+  numeric: 'numeric',
+  monospace: 'monospace',
+} as const;
+
+/**
+ * Applies font family to the content
+ * @public
+ */
+export type TextFont = ValuesOf<typeof TextFont>;
+
+/**
+ * TextWeight Constants
+ * @public
+ */
+export const TextWeight = {
+  medium: 'medium',
+  regular: 'regular',
+  semibold: 'semibold',
+  bold: 'bold',
+} as const;
+
+/**
+ * Applies font weight to the content
+ * @public
+ */
+export type TextWeight = ValuesOf<typeof TextWeight>;
+
+/**
+ * TextAlign Constants
+ * @public
+ */
+export const TextAlign = {
+  start: 'start',
+  end: 'end',
+  center: 'center',
+  justify: 'justify',
+} as const;
+
+/**
+ * Aligns the content
+ * @public
+ */
+export type TextAlign = ValuesOf<typeof TextAlign>;