chore(fab): fab fast foundation (VIV-2023)

apps/docs/tsconfig.json

@@ -6,6 +6,7 @@
 		"strict": true,
 		"noImplicitOverride": true,
 		"noImplicitReturns": true,
+		"noUnusedLocals": true,
 		"noFallthroughCasesInSwitch": true,
 		"esModuleInterop": true,
 		"resolveJsonModule": true

libs/components/cem.config.mjs

@@ -9,6 +9,7 @@ export default {
 	/** Globs to analyze */
 	globs: [
 		'libs/components/src/lib/**/*.ts',
+		'libs/components/src/shared/foundation/**/*.ts',
 		'libs/components/src/shared/date-picker/date-picker-base.ts',
 	],
 	/** Globs to exclude */

libs/components/src/lib/breadcrumb-item/breadcrumb-item.ts

@@ -1,6 +1,6 @@
 import { attr, observable } from '@microsoft/fast-element';
 import { applyMixins, FoundationElement } from '@microsoft/fast-foundation';
-import { Anchor } from '../../shared/patterns/anchor';
+import { Anchor } from '../../shared/foundation/anchor/anchor';
 
 /**
  * @public

libs/components/src/lib/fab/fab.ts

@@ -1,9 +1,6 @@
-import {
-	applyMixins,
-	Button as FoundationButton,
-} from '@microsoft/fast-foundation';
 import { attr } from '@microsoft/fast-element';
-
+import { applyMixins } from '@microsoft/fast-foundation';
+import { FoundationButton } from '../../shared/foundation/button';
 import type { Connotation, Size } from '../enums.js';
 import { AffixIconWithTrailing } from '../../shared/patterns/affix';
 

libs/components/src/shared/patterns/anchor.ts → libs/components/src/shared/foundation/anchor/anchor.ts

@@ -1,6 +1,6 @@
 import { attr } from '@microsoft/fast-element';
 import { applyMixins } from '@microsoft/fast-foundation';
-import { ARIAGlobalStatesAndProperties } from './aria-global';
+import { ARIAGlobalStatesAndProperties } from '../patterns/aria-global';
 
 /**
  * Based largely on the {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a | <a> element }.

libs/components/src/shared/foundation/button/REAME.md

@@ -0,0 +1,142 @@
+---
+id: button
+title: fast-button
+sidebar_label: button
+custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-foundation/src/button/README.md
+description: fast-button is a web component implementation of a button element.
+---
+
+As defined by the [W3C](https://w3c.github.io/aria-practices/#button):
+
+> A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.
+
+`fast-button` is a web component implementation of an [HTML button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button). The `fast-components` button supports several visual appearances (accent, lightweight, neutral, outline, stealth).
+
+## Setup
+
+```ts
+import {
+	provideFASTDesignSystem,
+	fastButton,
+} from '@microsoft/fast-components';
+
+provideFASTDesignSystem().register(fastButton());
+```
+
+## Usage
+
+```html live
+<fast-button appearance="primary">Submit</fast-button>
+```
+
+## Create your own design
+
+```ts
+import { Button, buttonTemplate as template } from '@microsoft/fast-foundation';
+import { buttonStyles as styles } from './my-button.styles';
+
+export const myButton = Button.compose({
+	baseName: 'button',
+	template,
+	styles,
+	shadowOptions: {
+		delegatesFocus: true,
+	},
+});
+```
+
+:::note
+This component is built with the expectation that focus is delegated to the button element rendered into the shadow DOM.
+:::
+
+## API
+
+### class: `Button`
+
+#### Superclass
+
+| Name                   | Module                                | Package |
+| ---------------------- | ------------------------------------- | ------- |
+| `FormAssociatedButton` | /src/button/button.form-associated.js |         |
+
+#### Fields
+
+| Name                    | Privacy | Type                                         | Default | Description                                                                                                                                                                         | Inherited From       |
+| ----------------------- | ------- | -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `autofocus`             | public  | `boolean`                                    |         | Determines if the element should receive document focus on page load.                                                                                                               |                      |
+| `formId`                | public  | `string`                                     |         | The id of a form to associate the element to.                                                                                                                                       |                      |
+| `formaction`            | public  | `string`                                     |         | See [`<button>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) for more details.                                                                        |                      |
+| `formenctype`           | public  | `string`                                     |         | See [`<button>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) for more details.                                                                        |                      |
+| `formmethod`            | public  | `string`                                     |         | See [`<button>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) for more details.                                                                        |                      |
+| `formnovalidate`        | public  | `boolean`                                    |         | See [`<button>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) for more details.                                                                        |                      |
+| `formtarget`            | public  | `"_self" or "_blank" or "_parent" or "_top"` |         | See [`<button>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) for more details.                                                                        |                      |
+| `type`                  | public  | `"submit" or "reset" or "button"`            |         | The button type.                                                                                                                                                                    |                      |
+| `defaultSlottedContent` | public  | `HTMLElement[]`                              |         | Default slotted content                                                                                                                                                             |                      |
+| `control`               | public  | `HTMLButtonElement`                          |         |                                                                                                                                                                                     |                      |
+| `proxy`                 |         |                                              |         |                                                                                                                                                                                     | FormAssociatedButton |
+| `$presentation`         | public  | `ComponentPresentation or null`              |         | A property which resolves the ComponentPresentation instance for the current component.                                                                                             | FoundationElement    |
+| `template`              | public  | `ElementViewTemplate or void or null`        |         | Sets the template of the element instance. When undefined, the element will attempt to resolve the template from the associated presentation or custom element definition.          | FoundationElement    |
+| `styles`                | public  | `ElementStyles or void or null`              |         | Sets the default styles for the element instance. When undefined, the element will attempt to resolve default styles from the associated presentation or custom element definition. | FoundationElement    |
+
+#### Methods
+
+| Name              | Privacy   | Description                                       | Parameters | Return | Inherited From    |
+| ----------------- | --------- | ------------------------------------------------- | ---------- | ------ | ----------------- |
+| `validate`        | public    | {@inheritDoc (FormAssociated:interface).validate} |            | `void` |                   |
+| `templateChanged` | protected |                                                   |            | `void` | FoundationElement |
+| `stylesChanged`   | protected |                                                   |            | `void` | FoundationElement |
+
+#### Attributes
+
+| Name          | Field          | Inherited From |
+| ------------- | -------------- | -------------- |
+|               | autofocus      |                |
+| `form`        | formId         |                |
+| `formaction`  | formaction     |                |
+| `formenctype` | formenctype    |                |
+| `formmethod`  | formmethod     |                |
+|               | formnovalidate |                |
+| `formtarget`  | formtarget     |                |
+| `type`        | type           |                |
+
+#### CSS Parts
+
+| Name      | Description                         |
+| --------- | ----------------------------------- |
+| `control` | The button element                  |
+| `content` | The element wrapping button content |
+
+#### Slots
+
+| Name    | Description                                             |
+| ------- | ------------------------------------------------------- |
+| `start` | Content which can be provided before the button content |
+| `end`   | Content which can be provided after the button content  |
+|         | The default slot for button content                     |
+
+<hr/>
+
+### class: `DelegatesARIAButton`
+
+#### Fields
+
+| Name           | Privacy | Type                                             | Default | Description                                                          | Inherited From |
+| -------------- | ------- | ------------------------------------------------ | ------- | -------------------------------------------------------------------- | -------------- |
+| `ariaExpanded` | public  | `"true" or "false" or string or null`            |         | See https://www.w3.org/WAI/PF/aria/roles#button for more information |                |
+| `ariaPressed`  | public  | `"true" or "false" or "mixed" or string or null` |         | See https://www.w3.org/WAI/PF/aria/roles#button for more information |                |
+
+#### Attributes
+
+| Name            | Field        | Inherited From |
+| --------------- | ------------ | -------------- |
+| `aria-expanded` | ariaExpanded |                |
+| `aria-pressed`  | ariaPressed  |                |
+
+<hr/>
+
+## Additional resources
+
+- [Component explorer examples](https://explore.fast.design/components/fast-button)
+- [Component technical specification](https://github.com/microsoft/fast/blob/master/packages/web-components/fast-foundation/src/button/button.spec.md)
+- [W3C Component Aria Practices](https://w3c.github.io/aria-practices/#button)
+- [Open UI Analysis](https://open-ui.org/components/button)

libs/components/src/shared/foundation/button/button.form-associated.ts

@@ -0,0 +1,14 @@
+import { FormAssociated, FoundationElement } from '@microsoft/fast-foundation';
+
+class _FoundationButton extends FoundationElement {}
+/* eslint-disable-next-line @typescript-eslint/naming-convention */
+interface _FoundationButton extends FormAssociated {}
+
+/**
+ * A form-associated base class for the {@link @microsoft/fast-foundation#(Button:class)} component.
+ *
+ * @internal
+ */
+export class FormAssociatedButton extends FormAssociated(_FoundationButton) {
+	proxy = document.createElement('input');
+}