From 46be5ff69017aa8c930060023ac80959ce880165 Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Mon, 29 Jun 2026 15:02:47 -0700 Subject: [PATCH 1/2] Promote web components to stable (#36356) ## Description This change promotes the `@fluentui/web-components` from release candidate to stable `3.0.0` and updates outdated `README.md` documentation as appropriate. Co-authored-by: Dave Rupert Co-authored-by: John Kreitlow <863023+radium-v@users.noreply.github.com> --- ...-baaa98fd-7a14-4318-9cdb-133c1e6c1f2a.json | 7 + packages/web-components/README.md | 69 +++++--- .../web-components/docs/web-components.api.md | 12 +- packages/web-components/package.json | 8 +- .../src/_docs/concepts/introduction.mdx | 4 - .../src/_docs/developer/quick-start.mdx | 45 +++--- .../src/accordion-item/README.md | 141 ----------------- .../src/accordion-item/index.ts | 6 +- .../web-components/src/accordion/README.md | 108 ------------- .../web-components/src/accordion/index.ts | 6 +- packages/web-components/src/avatar/README.md | 59 ------- packages/web-components/src/button/README.md | 47 ------ .../web-components/src/checkbox/README.md | 127 --------------- .../web-components/src/dialog-body/README.md | 9 -- packages/web-components/src/dialog/README.md | 90 ----------- .../web-components/src/drawer-body/README.md | 49 ------ packages/web-components/src/drawer/README.md | 111 ------------- .../web-components/src/image/image.spec.md | 62 -------- packages/web-components/src/index.ts | 12 +- packages/web-components/src/label/README.md | 123 --------------- .../web-components/src/menu-item/README.md | 125 --------------- .../web-components/src/menu-list/README.md | 104 ------------- packages/web-components/src/menu/README.md | 145 ----------------- .../web-components/src/message-bar/README.md | 96 ------------ .../web-components/src/radio-group/README.md | 129 --------------- packages/web-components/src/radio/README.md | 133 ---------------- .../web-components/src/select/select.spec.md | 115 -------------- .../web-components/src/slider/slider.spec.md | 109 ------------- packages/web-components/src/switch/README.md | 121 -------------- packages/web-components/src/tablist/readme.md | 100 ------------ .../web-components/src/text-input/README.md | 147 ------------------ 31 files changed, 97 insertions(+), 2322 deletions(-) create mode 100644 change/@fluentui-web-components-baaa98fd-7a14-4318-9cdb-133c1e6c1f2a.json delete mode 100644 packages/web-components/src/accordion-item/README.md delete mode 100644 packages/web-components/src/accordion/README.md delete mode 100644 packages/web-components/src/avatar/README.md delete mode 100644 packages/web-components/src/button/README.md delete mode 100644 packages/web-components/src/checkbox/README.md delete mode 100644 packages/web-components/src/dialog-body/README.md delete mode 100644 packages/web-components/src/dialog/README.md delete mode 100644 packages/web-components/src/drawer-body/README.md delete mode 100644 packages/web-components/src/drawer/README.md delete mode 100644 packages/web-components/src/image/image.spec.md delete mode 100644 packages/web-components/src/label/README.md delete mode 100644 packages/web-components/src/menu-item/README.md delete mode 100644 packages/web-components/src/menu-list/README.md delete mode 100644 packages/web-components/src/menu/README.md delete mode 100644 packages/web-components/src/message-bar/README.md delete mode 100644 packages/web-components/src/radio-group/README.md delete mode 100644 packages/web-components/src/radio/README.md delete mode 100644 packages/web-components/src/select/select.spec.md delete mode 100644 packages/web-components/src/slider/slider.spec.md delete mode 100644 packages/web-components/src/switch/README.md delete mode 100644 packages/web-components/src/tablist/readme.md delete mode 100644 packages/web-components/src/text-input/README.md diff --git a/change/@fluentui-web-components-baaa98fd-7a14-4318-9cdb-133c1e6c1f2a.json b/change/@fluentui-web-components-baaa98fd-7a14-4318-9cdb-133c1e6c1f2a.json new file mode 100644 index 00000000000000..baba575bba336b --- /dev/null +++ b/change/@fluentui-web-components-baaa98fd-7a14-4318-9cdb-133c1e6c1f2a.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "Promote @fluentui/web-components to 3.0.0 stable release.", + "packageName": "@fluentui/web-components", + "email": "7559015+janechu@users.noreply.github.com", + "dependentChangeType": "patch" +} diff --git a/packages/web-components/README.md b/packages/web-components/README.md index 9102db6d8a00d0..7dfa68acbf392b 100644 --- a/packages/web-components/README.md +++ b/packages/web-components/README.md @@ -1,7 +1,7 @@ # Fluent UI Web Components [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![npm version](https://img.shields.io/npm/v/@fluentui/web-components/beta?style=flat-square)](https://www.npmjs.com/package/@fluentui/web-components/v/beta) +[![npm version](https://img.shields.io/npm/v/@fluentui/web-components?/style=flat-square)](https://www.npmjs.com/package/@fluentui/web-components) Microsoft's [Fluent UI Web Components](https://github.com/microsoft/fluentui/tree/master/packages/web-components) is designed to help you build web apps using Web Components styled with the [Fluent design language](https://github.com/microsoft/fluentui). @@ -14,43 +14,52 @@ Fluent UI should be installed as a `dependency` of your app. **Yarn** ```sh -yarn add @fluentui/web-components@beta +yarn add @fluentui/web-components ``` **NPM** ```sh -npm i @fluentui/web-components@beta +npm i @fluentui/web-components ``` **pnpm** ```sh -pnpm add @fluentui/web-components@beta +pnpm add @fluentui/web-components ``` ### From CDN -A pre-bundled script that contains all APIs needed to use FAST Foundation is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN. +A pre-bundled script that contains all APIs needed to use Fluent UI Web Components is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN. ```html - + ``` -The above CDN location points to the latest Beta release of `@fluentui/web-components`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with. +The above CDN location points to the latest release of `@fluentui/web-components`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with. For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL. ## Setup +### Required Theming + Fluent UI Web Components are styled using tokens in the form of CSS variables. You can use the `setTheme` utility to provide a theme for your website or application. +Available themes: + +- `webLightTheme` +- `webDarkTheme` + +Theme implementation: + ```js import { setTheme } from '@fluentui/web-components'; import { webLightTheme } from '@fluentui/tokens'; @@ -60,31 +69,50 @@ setTheme(webLightTheme); ## Usage -That's it. You can now use Fluent UI Web Components in your app. +Each component can be directly imported. The side effect only module will call define and cause it to be set up. + +### Defining Components -**Importing the defined component:** +**Importing a defined component:** ```js import '@fluentui/web-components/button.js'; ``` -**Defining the element yourself using named imports:** +**Importing all defined components:** ```js -import { ButtonDefinition, FluentDesignSystem } from '@fluentui/web-components'; +import '@fluentui/web-components/web-components.js'; +``` + +### Defining Declarative Components + +Each component provides a declarative `f-template`. + +Include an `f-template` on your page, you can find it at +`'@fluentui/web-components/button/template.html'`. -ButtonDefinition.define(FluentDesignSystem.registry); +**Importing a defined component:** + +```js +import '@fluentui/web-components/button/define-async.js'; ``` -## Developer Experience +### Hydrating Declarative Components + +For more information about including hydratable syntax, we recommend using an integration with [WebUI Framework](https://microsoft.github.io/webui/) project. + +[More information about FAST hydration](https://fast.design/docs/3.x/declarative-templates/server-rendering/). -For convenience we have included a [CEM (custom elements manifest)](https://github.com/webcomponents/custom-elements-manifest) at the root of the project. +### Custom Elements Manifest + +We ship a [CEM (custom elements manifest)](https://github.com/webcomponents/custom-elements-manifest) from the root of the bundle. ```js -import CEM from '@fluentui/custom-elements.json' with { type: 'json' }; +import CEM from '@fluentui/web-components/custom-elements.json' with { type: 'json' }; ``` -## Development +## Contributing To start the component development environment, run `yarn start`. @@ -114,14 +142,7 @@ Use the `yarn check:ssr` summary to avoid clobbering intentional SSR-only edits: Keep generated-file updates scoped to the component you changed. If `yarn check:ssr` reports unrelated stale files, leave them out of your PR and coordinate a dedicated cleanup. -### Known issue with Storybook site hot-reloading during development - -Storybook will watch modules for changes and hot-reload the module when necessary. This is usually great but poses a problem when the module being hot-reloaded defines a custom element. A custom element name can only be defined by the `CustomElementsRegistry` once, so reloading a module that defines a custom element will attempt to re-register the custom element name, throwing an error because the name has already been defined. This error will manifest with the following message: -`Failed to execute 'define' on 'CustomElementRegistry': the name "my-custom-element-name" has already been used with this registry` - -This is a known issue and will indicate that you need to refresh the page. We're working on surfacing a more instructive error message for this case. - -## Testing +### Testing On CI, a static test harness build is first generated by running Vite in build mode. The Playwright tests are then run against the generated harness. To run Playwright tests in this mode, use the command `yarn nx run web-components:e2e`. diff --git a/packages/web-components/docs/web-components.api.md b/packages/web-components/docs/web-components.api.md index d8a59fc44377bd..8732dacfa46be5 100644 --- a/packages/web-components/docs/web-components.api.md +++ b/packages/web-components/docs/web-components.api.md @@ -32,7 +32,7 @@ export class Accordion extends FASTElement { } // @public -export const accordionDefinition: PartialFASTElementDefinition; +export const AccordionDefinition: PartialFASTElementDefinition; // @public export const AccordionExpandMode: { @@ -60,7 +60,7 @@ export interface AccordionItem extends StartEnd { } // @public -export const accordionItemDefinition: PartialFASTElementDefinition; +export const AccordionItemDefinition: PartialFASTElementDefinition; // Warning: (ae-missing-release-tag) "AccordionItemMarkerPosition" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -95,20 +95,20 @@ export type AccordionItemSize = ValuesOf; // Warning: (ae-missing-release-tag) "styles" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const accordionItemStyles: ElementStyles; +export const AccordionItemStyles: ElementStyles; // @public -export const accordionItemTemplate: ElementViewTemplate; +export const AccordionItemTemplate: ElementViewTemplate; // Warning: (ae-missing-release-tag) "styles" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const accordionStyles: ElementStyles; +export const AccordionStyles: ElementStyles; // Warning: (ae-missing-release-tag) "template" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) -export const accordionTemplate: ElementViewTemplate; +export const AccordionTemplate: ElementViewTemplate; // Warning: (ae-different-release-tags) This symbol has another declaration with a different release tag // Warning: (ae-internal-mixed-release-tag) Mixed release tags are not allowed for "AnchorButton" because one of its declarations is marked as @internal diff --git a/packages/web-components/package.json b/packages/web-components/package.json index f8fa1af8d27988..fb6e418bbd2ea8 100644 --- a/packages/web-components/package.json +++ b/packages/web-components/package.json @@ -45,6 +45,7 @@ "./utilities.js": "./dist/esm/utils/index.js", "./theme/*.js": "./dist/esm/theme/*.js", "./*/base.js": "./dist/esm/*/*.base.js", + "./*/class.js": "./dist/esm/*/*.js", "./*/define.js": "./dist/esm/*/define.js", "./*/define-async.js": "./dist/esm/*/define-async.js", "./*/definition.js": "./dist/esm/*/*.definition.js", @@ -119,11 +120,8 @@ }, "beachball": { "disallowedChangeTypes": [ - "major", - "minor", - "patch" - ], - "tag": "rc" + "major" + ] }, "customElements": "./custom-elements.json" } diff --git a/packages/web-components/src/_docs/concepts/introduction.mdx b/packages/web-components/src/_docs/concepts/introduction.mdx index 6b44a6332734ba..fe4d59fb8409a7 100644 --- a/packages/web-components/src/_docs/concepts/introduction.mdx +++ b/packages/web-components/src/_docs/concepts/introduction.mdx @@ -63,10 +63,6 @@ Each component is designed to adhere to the following standards: Fluent UI Web Components is built directly on the W3C Web Component standards, and does not create its own component model. This allows our components to function the same as built-in, native HTML elements. You do not need a framework to use Fluent UI components but you can use them in combination with any framework or library of your choice. -### When is the official release planned? - -While we don't expect any major (breaking) changes in our Release Candidate, we're actively listening to user feedback and responding accordingly. Once partners and the rest of the Fluent project give required approvals, we'll publish the official V3 release. - ### Questions Reach out to the Fluent UI Web Components team on [Github](https://github.com/microsoft/fluentui) diff --git a/packages/web-components/src/_docs/developer/quick-start.mdx b/packages/web-components/src/_docs/developer/quick-start.mdx index 8c527c78a8d210..5149d9520769e2 100644 --- a/packages/web-components/src/_docs/developer/quick-start.mdx +++ b/packages/web-components/src/_docs/developer/quick-start.mdx @@ -12,20 +12,34 @@ Fluent UI web components and Fluent tokens should be installed as a `dependency` npm install @fluentui/web-components @fluentui/tokens ``` -## Basic Usage: Import entire component bundle +## Basic Usage -The easiest way to get up and running with Fluent Web Components is to use our entire component bundle. You will also need Fluent UI's design token CSS on the page in either by generating stylesheet yourself or using our `setTheme` utility. +Fluent UI Web Components are styled using tokens in the form of CSS variables. You can use the `setTheme` utility to provide a theme for your website or application. -```js -// Import all components and the setTheme utility -import '@fluentui/web-components/web-components.min.js'; +Available themes: + +- `webLightTheme` +- `webDarkTheme` -// Set theme +Theme implementation: + +```js +import { setTheme } from '@fluentui/web-components'; import { webLightTheme } from '@fluentui/tokens'; + setTheme(webLightTheme); ``` -## Recommended Usage: Use our tree-shakable component exports +### Import entire component bundle + +The easiest way to get up and running with Fluent Web Components is to use our entire component bundle. You will also need Fluent UI's design token CSS on the page in either by generating stylesheet yourself or using our `setTheme` utility. + +```js +// Import all components +import '@fluentui/web-components/web-components.js'; +``` + +### Recommended Usage: Use our tree-shakable component exports To reduce your production bundle size, we offer each component as a standalone ESM export. We recommend this pathway for maximum performance and tree-shaking. There are two options for importing individual components. @@ -36,12 +50,6 @@ Our defined component exports will import single components _and_ define the cus ```js // Import with side-effectful Custom Element definitions import '@fluentui/web-components/button.js'; -import '@fluentui/web-components/dialog.js'; - -// Set theme -import { setTheme } from '@fluentui/web-components'; -import { webLightTheme } from '@fluentui/tokens'; -setTheme(webLightTheme); ``` Note: If a component has a child component dependency, you will need to import both components (e.g. Tablist and Tab). @@ -52,14 +60,9 @@ If you want to control side-effects and need granular control of when your compo ```js // Import non-side-effectful component definitions -import { ButtonDefinition, DialogDefinition, FluentDesignSystem } from '@fluentui/web-components'; +import { Button } from '@fluentui/web-components/button/class.js'; +import { definition as buttonDefinition } from '@fluentui/web-components/button/definition.js'; // Manual component definition -ButtonDefinition.define(FluentDesignSystem.registry); -DialogDefinition.define(FluentDesignSystem.registry); - -// Set theme -import { setTheme } from '@fluentui/web-components'; -import { webLightTheme } from '@fluentui/tokens'; -setTheme(webLightTheme); +Button.define(buttonDefinition); ``` diff --git a/packages/web-components/src/accordion-item/README.md b/packages/web-components/src/accordion-item/README.md deleted file mode 100644 index 489ddf34805baf..00000000000000 --- a/packages/web-components/src/accordion-item/README.md +++ /dev/null @@ -1,141 +0,0 @@ -# Accordion Item - -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. - -
- -## Class: `AccordionItem` - -
- -### **Component Name** - -`AccordionItem` - -
- -### **Variables** - -| Name | Description | Type | -| ----------------------------- | -------------------------- | --------------------------------------------------------------------------------- | -| `AccordionItemSize` | Expand modes for Accordion | `{ small: "small", medium: "medium", large: "large", extraLarge: "extra-large" }` | -| `AccordionItemMarkerPosition` | 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. | -| `markerPosition` | public | `AccordionItemMarkerPosition` | `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 | -| `markerPosition` | markerPosition | -| `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` | `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` | -| `markerPosition` | `marker-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-item/index.ts b/packages/web-components/src/accordion-item/index.ts index dbf6f3a7a68208..9de750227194a7 100644 --- a/packages/web-components/src/accordion-item/index.ts +++ b/packages/web-components/src/accordion-item/index.ts @@ -2,7 +2,7 @@ export { BaseAccordionItem } from './accordion-item.base.js'; export { AccordionItem } from './accordion-item.js'; export type { AccordionItemOptions } from './accordion-item.js'; export { AccordionItemSize, AccordionItemMarkerPosition } from './accordion-item.options.js'; -export { styles as accordionItemStyles } from './accordion-item.styles.js'; -export { definition as accordionItemDefinition } from './accordion-item.definition.js'; -export { template as accordionItemTemplate } from './accordion-item.template.js'; +export { styles as AccordionItemStyles } from './accordion-item.styles.js'; +export { definition as AccordionItemDefinition } from './accordion-item.definition.js'; +export { template as AccordionItemTemplate } from './accordion-item.template.js'; export { tagName as AccordionItemTagName } from './accordion-item.options.js'; diff --git a/packages/web-components/src/accordion/README.md b/packages/web-components/src/accordion/README.md deleted file mode 100644 index 54992e92207fa0..00000000000000 --- a/packages/web-components/src/accordion/README.md +++ /dev/null @@ -1,108 +0,0 @@ -# Accordion - -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 Design Spec in Figma](https://www.figma.com/file/7X3Tgd3fTurii3FACrfhzo/Accordion?node-id=2777%3A42482&t=jHgc4PXRMQH6rPmy-0) - -
- -## **Engineering Spec** - -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. - -
- -## Class: `Accordion` - -
- -### **Component Name** - -`Accordion` - -
- -### **Variables** - -| Name | Description | Type | -| --------------------- | ------------------------- | -------------------------------------- | -| `AccordionExpandMode` | Expand mode for Accordion | `{ single: "single", multi: "multi" }` | - -
- -### **Fields** - -| Name | Privacy | Type | Default | Description | -| ---------------- | --------- | --------------------- | ---------- | --------------------------------------------------------------------------------------------- | -| `expandmode` | public | `AccordionExpandMode` | `multiple` | Controls the expand mode of the Accordion, either allowing single or multiple item expansion. | -| `AccordionItems` | protected | `Element[]` | - -
- -### **Methods** - -| Name | Privacy | Description | Parameters | Return | Inherited From | -| ------------------- | ------- | ----------- | ------------------------------------------------------- | ------ | -------------- | -| `expandmodeChanged` | public | | `prev: AccordionExpandMode, next: AccordionExpandMode ` | - -
- -### **Events** - -| Name | Type | Description | Inherited From | -| -------- | ---- | ---------------------------------------------------------- | -------------- | -| `change` | | Fires a custom 'change' event when the active item changes | - -
- -### **Attributes** - -| Name | Field | -| ------------- | ---------- | -| `expand-mode` | expandmode | - -
- -
- -
- -## **Accessibility** - -[W3 Accordion Spec](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) - -
- -### **WAI-ARIA Roles, States, and Properties** - -
-
-
- -## **Preparation** - -
- -### **Fluent Web Component v3 v.s Fluent React 9** - -
- -**Component and Slot Mapping** - -| 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` | `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"` | | diff --git a/packages/web-components/src/accordion/index.ts b/packages/web-components/src/accordion/index.ts index f0f3cc0e53d36b..4fcb84dd2a2ec5 100644 --- a/packages/web-components/src/accordion/index.ts +++ b/packages/web-components/src/accordion/index.ts @@ -1,6 +1,6 @@ export { Accordion } from './accordion.js'; export { AccordionExpandMode } from './accordion.options.js'; -export { template as accordionTemplate } from './accordion.template.js'; -export { styles as accordionStyles } from './accordion.styles.js'; -export { definition as accordionDefinition } from './accordion.definition.js'; +export { template as AccordionTemplate } from './accordion.template.js'; +export { styles as AccordionStyles } from './accordion.styles.js'; +export { definition as AccordionDefinition } from './accordion.definition.js'; export { tagName as AccordionTagName } from './accordion.options.js'; diff --git a/packages/web-components/src/avatar/README.md b/packages/web-components/src/avatar/README.md deleted file mode 100644 index 0aea250cdf8db3..00000000000000 --- a/packages/web-components/src/avatar/README.md +++ /dev/null @@ -1,59 +0,0 @@ -# Avatar - -The Avatar component represents a person or entity. It displays the person's image, initials, or an icon, and can be either circular or square. - -## **Design Spec** - -[Link to Avatar in Figma](https://www.figma.com/file/3SlxyaJA3tpLs5rVZ4oTVj/Avatar?node-id=0%3A1&t=Ugsg41JLdURbxd7i-1) - -
- -## **Engineering Spec** - -Fluent WC3 Avatar has feature parity with the Fluent UI React 9 Accordion implementation but not direct parity. - -
- -## Class: `Avatar` - -
- -### **Component Name** - -`` - -
- -## **Preparation** - -
- -### **Fluent Web Component v3 v.s Fluent React 9** - -
- -**Component and Slot Mapping** - -| Fluent UI React 9 | Fluent Web Components 3 | -| ----------------- | ----------------------- | -| `` | `` | - -
- -**Property Mapping** -| Fluent UI React 9 | Fluent Web Components 3 | Description of difference | -| ------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------- | -| `idForColor: string`| `colorId: string` | both are strings, the delta here is primarily verbosity. In web components attributes need to follow HTML syntax for attributes. The property of `colorId` maps to `color-id`. Were we to map directly we would have an attribute of `id-for-color` which seems overly verbose. Almost all HTML attributes are at max hyphenated once. This proposes an attribute which is less verbose and only requires a single `-`. | -| `size` | `size` | | -| `shape` | `shape` | -| `active` | `active` | The only delta here is that the web components are aligning to the resolved RFC to use `undefined` for fields which are intended to "unset" attributes | -| `activeAppearance` | `appearance` | The delta here is semantic only, unless we need to reserve the appearance namespace, brevity seems preferred here | -| `name` | `name` | -| `initials` | `initials` | - -**Additional Deltas:** - -The FUIR9 implementation seems to utilize several "slots", whereas with the web component implementation includes two primary slots. - -1. Default slot - When a name or initials is provided, the default slot projects the initials generated via name or initials. If an image is slotted into the default slot, the image will be shown. If an SVG is slotted into the default slot an SVG will project overriding any other value. If name and initials are not provided and nothing is slotted, the default avatar svg is projected. -2. Badge - The slot for the badge diff --git a/packages/web-components/src/button/README.md b/packages/web-components/src/button/README.md deleted file mode 100644 index 9bea0533122f9d..00000000000000 --- a/packages/web-components/src/button/README.md +++ /dev/null @@ -1,47 +0,0 @@ -# Button - -The `Button` component allows users to commit a change or trigger an action via a single click or tap and is often found inside forms, dialogs, panels and/or pages. - -## **Design Spec** - -[Link to Button in Figma](https://www.figma.com/file/Nj9EBBvOZmS11zKNJfilVR/Button?node-id=1723%3A380&t=PNVwuI4rLXjxAFNJ-1) - -
- -## **Engineering Spec** - -Fluent WC3 Button has feature parity with the Fluent UI React 9 Button implementation but not direct parity. - -
- -## Class: `Button` - -
- -### **Component Name** - -`` - -
- -## **Preparation** - -
- -### **Fluent Web Component v3 v.s Fluent React 9** - -
- -**Component and Slot Mapping** - -| Fluent UI React 9 | Fluent Web Components 3 | -| ----------------- | ----------------------- | -| ` -
Content goes here...
-
Footer content
- - -``` diff --git a/packages/web-components/src/drawer/README.md b/packages/web-components/src/drawer/README.md deleted file mode 100644 index 3b65f3b9fac925..00000000000000 --- a/packages/web-components/src/drawer/README.md +++ /dev/null @@ -1,111 +0,0 @@ -# Drawer - -The `Drawer` component represents a drawer that can be opened and closed, typically used for navigation or additional content. - -## Design Spec - -Link to Drawer Design Spec in Figma: [Link]() - -## Engineering Spec - -The Fluent WC3 Drawer extends `FASTElement` - -### Class `Drawer` - -### Template - -```ts -export function drawerTemplate(): ElementViewTemplate { - return html` - - - - `; -} -``` - -### **Variables** - -| Name | Type | Description | -| ---------------- | ------------------------------- | ---------------------- | -| `DrawerPosition` | `start` `end` | Positions for Drawer | -| `DrawerSize` | `small` `medium` `large` `full` | Sizes for Drawer | -| `DrawerType` | `modal` `non-modal` `inline` | Modal types for Drawer | - -### **Attributes** - -| Name | Privacy | Type | Description | -| ----------------- | ------- | -------------- | ----------------------------------------------------------------------------------------- | -| `type` | public | DrawerType | Determines whether the drawer should be displayed as a modal, non-modal or inline drawer. | -| `position` | public | DrawerPosition | Sets the position of the drawer (start/end). | -| `size` | public | DrawerSize | Sets the size of the drawer (small/medium/large). | -| `ariaDescribedby` | public | string | The ID of the element that describes the drawer. | -| `ariaLabelledby` | public | string | The ID of the element that labels the drawer. | - -### **Events** - -| Name | Type | Description | -| -------------- | ------------- | -------------------------------------------- | -| `toggle` | `CustomEvent` | Fires after the dialog's open state changes | -| `beforetoggle` | `CustomEvent` | Fires before the dialog's open state changes | - -### **Methods** - -| Name | Privacy | Description | -| ------------------ | ------- | --------------------------------------------------------------- | -| `show` | public | Shows the drawer. | -| `hide` | public | Hides the drawer. | -| `emitToggle` | public | Method to emit an event after the dialog's open state changes. | -| `emitBeforeToggle` | public | Method to emit an event before the dialog's open state changes. | -| `clickHandler` | public | Handles click events on the drawer. | -| `keydownHandler` | public | Handles keydown events on the drawer. | - -### **Slots** - -| Name | Description | -| ---- | ------------------------------------- | -| | The default slot for the main content | - -### **CSS Variables** - -| Name | Description | -| ---------------- | ----------------------------------- | -| `--drawer-width` | Used to set the width of the drawer | - -## **Accessiblity** - -### **WAI-ARIA Roles, States, and Properties** - -| Name | Privacy | Type | Description | -| ------------------ | ------- | ------------------- | ---------------------------------------------------------------------------- | -| `role` | public | string | Sets the role of the dialog element to dialog when modal dialog is rendered. | -| `aria-modal` | public | string or undefined | Indicates if the drawer is modal. | -| `aria-describedby` | public | string | The ID of the element that describes the drawer. | -| `aria-labelledby` | public | string | The ID of the element that labels the drawer. | -| `aria-label` | public | string | Provides an accessible name for the drawer when aria-labelledby is not used. | - -### **Fluent Web Component v3 v.s Fluent React 9** - -
- -**Component and Slot Mapping** - -| Fluent UI React 9 | Fluent Web Components 3 | -| ----------------- | ----------------------- | -| `` | `type="modal"` | -| `` | `type="inline"` | -| ` ` | `` | diff --git a/packages/web-components/src/image/image.spec.md b/packages/web-components/src/image/image.spec.md deleted file mode 100644 index d2dba58db8142a..00000000000000 --- a/packages/web-components/src/image/image.spec.md +++ /dev/null @@ -1,62 +0,0 @@ -# Fluent Image Component - -## Component Description - -Images, like photos and illustrations, help reinforce a message and express your product or app’s style. - -## Design Spec - -[Image Spec in Figma](https://www.figma.com/file/05wt6TAsEmgsCVZfPrpcWx/Image?t=uEvu1KnTefdTZHJC-6) - -## Engineering Spec - -### Inputs - -**content** - -- @attr public alt: string | Requires description if image role is not set to presentation. -- @attr public role: string -- @attr public src: string - -**booleans** - -- @attr public block: boolean | false -- @attr public border: boolean | false -- @attr public shadow: boolean | false - -**options** - -- @attr public fit: 'none' | 'center' | 'contain' | 'cover' | 'default' -- @attr public shape: 'square' | 'rounded' | 'circular' - -### Slots - -1 slot for developer to add element. - -## Accessibility - -The image element requires an alt tag when not used in role: presentation. - -## Preparation - -This will extend the FASTElement. - -Open GitHub issues related to Image component - -- [Feature request](https://github.com/microsoft/fluentui/issues/26452) -- [Bug](https://github.com/microsoft/fluentui/issues/26399) - -## Implementation - -### CSS Guidance - -- [x] Uses design tokens for styling - -An optional border-radius can be expressed using the following design tokens: - -- borderRadiusSmall, -- borderRadiusMedium, -- borderRadiusLarge -- borderRadiusXLarge - -An optional 16px margin can be added to the image to separate it from surrounding content. diff --git a/packages/web-components/src/index.ts b/packages/web-components/src/index.ts index da3ecaf56b639f..5d316c1eb79764 100644 --- a/packages/web-components/src/index.ts +++ b/packages/web-components/src/index.ts @@ -1,19 +1,19 @@ export { AccordionItem, - accordionItemDefinition, + AccordionItemDefinition, AccordionItemMarkerPosition, AccordionItemSize, - accordionItemStyles, - accordionItemTemplate, + AccordionItemStyles, + AccordionItemTemplate, BaseAccordionItem, } from './accordion-item/index.js'; export type { AccordionItemOptions } from './accordion-item/index.js'; export { Accordion, - accordionDefinition, + AccordionDefinition, AccordionExpandMode, - accordionStyles, - accordionTemplate, + AccordionStyles, + AccordionTemplate, } from './accordion/index.js'; export { Link, LinkAppearance, LinkDefinition, LinkTemplate, LinkStyles, LinkTarget } from './link/index.js'; export { diff --git a/packages/web-components/src/label/README.md b/packages/web-components/src/label/README.md deleted file mode 100644 index 97eaf298e81f4b..00000000000000 --- a/packages/web-components/src/label/README.md +++ /dev/null @@ -1,123 +0,0 @@ -# Label - -> A label represents a caption for an item in a user interface. - -
- -## **Design Spec** - -[Link to Label Design Spec in Figma](https://www.figma.com/file/jpWO2FMBefirTyThf5Rg2P/Label?node-id=2%3A476&t=QCdofuTbXkUjMS4d-0) - -
- -## **Engineering Spec** - -
- -The fluent-label has several visual font size (small, medium, large) and font weight(regular, semibold) options. The fluent-label also provides appearances for required and disabled states. - -
- -_Note about form association_ - -In web components, when using the shadow DOM, it's not feasible to associate elements across the shadow DOM boundary using the traditional `for` attribute, since the shadow DOM creates a boundary that prevents the label element from accessing the input element's id attribute. Instead, the WC3 Label component uses the `aria-labelledby` attribute to associate the label element with the input element. This attribute has a value that matches the id of another element on the page, which serves as a label for the input element. - -
- -### Use Case - -Creating a simple label element with an optional info icon and optional required state - -
- -## Class: `Label` - -
- -### **Variables** - -
- -### **Fields** - -| Name | Privacy | Type | Default | Description | -| ---------- | ------- | ------------------------------ | ----------- | ------------------------------------ | -| `required` | public | `boolean` | `false` | Specifies required styling for label | -| `disabled` | public | `boolean` | `false` | Sets disabled state for label | -| `size` | public | `"small"` `"medium"` `"large"` | `"medium"` | Specifies font size for label | -| `weight` | public | `"regular"` `"semibold"` | `"regular"` | Specifies font weight for label | - -
- -### **Methods** - -
- -### **Events** - -
- -### **Attributes** - -| Name | Field | -| ---------- | -------- | -| `required` | required | -| `disabled` | disabled | -| `size` | size | -| `weight` | weight | - -
- -### **Slots** - -| Name | Description | -| ---- | -------------------------------------- | -| | Default slotted content for label text | - -
- -### **Template** - -```html - * -``` - -## **Accessibility** - -[W3 Label Spec](https://www.w3.org/WAI/tutorials/forms/labels/) - -
- -### **WAI-ARIA Roles, States, and Properties** - -
- -- [`aria-labelledby`](https://www.w3.org/TR/wai-aria-1.2/#aria-labelledby) - -
-
-
- -## **Preparation** - -
- -### **Fluent Web Component v3 v.s Fluent React 9** - -
- -**Component and Slot Mapping** - -| Fluent UI React 9 | Fluent Web Components 3 | -| ----------------- | ----------------------- | -| `