From fe5c09c47f726984dcaadaa812362e52691caca7 Mon Sep 17 00:00:00 2001 From: Brian Brady Date: Tue, 21 Feb 2023 15:10:01 -0800 Subject: [PATCH 1/5] divides accordion and accordion item readme --- .../src/accordion-item/README.md | 132 ++++++++++++++++++ .../web-components/src/accordion/README.md | 96 +------------ 2 files changed, 137 insertions(+), 91 deletions(-) create mode 100644 packages/web-components/src/accordion-item/README.md diff --git a/packages/web-components/src/accordion-item/README.md b/packages/web-components/src/accordion-item/README.md new file mode 100644 index 00000000000000..ebb3744d5799c2 --- /dev/null +++ b/packages/web-components/src/accordion-item/README.md @@ -0,0 +1,132 @@ +## Class: `AccordionItem` + +As defined by the [W3C](https://w3c.github.io/aria-practices/#accordion): + +> An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content. The headings function as controls that enable users to reveal or hide their associated sections of content. Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page. + +
+ +## **Design Spec** + +[Link to Accordion Item Design Spec in Figma](https://www.figma.com/file/7X3Tgd3fTurii3FACrfhzo/Accordion?node-id=2777%3A42482&t=jHgc4PXRMQH6rPmy-0) + +
+ +## **Engineering Spec** + +Fluent WC3 Accordion Item extends from the [FAST Accordion Item](https://explore.fast.design/components/fast-accordion-item) and is intended to be as close to the Fluent UI React 9 Accordion implementation as possible. However, due to the nature of web components there will not be 100% parity between the two. + +
+ +### **Variables** + +| Name | Description | Type | +| --------------------------------- | -------------------------- | --------------------------------------------------------------------------------- | +| `AccordionItemSize` | Expand modes for Accordion | `{ small: "small", medium: "medium", large: "large", extraLarge: "extra-large" }` | +| `AccordionItemExpandIconPosition` | Expand icon position | `{ start: "start", end: "end" }` | + +
+ +### **Fields** + +| Name | Privacy | Type | Default | Description | Inherited From | +| -------------------- | ------- | --------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | -------------- | +| `headinglevel` | public | `1 or 2 or 3 or 4 or 5 or 6` | `2` | Configures the [level](https://www.w3.org/TR/wai-aria-1.1/#aria-level) of the heading element. | | +| `expanded` | public | `boolean` | `false` | Expands or collapses the item. | | +| `disabled` | public | `boolean` | `false` | Disables an accordion item | | +| `id` | public | `string` | | The item ID | | +| `size` | public | `AccordionItemSize` | `medium` | The font size of the AccordionItem header. | +| `block` | public | `boolean` | `true` | Sets the width of the focus state. | +| `expandIconPosition` | public | `AccordionItemExpandIconPosition` | `start` | Sets the position of the expand icon | + +
+ +### **Events** + +| Name | Type | Description | Inherited From | +| -------- | ---- | -------------------------------------------------------- | -------------- | +| `change` | | Fires a custom 'change' event when the button is invoked | | + +
+ +### **Attributes** + +| Name | Field | +| -------------------- | ------------------ | +| `heading-level` | headinglevel | +| | expanded | +| | disabled | +| | block | +| `id` | id | +| `expandIconPosition` | expandIconPosition | +| `size` | size | + +
+ +### **Slots** + +| Name | Description | +| ---------------- | -------------------------------------------------------------------------------- | +| `start` | The slot used for a presentation icon when expanded | +| `end` | The slot used for a presentation icon when collapsed | +| `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 slot used for a custom expanded icon | +| `collapsed-icon` | The slot used for a custom collapsed icon | + +
+
+
+ +## **Accessibility** + +[W3 Accordion Item Spec](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) + +
+ +### **WAI-ARIA Roles, States, and Properties** + +- `role = "button"` + - The title of each accordion header is contained in an element with role button. +- `role = "heading"` + - Each accordion header button is wrapped in an element with role heading that has a value set for aria-level that is appropriate for the information architecture of the page. +- `aria-expanded` + - If the accordion panel associated with an accordion header is visible, the header button element has aria-expanded set to true. If the panel is not visible, aria-expanded is set to false. +- `aria-controls` + - The accordion header button element has aria-controls set to the ID of the element containing the accordion panel content. +- `aria-disabled` + - If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true. + +
+
+
+ +## **Preparation** + +
+ +### **Fluent Web Component v3 v.s Fluent React 9** + +
+ +**Component and Slot Mapping** + +| Fluent UI React 9 | Fluent Web Components 3 | +| ------------------- | ------------------------- | +| `` | `` | +| `` | `named slot = "heading"` | +| `` | `default slotted content` | + +
+ +**Property Mapping** +| Fluent UI React 9 | Fluent Web Components 3 | Description of difference | +|---------------------------|---------------------------|------------------------------------------------------------------------------------------| +| `defaultOpenItems: number`| `expand: boolean` | _FuiR9_ `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. +| `multiple: boolean` | `expandmode: "single"` | `"multiple"`| | +| `size` | `size` | +| `as: 'h1'` | `'h2'` | `'h3'` | `'h4'` | `'h5'` | `'h6'` | `headinglevel: 1` | `2` | `3` | `4` | `5` | `6` | `as` property sets a wrapper around the `AccordionItem` header with the corresponding header tag ( `h1`, `h2`, etc. )
`headinglevel` sets the `aria-level` attribute to the corresponding heading level. +| `disabled` | `disabled` | +| `expandIconPosition` | `expandIconPosition` | +| `expandIcon` | `named slot: collapsed-icon` + `expanded-icon` | `expandIcon` is a prop that is passed a ternary to render the appropriate icon.
`collapsed-icon` and `expanded-icon` are named slots to supply the appropriate icons. +| `icon` | `named slot: start` + `end` | `icon` is a property set on the `AccordionHeader` through which an icon is passed
`start` and `end` are named slots through which to supply a presentation icon. diff --git a/packages/web-components/src/accordion/README.md b/packages/web-components/src/accordion/README.md index 7756994649bb78..5e4018478db9fb 100644 --- a/packages/web-components/src/accordion/README.md +++ b/packages/web-components/src/accordion/README.md @@ -1,4 +1,4 @@ -# Accordion + Accordion Item +# Accordion As defined by the [W3C](https://w3c.github.io/aria-practices/#accordion): @@ -14,7 +14,7 @@ As defined by the [W3C](https://w3c.github.io/aria-practices/#accordion): ## **Engineering Spec** -Fluent WC3 Accordion extends from the FAST Accordion [FAST Accordion](https://explore.fast.design/components/fast-accordion) and is intended to be as close to the Fluent UI React 9 Menu implementation as possible. However, due to the nature of web components there will not be 100% parity between the two. +Fluent WC3 Accordion extends from the [FAST Accordion](https://explore.fast.design/components/fast-accordion) and is intended to be as close to the Fluent UI React 9 Accordion implementation as possible. However, due to the nature of web components there will not be 100% parity between the two.
@@ -67,70 +67,6 @@ Fluent WC3 Accordion extends from the FAST Accordion [FAST Accordion](https://ex
-## Class: `AccordionItem` - -
- -### **Variables** - -| Name | Description | Type | -| --------------------------------- | -------------------------- | --------------------------------------------------------------------------------- | -| `AccordionItemSize` | Expand modes for Accordion | `{ small: "small", medium: "medium", large: "large", extraLarge: "extra-large" }` | -| `AccordionItemExpandIconPosition` | Expand icon position | `{ start: "start", end: "end" }` | - -
- -### **Fields** - -| Name | Privacy | Type | Default | Description | Inherited From | -| -------------------- | ------- | --------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | -------------- | -| `headinglevel` | public | `1 or 2 or 3 or 4 or 5 or 6` | `2` | Configures the [level](https://www.w3.org/TR/wai-aria-1.1/#aria-level) of the heading element. | | -| `expanded` | public | `boolean` | `false` | Expands or collapses the item. | | -| `disabled` | public | `boolean` | `false` | Disables an accordion item | | -| `id` | public | `string` | | The item ID | | -| `size` | public | `AccordionItemSize` | `medium` | The font size of the AccordionItem header. | -| `block` | public | `boolean` | `true` | Sets the width of the focus state. | -| `expandIconPosition` | public | `AccordionItemExpandIconPosition` | `start` | Sets the position of the expand icon | - -
- -### **Events** - -| Name | Type | Description | Inherited From | -| -------- | ---- | -------------------------------------------------------- | -------------- | -| `change` | | Fires a custom 'change' event when the button is invoked | | - -
- -### **Attributes** - -| Name | Field | -| -------------------- | ------------------ | -| `heading-level` | headinglevel | -| | expanded | -| | disabled | -| | block | -| `id` | id | -| `expandIconPosition` | expandIconPosition | -| `size` | size | - -
- -### **Slots** - -| Name | Description | -| ---------------- | -------------------------------------------------------------------------------- | -| `start` | The slot used for a presentation icon when expanded | -| `end` | The slot used for a presentation icon when collapsed | -| `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 slot used for a custom expanded icon | -| `collapsed-icon` | The slot used for a custom collapsed icon | - -
-
-
- ## **Accessibility** [W3 Accordion Spec](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) @@ -139,17 +75,6 @@ Fluent WC3 Accordion extends from the FAST Accordion [FAST Accordion](https://ex ### **WAI-ARIA Roles, States, and Properties** -- `role = "button"` - - The title of each accordion header is contained in an element with role button. -- `role = "heading"` - - Each accordion header button is wrapped in an element with role heading that has a value set for aria-level that is appropriate for the information architecture of the page. -- `aria-expanded` - - If the accordion panel associated with an accordion header is visible, the header button element has aria-expanded set to true. If the panel is not visible, aria-expanded is set to false. -- `aria-controls` - - The accordion header button element has aria-controls set to the ID of the element containing the accordion panel content. -- `aria-disabled` - - If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true. -

@@ -164,23 +89,12 @@ Fluent WC3 Accordion extends from the FAST Accordion [FAST Accordion](https://ex **Component and Slot Mapping** -| Fluent UI React 9 | Fluent Web Components 3 | -| ------------------- | ------------------------- | -| `` | `` | -| `` | `` | -| `` | `named slot = "heading"` | -| `` | `default slotted content` | +| Fluent UI React 9 | Fluent Web Components 3 | +| ----------------- | ----------------------- | +| `` | `` |
**Property Mapping** | Fluent UI React 9 | Fluent Web Components 3 | Description of difference | |---------------------------|---------------------------|------------------------------------------------------------------------------------------| -| `defaultOpenItems: number`| `expand: boolean` | _FuiR9_ `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. -| `multiple: boolean` | `expandmode: "single"` | `"multiple"`| | -| `size` | `size` | -| `as: 'h1'` | `'h2'` | `'h3'` | `'h4'` | `'h5'` | `'h6'` | `headinglevel: 1` | `2` | `3` | `4` | `5` | `6` | `as` property sets a wrapper around the `AccordionItem` header with the corresponding header tag ( `h1`, `h2`, etc. )
`headinglevel` sets the `aria-level` attribute to the corresponding heading level. -| `disabled` | `disabled` | -| `expandIconPosition` | `expandIconPosition` | -| `expandIcon` | `named slot: collapsed-icon` + `expanded-icon` | `expandIcon` is a prop that is passed a ternary to render the appropriate icon.
`collapsed-icon` and `expanded-icon` are named slots to supply the appropriate icons. -| `icon` | `named slot: start` + `end` | `icon` is a property set on the `AccordionHeader` through which an icon is passed
`start` and `end` are named slots through which to supply a presentation icon. From 4a058e8cdf7aa3cebdf25f7a5425dd0190458cbf Mon Sep 17 00:00:00 2001 From: Brian Brady Date: Tue, 21 Feb 2023 15:15:42 -0800 Subject: [PATCH 2/5] updates accordion docs --- packages/web-components/src/accordion-item/README.md | 12 +++++++++++- packages/web-components/src/accordion/README.md | 6 ++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/packages/web-components/src/accordion-item/README.md b/packages/web-components/src/accordion-item/README.md index ebb3744d5799c2..d4002ff486574c 100644 --- a/packages/web-components/src/accordion-item/README.md +++ b/packages/web-components/src/accordion-item/README.md @@ -1,4 +1,4 @@ -## Class: `AccordionItem` +# Accordion Item As defined by the [W3C](https://w3c.github.io/aria-practices/#accordion): @@ -18,6 +18,16 @@ Fluent WC3 Accordion Item extends from the [FAST Accordion Item](https://explore
+## Class: `AccordionItem` + +
+ +### **Component Name** + +`AccordionItem` + +
+ ### **Variables** | Name | Description | Type | diff --git a/packages/web-components/src/accordion/README.md b/packages/web-components/src/accordion/README.md index 5e4018478db9fb..e39315cf5f99ea 100644 --- a/packages/web-components/src/accordion/README.md +++ b/packages/web-components/src/accordion/README.md @@ -22,6 +22,12 @@ Fluent WC3 Accordion extends from the [FAST Accordion](https://explore.fast.desi
+### **Component Name** + +`Accordion` + +
+ ### **Variables** | Name | Description | Type | From 3937d004a2833cbbc66ccec096b6e460bc1e0e6a Mon Sep 17 00:00:00 2001 From: Brian Brady Date: Wed, 22 Feb 2023 10:41:40 -0800 Subject: [PATCH 3/5] updates accordion docs --- packages/web-components/src/accordion-item/README.md | 5 ++--- packages/web-components/src/accordion/README.md | 4 +++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/packages/web-components/src/accordion-item/README.md b/packages/web-components/src/accordion-item/README.md index d4002ff486574c..ebe371be3ea91a 100644 --- a/packages/web-components/src/accordion-item/README.md +++ b/packages/web-components/src/accordion-item/README.md @@ -132,11 +132,10 @@ Fluent WC3 Accordion Item extends from the [FAST Accordion Item](https://explore **Property Mapping** | Fluent UI React 9 | Fluent Web Components 3 | Description of difference | |---------------------------|---------------------------|------------------------------------------------------------------------------------------| -| `defaultOpenItems: number`| `expand: boolean` | _FuiR9_ `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. -| `multiple: boolean` | `expandmode: "single"` | `"multiple"`| | +| `defaultOpenItems: number`| `expand: boolean` | `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. | `size` | `size` | | `as: 'h1'` | `'h2'` | `'h3'` | `'h4'` | `'h5'` | `'h6'` | `headinglevel: 1` | `2` | `3` | `4` | `5` | `6` | `as` property sets a wrapper around the `AccordionItem` header with the corresponding header tag ( `h1`, `h2`, etc. )
`headinglevel` sets the `aria-level` attribute to the corresponding heading level. | `disabled` | `disabled` | -| `expandIconPosition` | `expandIconPosition` | +| `expandIconPosition` | `expand-icon-position` | | `expandIcon` | `named slot: collapsed-icon` + `expanded-icon` | `expandIcon` is a prop that is passed a ternary to render the appropriate icon.
`collapsed-icon` and `expanded-icon` are named slots to supply the appropriate icons. | `icon` | `named slot: start` + `end` | `icon` is a property set on the `AccordionHeader` through which an icon is passed
`start` and `end` are named slots through which to supply a presentation icon. diff --git a/packages/web-components/src/accordion/README.md b/packages/web-components/src/accordion/README.md index e39315cf5f99ea..4238aef7d0e1e2 100644 --- a/packages/web-components/src/accordion/README.md +++ b/packages/web-components/src/accordion/README.md @@ -103,4 +103,6 @@ Fluent WC3 Accordion extends from the [FAST Accordion](https://explore.fast.desi **Property Mapping** | Fluent UI React 9 | Fluent Web Components 3 | Description of difference | -|---------------------------|---------------------------|------------------------------------------------------------------------------------------| +| ------------------------- | ------------------------------------------ |------------------------------------------------ | +| `defaultOpenItems: number`| `expand: boolean` | `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. | +| `multiple: boolean` | `expand-mode: "single" \| "multiple"` | | From 35aa33719219d81ace27c0d4370e31979d00690b Mon Sep 17 00:00:00 2001 From: Brian Brady Date: Wed, 22 Feb 2023 10:51:57 -0800 Subject: [PATCH 4/5] formats docs table --- packages/web-components/src/accordion-item/README.md | 6 +++--- packages/web-components/src/accordion/README.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/web-components/src/accordion-item/README.md b/packages/web-components/src/accordion-item/README.md index ebe371be3ea91a..946769567defe5 100644 --- a/packages/web-components/src/accordion-item/README.md +++ b/packages/web-components/src/accordion-item/README.md @@ -131,9 +131,9 @@ Fluent WC3 Accordion Item extends from the [FAST Accordion Item](https://explore **Property Mapping** | Fluent UI React 9 | Fluent Web Components 3 | Description of difference | -|---------------------------|---------------------------|------------------------------------------------------------------------------------------| -| `defaultOpenItems: number`| `expand: boolean` | `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. -| `size` | `size` | +| ------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------- | +| `defaultOpenItems: number`| `expand: boolean` | `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. | +| `size` | `size` | | | `as: 'h1'` | `'h2'` | `'h3'` | `'h4'` | `'h5'` | `'h6'` | `headinglevel: 1` | `2` | `3` | `4` | `5` | `6` | `as` property sets a wrapper around the `AccordionItem` header with the corresponding header tag ( `h1`, `h2`, etc. )
`headinglevel` sets the `aria-level` attribute to the corresponding heading level. | `disabled` | `disabled` | | `expandIconPosition` | `expand-icon-position` | diff --git a/packages/web-components/src/accordion/README.md b/packages/web-components/src/accordion/README.md index 4238aef7d0e1e2..54992e92207fa0 100644 --- a/packages/web-components/src/accordion/README.md +++ b/packages/web-components/src/accordion/README.md @@ -103,6 +103,6 @@ Fluent WC3 Accordion extends from the [FAST Accordion](https://explore.fast.desi **Property Mapping** | Fluent UI React 9 | Fluent Web Components 3 | Description of difference | -| ------------------------- | ------------------------------------------ |------------------------------------------------ | -| `defaultOpenItems: number`| `expand: boolean` | `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded. | +| ------------------------- | ------------------------------------------ |---------------------------------------------------------- | +| `defaultOpenItems: number`| `expand: boolean` | `defaultOpenItems` is a number property set on the `Accordion` corresponding to the intended `AccordionItem` to be expanded.
`expand` is a boolean property set directly on the `AccordionItem` intended to be expanded | | `multiple: boolean` | `expand-mode: "single" \| "multiple"` | | From 2fcacd14c35f17d562b098f8b16c7e5746acf999 Mon Sep 17 00:00:00 2001 From: Brian Brady Date: Mon, 27 Feb 2023 10:31:00 -0800 Subject: [PATCH 5/5] yarn change --- ...eb-components-3cce950f-a483-4620-ba7b-696cc922f331.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@fluentui-web-components-3cce950f-a483-4620-ba7b-696cc922f331.json diff --git a/change/@fluentui-web-components-3cce950f-a483-4620-ba7b-696cc922f331.json b/change/@fluentui-web-components-3cce950f-a483-4620-ba7b-696cc922f331.json new file mode 100644 index 00000000000000..4f45a98bfd9806 --- /dev/null +++ b/change/@fluentui-web-components-3cce950f-a483-4620-ba7b-696cc922f331.json @@ -0,0 +1,7 @@ +{ + "type": "prerelease", + "comment": "updates wc3 accordion and accordion item docs", + "packageName": "@fluentui/web-components", + "email": "brianbrady@microsoft.com", + "dependentChangeType": "patch" +}