feat: add slot event part docs to foundation (microsoft#5912)

* add docs for accordion through breadcrumb-item * update through listbox option * updates through search * add select and skeleton * add update through text-area * add initial jsdocs for foundation elements * update docs * Change files * fix: add custom tags to tsdoc (microsoft#5920) * Add custom tags to tsdoc * PR feedback * fix misspelled part and incorrect syntax for non-default slots * fix missing tsdoc in components * Change files Co-authored-by: William Wagner <44823142+williamw2@users.noreply.github.com>
codef0rmerz · May 2, 2022 · 8327524 · 8327524
1 parent a356d1d
commit 8327524
Show file tree

Hide file tree

Showing 77 changed files with 1,021 additions and 9 deletions.
diff --git a/change/@microsoft-fast-components-8dd495d3-f291-4cb6-a5ab-d95535bd0c7d.json b/change/@microsoft-fast-components-8dd495d3-f291-4cb6-a5ab-d95535bd0c7d.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "add initial jsdocs for fast-components",
+  "packageName": "@microsoft/fast-components",
+  "email": "chhol@microsoft.com",
+  "dependentChangeType": "none"
+}
diff --git a/change/@microsoft-fast-foundation-1afd0c87-ccc9-42fe-a153-d620dfa98e30.json b/change/@microsoft-fast-foundation-1afd0c87-ccc9-42fe-a153-d620dfa98e30.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "add initial jsdocs for foundation elements",
+  "packageName": "@microsoft/fast-foundation",
+  "email": "chhol@microsoft.com",
+  "dependentChangeType": "none"
+}
diff --git a/packages/web-components/fast-components/tsdoc.json b/packages/web-components/fast-components/tsdoc.json
@@ -0,0 +1,44 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"],
+  "tagDefinitions": [
+    {
+      "tagName": "@slot",
+      "syntaxKind": "block",
+      "allowMultiple": true
+    },
+    {
+      "tagName": "@csspart",
+      "syntaxKind": "block",
+      "allowMultiple": true
+    },
+    {
+      "tagName": "@cssprop",
+      "syntaxKind": "block",
+      "allowMultiple": true
+    },
+    {
+      "tagName": "@cssproperty",
+      "syntaxKind": "block",
+      "allowMultiple": true
+    },
+    {
+      "tagName": "@event",
+      "syntaxKind": "block",
+      "allowMultiple": true
+    },
+    {
+      "tagName": "@fires",
+      "syntaxKind": "block",
+      "allowMultiple": true
+    }
+  ],
+  "supportForTags": {
+    "@slot": true,
+    "@csspart": true,
+    "@cssprop": true,
+    "@cssproperty": true,
+    "@event": true,
+    "@fires": true
+  }
+}
diff --git a/packages/web-components/fast-foundation/src/accordion-item/accordion-item.ts b/packages/web-components/fast-foundation/src/accordion-item/accordion-item.ts
@@ -22,6 +22,22 @@ export type AccordionItemOptions = FoundationElementDefinition &
 
 /**
  * An individual item in an {@link @microsoft/fast-foundation#(Accordion:class) }.
+ *
+ * @slot start - Content which can be provided between the heading and the icon
+ * @slot end - Content which can be provided between the start slot and icon
+ * @slot heading - Content which serves as the accordion item heading and text of the expand button
+ * @slot - The default slot for accordion item content
+ * @slot expanded-icon - The expanded icon
+ * @slot collapsed-icon - The collapsed icon
+ * @fires change - Fires a custom 'change' event when the button is invoked
+ * @csspart heading - Wraps the button
+ * @csspart button - The button which serves to invoke the item
+ * @csspart heading-content - Wraps the slot for the heading content within the button
+ * @csspart icon - The icon container
+ * @csspart expanded-icon - The expanded icon slot
+ * @csspart collapsed-icon - The collapsed icon
+ * @csspart region - The wrapper for the accordion item content
+ *
  * @public
  */
 export class AccordionItem extends FoundationElement {

diff --git a/packages/web-components/fast-foundation/src/accordion/README.md b/packages/web-components/fast-foundation/src/accordion/README.md
@@ -127,12 +127,24 @@ export const myAccordionItem = AccordionItem.compose<AccordionItemOptions>({
 | `templateChanged` | protected |             |            | `void` | FoundationElement |
 | `stylesChanged`   | protected |             |            | `void` | FoundationElement |
 
+#### Events
+
+| Name     | Type | Description                                                | Inherited From |
+| -------- | ---- | ---------------------------------------------------------- | -------------- |
+| `change` |      | Fires a custom 'change' event when the active item changes |                |
+
 #### Attributes
 
 | Name          | Field      | Inherited From |
 | ------------- | ---------- | -------------- |
 | `expand-mode` | expandmode |                |
 
+#### CSS Parts
+
+| Name   | Description                      |
+| ------ | -------------------------------- |
+| `item` | The slot for the accordion items |
+
 <hr/>
 
 
@@ -163,6 +175,12 @@ export const myAccordionItem = AccordionItem.compose<AccordionItemOptions>({
 | `templateChanged` | protected |             |            | `void` | FoundationElement |
 | `stylesChanged`   | protected |             |            | `void` | FoundationElement |
 
+#### Events
+
+| Name     | Type | Description                                              | Inherited From |
+| -------- | ---- | -------------------------------------------------------- | -------------- |
+| `change` |      | Fires a custom 'change' event when the button is invoked |                |
+
 #### Attributes
 
 | Name            | Field        | Inherited From |
@@ -171,6 +189,29 @@ export const myAccordionItem = AccordionItem.compose<AccordionItemOptions>({
 |                 | expanded     |                |
 | `id`            | id           |                |
 
+#### CSS Parts
+
+| Name              | Description                                              |
+| ----------------- | -------------------------------------------------------- |
+| `heading`         | Wraps the button                                         |
+| `button`          | The button which serves to invoke the item               |
+| `heading-content` | Wraps the slot for the heading content within the button |
+| `icon`            | The icon container                                       |
+| `expanded-icon`   | The expanded icon slot                                   |
+| `collapsed-icon`  | The collapsed icon                                       |
+| `region`          | The wrapper for the accordion item content               |
+
+#### Slots
+
+| Name             | Description                                                                      |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `start`          | Content which can be provided between the heading and the icon                   |
+| `end`            | Content which can be provided between the start slot and icon                    |
+| `heading`        | Content which serves as the accordion item heading and text of the expand button |
+|                  | The default slot for accordion item content                                      |
+| `expanded-icon`  | The expanded icon                                                                |
+| `collapsed-icon` | The collapsed icon                                                               |
+
 <hr/>
 
 

diff --git a/packages/web-components/fast-foundation/src/accordion/accordion.ts b/packages/web-components/fast-foundation/src/accordion/accordion.ts
@@ -28,6 +28,9 @@ export enum AccordionExpandMode {
 /**
  * An Accordion Custom HTML Element
  * Implements {@link https://www.w3.org/TR/wai-aria-practices-1.1/#accordion | ARIA Accordion}.
+ *
+ * @fires change - Fires a custom 'change' event when the active item changes
+ * @csspart item - The slot for the accordion items
  * @public
  *
  * @remarks

diff --git a/packages/web-components/fast-foundation/src/anchor/README.md b/packages/web-components/fast-foundation/src/anchor/README.md
@@ -103,6 +103,21 @@ This component is built with the expectation that focus is delegated to the anch
 | `target`         | target         |                |
 | `type`           | type           |                |
 
+#### CSS Parts
+
+| Name      | Description                         |
+| --------- | ----------------------------------- |
+| `control` | The anchor element                  |
+| `content` | The element wrapping anchor content |
+
+#### Slots
+
+| Name    | Description                                             |
+| ------- | ------------------------------------------------------- |
+| `start` | Content which can be provided before the anchor content |
+| `end`   | Content which can be provided after the anchor content  |
+|         | The default slot for anchor content                     |
+
 <hr/>
 
 ### class: `DelegatesARIALink`

diff --git a/packages/web-components/fast-foundation/src/anchor/anchor.ts b/packages/web-components/fast-foundation/src/anchor/anchor.ts
@@ -20,6 +20,12 @@ export type AnchorOptions = FoundationElementDefinition & StartEndOptions;
  * An Anchor Custom HTML Element.
  * Based largely on the {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a | <a> element }.
  *
+ * @slot start - Content which can be provided before the anchor content
+ * @slot end - Content which can be provided after the anchor content
+ * @slot - The default slot for anchor content
+ * @csspart control - The anchor element
+ * @csspart content - The element wrapping anchor content
+ *
  * @public
  */
 export class Anchor extends FoundationElement {

diff --git a/packages/web-components/fast-foundation/src/anchored-region/README.md b/packages/web-components/fast-foundation/src/anchored-region/README.md
@@ -118,6 +118,13 @@ export const myAnchoredRegion = AnchoredRegion.compose({
 | `templateChanged` | protected |             |            | `void` | FoundationElement |
 | `stylesChanged`   | protected |             |            | `void` | FoundationElement |
 
+#### Events
+
+| Name             | Type | Description                                                         | Inherited From |
+| ---------------- | ---- | ------------------------------------------------------------------- | -------------- |
+| `loaded`         |      | Fires a custom 'loaded' event when the region is loaded and visible |                |
+| `positionchange` |      | Fires a custom 'positionchange' event when the position has changed |                |
+
 #### Attributes
 
 | Name                          | Field                     | Inherited From |
@@ -139,6 +146,12 @@ export const myAnchoredRegion = AnchoredRegion.compose({
 | `fixed-placement`             | fixedPlacement            |                |
 | `auto-update-mode`            | autoUpdateMode            |                |
 
+#### Slots
+
+| Name | Description                      |
+| ---- | -------------------------------- |
+|      | The default slot for the content |
+
 <hr/>
 
 

diff --git a/packages/web-components/fast-foundation/src/anchored-region/anchored-region.ts b/packages/web-components/fast-foundation/src/anchored-region/anchored-region.ts
@@ -74,6 +74,10 @@ interface Dimension {
 /**
  * An anchored region Custom HTML Element.
  *
+ * @slot - The default slot for the content
+ * @fires loaded - Fires a custom 'loaded' event when the region is loaded and visible
+ * @fires positionchange - Fires a custom 'positionchange' event when the position has changed
+ *
  * @public
  */
 export class AnchoredRegion extends FoundationElement {

diff --git a/packages/web-components/fast-foundation/src/avatar/README.md b/packages/web-components/fast-foundation/src/avatar/README.md
@@ -158,6 +158,23 @@ This component is built with the expectation that focus is delegated to the anch
 | `link`  | link  |                |
 | `shape` | shape |                |
 
+#### CSS Parts
+
+| Name        | Description                           |
+| ----------- | ------------------------------------- |
+| `backplate` | The wrapping container for the avatar |
+| `link`      | The avatar link                       |
+| `media`     | The media slot                        |
+| `content`   | The default slot                      |
+
+#### Slots
+
+| Name    | Description                                                   |
+| ------- | ------------------------------------------------------------- |
+| `media` | Used for media such as an image                               |
+|         | The default slot for avatar text, commonly a name or initials |
+| `badge` | Used to provide a badge, such as a status badge               |
+
 <hr/>
 
 

diff --git a/packages/web-components/fast-foundation/src/avatar/avatar.ts b/packages/web-components/fast-foundation/src/avatar/avatar.ts
@@ -17,6 +17,14 @@ export type AvatarOptions = FoundationElementDefinition & {
 /**
  * An Avatar Custom HTML Element
  *
+ * @slot media - Used for media such as an image
+ * @slot - The default slot for avatar text, commonly a name or initials
+ * @slot badge - Used to provide a badge, such as a status badge
+ * @csspart backplate - The wrapping container for the avatar
+ * @csspart link - The avatar link
+ * @csspart media - The media slot
+ * @csspart content - The default slot
+ *
  * @public
  */
 export class Avatar extends FoundationElement {

diff --git a/packages/web-components/fast-foundation/src/badge/README.md b/packages/web-components/fast-foundation/src/badge/README.md
@@ -90,6 +90,18 @@ export const myBadge = Badge.compose({
 | `color` | color    |                |
 |         | circular |                |
 
+#### CSS Parts
+
+| Name      | Description                                                      |
+| --------- | ---------------------------------------------------------------- |
+| `control` | The element representing the badge, which wraps the default slot |
+
+#### Slots
+
+| Name | Description                    |
+| ---- | ------------------------------ |
+|      | The default slot for the badge |
+
 <hr/>
 
 

diff --git a/packages/web-components/fast-foundation/src/badge/badge.ts b/packages/web-components/fast-foundation/src/badge/badge.ts
@@ -3,6 +3,8 @@ import { FoundationElement } from "../foundation-element/foundation-element.js";
 
 /**
  * A Badge Custom HTML Element.
+ * @slot - The default slot for the badge
+ * @csspart control - The element representing the badge, which wraps the default slot
  *
  * @public
  */

diff --git a/packages/web-components/fast-foundation/src/breadcrumb-item/breadcrumb-item.ts b/packages/web-components/fast-foundation/src/breadcrumb-item/breadcrumb-item.ts
@@ -6,6 +6,12 @@ import { applyMixins } from "../utilities/apply-mixins.js";
 
 /**
  * Breadcrumb Item configuration options
+ *
+ * @slot - The default slot for when no href is provided or for providing your own custom elements
+ * @slot separator - The slot for providing a custom separator
+ * @csspart listitem - The wrapping container for the item, represents a semantic listitem
+ * @csspart separator - The wrapping element for the separator
+ *
  * @public
  */
 export type BreadcrumbItemOptions = FoundationElementDefinition &

diff --git a/packages/web-components/fast-foundation/src/breadcrumb/README.md b/packages/web-components/fast-foundation/src/breadcrumb/README.md
@@ -123,6 +123,18 @@ This component is built with the expectation that focus is delegated to the anch
 | `templateChanged`               | protected |             |            | `void` | FoundationElement |
 | `stylesChanged`                 | protected |             |            | `void` | FoundationElement |
 
+#### CSS Parts
+
+| Name   | Description                            |
+| ------ | -------------------------------------- |
+| `list` | The element wrapping the slotted items |
+
+#### Slots
+
+| Name | Description                               |
+| ---- | ----------------------------------------- |
+|      | The default slot for the breadcrumb items |
+
 <hr/>
 
 

diff --git a/packages/web-components/fast-foundation/src/breadcrumb/breadcrumb.ts b/packages/web-components/fast-foundation/src/breadcrumb/breadcrumb.ts
@@ -4,6 +4,8 @@ import { FoundationElement } from "../foundation-element/foundation-element.js";
 
 /**
  * A Breadcrumb Custom HTML Element.
+ * @slot - The default slot for the breadcrumb items
+ * @csspart list - The element wrapping the slotted items
  *
  * @public
  */

diff --git a/packages/web-components/fast-foundation/src/button/README.md b/packages/web-components/fast-foundation/src/button/README.md
@@ -105,6 +105,21 @@ This component is built with the expectation that focus is delegated to the butt
 | `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`

diff --git a/packages/web-components/fast-foundation/src/button/button.ts b/packages/web-components/fast-foundation/src/button/button.ts
@@ -18,6 +18,12 @@ export type ButtonOptions = FoundationElementDefinition & StartEndOptions;
  * A Button Custom HTML Element.
  * Based largely on the {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button | <button> element }.
  *
+ * @slot start - Content which can be provided before the button content
+ * @slot end - Content which can be provided after the button content
+ * @slot - The default slot for button content
+ * @csspart control - The button element
+ * @csspart content - The element wrapping button content
+ *
  * @public
  */
 export class Button extends FormAssociatedButton {

diff --git a/packages/web-components/fast-foundation/src/calendar/calendar.ts b/packages/web-components/fast-foundation/src/calendar/calendar.ts
@@ -69,6 +69,10 @@ export type CalendarOptions = FoundationElementDefinition &
 
 /**
  * Calendar component
+ *
+ * @slot - The default slot for calendar content
+ * @fires dateselected - Fires a custom 'dateselected' event when Enter is invoked via keyboard on a date
+ *
  * @public
  */
 export class Calendar extends FoundationElement {