diff --git a/change/@fluentui-web-components-02af706e-1d6f-43fe-9ced-181466a6aeed.json b/change/@fluentui-web-components-02af706e-1d6f-43fe-9ced-181466a6aeed.json new file mode 100644 index 00000000000000..23d7ffaabde286 --- /dev/null +++ b/change/@fluentui-web-components-02af706e-1d6f-43fe-9ced-181466a6aeed.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "update V2 to V3 migration guide", + "packageName": "@fluentui/web-components", + "email": "863023+radium-v@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/change/@fluentui-web-components-d031bfa2-7b89-4756-9ee7-b46a29db0c5b.json b/change/@fluentui-web-components-d031bfa2-7b89-4756-9ee7-b46a29db0c5b.json new file mode 100644 index 00000000000000..f5b4e972a5689f --- /dev/null +++ b/change/@fluentui-web-components-d031bfa2-7b89-4756-9ee7-b46a29db0c5b.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "fix minor sticker sheet quirks", + "packageName": "@fluentui/web-components", + "email": "863023+radium-v@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/packages/web-components/src/_docs/developer/migration.mdx b/packages/web-components/src/_docs/developer/migration.mdx index 3c14d1b79ccc36..a30369f7055f45 100644 --- a/packages/web-components/src/_docs/developer/migration.mdx +++ b/packages/web-components/src/_docs/developer/migration.mdx @@ -1,582 +1,665 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + -# V2 β†’ V3 Migration Guide +# Migration Guide -We're happy to announce Fluent Web Components v3 is now available. This document provides a high-level overview of the differences and API changes between previous versions. Please reach out if you have any questions. +Fluent Web Components v3 is a ground-up rewrite of the library. If you are coming from v2 (the last v2 release was `2.6.1`), expect breaking changes across imports, component registration, theming, and the markup for most form controls. This guide covers what changed and how to update your code. -Here's a snapshot of what's new and improved in v3. +## Major Changes -- Smaller bundle size (-26% compressed!) -- Reduced DOM size and overhead by nearly 50% -- Improved Storybook docs -- Updated to FASTElement v2.0 -- Individual component exports -- Leveraging ElementInternals for better form support -- Removed hard dependency on @microsoft/fast-foundation -- Continued alignment with Fluent React v9 -- Improved setTheme() to set/unset at the page or element level +- **New foundation.** Fluent Web Components v3 is built directly on [FAST Element](https://fast.design) v3. The hard dependency on `@microsoft/fast-foundation` has been removed. +- **Individual component exports.** Every component ships its own class, template, styles, and definition, so you can register only what you use. +- **New registration model.** The `provideFluentDesignSystem().register(...)` pattern is gone. Register components with side-effect `define` imports instead. +- **Token-based theming.** `setTheme()` replaces the design-token and `DesignSystemProvider` model, so you can apply your own theme to the whole page or a single element. +- **`ElementInternals` everywhere.** Form-associated components use `ElementInternals` for better native form participation. +- **Smaller and lighter.** The full-library bundle is about 20% smaller over the wire. -## Component Comparison v2 β†’ v3 +## Bundle Size Comparison -A high-level look at the differences between components in v2 and v3 - -- πŸ†• 14 new components -- ⚠️ 5 renamed components -- ⛔️ 4 removed components -- πŸ›£οΈ 13 components on our current roadmap - -### Renamed Components - -- `anchor` = use `link` or `anchor-button` -- `progress` = use `progress-bar` -- `select` = use `dropdown` -- `text-area` = `textarea` -- `text-field` = `text-input` - -### Removed Components - -- `anchored-region` -- `slider-label` = `use field, label` -- `tabs` = use `tablist` -- `tab-panel` = use `role="tabpanel"` - -# API Changes - -- Form controls now use `` wrapper to handle label spacing and errors -- Dialog = requires Dialog Body child -- Tabs = no longer a uniform control, allows for flexibility -- Accordion Item = attribute changes -- RadioGroup = new API to leverage field - -API changes, renames, and deprecations are itemized in the table below. +Comparing the CDN bundle that registers the entire library (`web-components.min.js`) in each version: - - - - + + + + + - - - - - - - - - - + + + + + - - - + + + + - - - + + + + + +
ComponentV2V3NotesVersionBundleMinifiedGzipBrotli
accordionβœ…βœ…
accordion-itemβœ…βœ…βš οΈ API Change β†’ Attributes changed to better match web platformv2.6.1 + web-components.min.js + 366 KB80.4 KB67.2 KB
anchorβœ…β›”οΈv3.0.0 - Removed β†’ Use link or anchor-button + web-components.min.js 267 KB64.5 KB54.1 KB
anchor-buttonπŸ†•Reduction + −27% + + −20% + + −19% +
+ +The v3 `web-components-all.min.js` bundle (all components plus every named export) is 301 KB minified / 71.3 KB gzip. + +The v2 and v3 component sets are not identical. Because every v3 component is individually importable, most applications ship far less than the full bundle by registering only the components they use. + +## Usage + +### Installation and Dependencies + +Fluent Web Components v3 can be installed for direct use in your project with common package managers: + +```bash +# npm +npm install @fluentui/web-components +``` + +`@fluentui/web-components` expects `@microsoft/fast-element@^3.0.0` to be installed as a peer dependency. If you are using a package manager that does not automatically install peer dependencies, you will need to install it manually: + +```bash +# npm +npm install @microsoft/fast-element +``` + +### Registering components + +Each component provides a side-effect import that registers the component with the browser. For example, to register the `Button` and `TextInput` components: + +```ts +// V3 β€” register individual components +import '@fluentui/web-components/button/define.js'; +import '@fluentui/web-components/text-input/define.js'; +``` + +You can also register all components at once with a single import: + +```ts +// V3 β€” register all components +import '@fluentui/web-components/web-components.js'; +``` + +Individual export paths allow you to import the component class, template, styles, and definition for use in your own custom elements: + +```ts +// The Fluent component class, which extends the BaseButton class with Fluent-specific behavior and properties +import { Button } from '@fluentui/web-components/button/class.js'; + +// Most components provide a base class, which can be extended to create a custom component +import { BaseButton } from '@fluentui/web-components/button/base.js'; + +// The raw component definition which +import { definition as ButtonDefinition } from '@fluentui/web-components/button/definition.js'; + +// Fluent-specific component template +import { template as ButtonTemplate } from '@fluentui/web-components/button/template.js'; + +// Fluent-specific composed styles +import { styles as ButtonStyles } from '@fluentui/web-components/button/styles.js'; + +// Attribute and property configuration options, as well as the component tag name +import { + ButtonAppearance, + ButtonSize, + ButtonShape, + tagName as ButtonTagName, +} from '@fluentui/web-components/button/options.js'; +``` + +All public exports are provided in the `@fluentui/web-components` package root, so you can also import them from there: + +```ts +import { + Button, + BaseButton, + ButtonDefinition, + ButtonTemplate, + ButtonStyles, + ButtonAppearance, + ButtonSize, + ButtonShape, + ButtonTagName, +} from '@fluentui/web-components'; +``` + +If you only need to define all components, you can import from the `web-components.js` entry point. The `setTheme()` function is also provided as a property on the `Fluent` global object, so you can use it without importing anything else: + +```ts +// All components are defined as a side effect of this import, but no public exports are available +import '@fluentui/web-components/web-components.js'; + +// the global `Fluent.setTheme()` function is available on the `Fluent` global object +Fluent.setTheme(/* your theme */); +``` + +If you need to define all components _and_ use public exports, you can import from the `web-components-all.js` entry point: + +```ts +// All components are defined as a side effect of this import, and all public exports are available from the same entry point +import { + Button, + BaseButton, + ButtonDefinition, + ButtonTemplate, + ButtonStyles, + ButtonAppearance, + ButtonSize, + ButtonShape, + ButtonTagName, +} from '@fluentui/web-components/web-components-all.js'; + +// the global `Fluent.setTheme()` function is also available from this entry point +Fluent.setTheme(/* your theme */); +``` + +## Theming + +v2 configured appearance through design tokens (for example `baseLayerLuminance`) and the `DesignSystemProvider`. v3 replaces this with `setTheme()`, which writes a flat object of theme tokens as CSS custom properties. + +```ts +import { setTheme } from '@fluentui/web-components'; +import { webLightTheme, webDarkTheme } from '@fluentui/tokens'; + +// Theme the whole document (default target) +setTheme(webLightTheme); + +// Theme a single element and its subtree +setTheme(webDarkTheme, document.querySelector('#panel')); + +// Unset a theme globally or on an element +setTheme(null); +setTheme(null, document.querySelector('#panel')); +``` + +`setTheme()` accepts any flat token object where each value is a string or number; it is not limited to the shipped `@fluentui/tokens` themes. + +When you load the CDN bundle via a script tag, `setTheme` is available on `globalThis` under the `Fluent` namespace: + +```html + + +``` + +See the [Theming](?path=/docs/concepts-developer-theming--docs) page for more information. + +### New Components in v3 + +These components are new in v3. Some are entirely new to the library, while others replace or rename a v2 component, as noted. + +{/* prettier-ignore */} + + - - - - - - - - - - + + + + + - - - - + + + - - - + + - - - + + - - - + + - - - + + - - + + - - - - + + - - - - + + + - - - + + - - - + + - - + + - - - - - + + + - - - + + - - - + + - - - + + - - - - + + + - - - + + - - - - + + + - - - - + + + - - - + + - - - - + + + - - - - + + + - - - + + - - - - + + + + +
anchored-regionβœ…β›”οΈRemoved
avatarπŸ†•Component Classv3 tag nameNote
badgeβœ…βœ…AnchorButton<fluent-anchor-button>Replaces <fluent-anchor>
breadcrumbβœ…Avatar<fluent-avatar>
breadcrumb-itemβœ…CounterBadge<fluent-counter-badge>
buttonβœ…βœ…CompoundButton<fluent-compound-button>
calendarβœ…DialogBody<fluent-dialog-body>
cardβœ…Drawer<fluent-drawer> 🚧 In Progress
checkboxβœ…βœ…DrawerBody<fluent-drawer-body>
colorβœ…Dropdown<fluent-dropdown>Replaces <fluent-combobox> and <fluent-select>
comboboxβœ…βœ…Field<fluent-field>
compound-buttonβœ…Image<fluent-image>
data-gridβœ…Label<fluent-label> 🚧 In Progress
dialogβœ…βœ… - ⚠️ API Change β†’ Use with dialog-body. - Link<fluent-link>Replaces <fluent-anchor appearance="hypertext">
dialog-bodyπŸ†•MenuButton<fluent-menu-button>
dividerβœ…βœ…MenuList<fluent-menu-list>
drawerπŸ†•MessageBar<fluent-message-bar>
drawer-bodyπŸ†•ProgressBar<fluent-progress-bar>Renamed from <fluent-progress>
dropdownβœ…RatingDisplay<fluent-rating-display>
fieldπŸ†•Spinner<fluent-spinner>Handles the indeterminate loading case previously covered by <fluent-progress-ring>
flipperβœ…Tablist<fluent-tablist>Renamed from <fluent-tabs>
horizontal-scrollβœ…Text<fluent-text>
imageπŸ†•TextInput<fluent-text-input>Renamed from <fluent-text-field>
listboxβœ…βœ…TextArea<fluent-textarea>Renamed from <fluent-text-area>
listbox-optionβœ…βœ…ToggleButton<fluent-toggle-button>
labelπŸ†•Tree<fluent-tree>Renamed from <fluent-tree-view>
+ +### Removed Components + +Aside from the renamed and replaced components above, the following components have been removed in v3: + +- Breadcrumb (``) +- BreadcrumbItem (``) +- Calendar (``) +- Card (``) +- DataGrid (``) +- DataGridCell (``) +- DataGridRow (``) +- DesignSystemProvider (``) +- Flipper (``) +- HorizontalScroll (``) +- NumberField (``) +- ProgressRing (``) +- Search (``) +- Skeleton (``) +- Toolbar (``) + +## Major Component API Changes + +### Anchor + +Button-style anchors are now represented by the `AnchorButton` class and `` tag. Hypertext-style anchors are now represented by the `Link` class and `` tag. + + + - - - - + + + + + + - - - - + + + + - - - - + + + + +
linkβœ…(Renamed)v2 Component Classv3 Class Namev2 tag namev3 Equivalent
menuβœ…βœ…AnchorAnchorButton + <fluent-anchor> + + <fluent-anchor-button> +
menu-buttonπŸ†•Link + <fluent-anchor appearance="hypertext"> + + <fluent-link> +
+ +### AnchoredRegion + +The `AnchoredRegion` class and `` tag have been removed in v3. Use CSS anchor positioning instead. + +### Combobox and Select + +The `Combobox` and `Select` classes in v2 have been replaced with the `Dropdown` class in v3. The `Dropdown` class can be configured to behave like a combobox by setting the `type` attribute to `"combobox"`. + + + - - - - + + + + + + - - - - + + + + - - - - + + + - - - - + + + + + +
menu-itemβœ…βœ…v2 Component Classv3 Class Namev2 tag namev3 Equivalent
menu-listπŸ†•ComboboxDropdown + <fluent-combobox> + + <fluent-dropdown type="combobox"> +
message-barπŸ†•Select + <fluent-select> + + <fluent-dropdown> +
number-fieldβœ…ListboxOptionDropdownOption + <fluent-option> + + <fluent-option> +
+ +### Dialog, DialogBody, Drawer, and DrawerBody + +The `Dialog` component in v2 didn't allow for expressive dialogs without the default padding and presentation (like full-width imagery). The introduction of the `` element allows for more custom compositions. Additionally, the `Drawer` component and `` element have been added in v3 to support a new type of modal presentation. + + + - - - - + + + + + + - - - + + - - - - - - - - + + - - - - + + + + - - - + + + +
popoverβœ…v2 Component Classv3 Class Namev2 tag namev3 Equivalent
progressβœ…πŸ”€DialogDialog - Renamed β†’ See progress-bar + <fluent-dialog>
progress-barπŸ”€ - Previously named progress + <fluent-dialog>
progress-ringβœ…DialogBody + <fluent-dialog-body> +
radioβœ…βœ…Drawer + <fluent-drawer> + + <fluent-drawer> +
radio-groupβœ…βœ…DrawerBody + <fluent-drawer-body> +
+ +### Progress + +The `Progress` class in v2 has been renamed to the `ProgressBar` class in v3. It remains a determinate, linear progress indicator. + + + - - - - + + + + + + - - - + + + + +
searchβœ…v2 Component Classv3 Component Classv2 tag namev3 Equivalent
selectβœ…πŸ”€ProgressProgressBar - Renamed β†’ Use dropdown with type="select" + <fluent-progress> + + <fluent-progress-bar>
+ +### SliderLabel + +The `SliderLabel` class and `` tag have been removed in v3. Use the `Field` or `Label` classes and `` or `` tags instead. + + + - - - - - - - - - - + + + + + + - - - + + + - - - - - - - - - - + + + +
skeletonβœ…
sliderβœ…βœ…v2 Component Classv2 tag namev3 Class Namev3 Equivalent
slider-labelβœ…β›”οΈSliderLabel + <fluent-slider-label> + Field - Removed β†’ Use label with field + <fluent-field>
spinnerπŸ†•
switchβœ…βœ…Label + <fluent-label> +
+ +### Tabs and TabPanel + +The `Tabs` class in v2 has been replaced with the `Tablist` class in v3. The `TabPanel` class and `` tag have been removed: supply your own panel element and associate it with a `Tab` through the tab's `aria-controls` attribute, referencing the panel's `id`. The `Tablist` applies `role="tabpanel"` to that element and shows or hides it based on the active tab. + +{/* prettier-ignore */} + + - - - - + + + + + + - - - + + - - - - - - - - + + + + +
tabβœ…βœ…Component Classv3 Class Namev2 tag namev3 Equivalent
tabsβœ…β›”οΈTabsTablist - Removed β†’ Use tablist + <fluent-tabs>
tab-panelβœ…β›”οΈ - Removed β†’ Use role="tabpanel" with tablist + <fluent-tablist>
tablistπŸ†•TabPanel + <fluent-tab-panel> + Use your own panel element and associate it with a Tab through the tab's aria-controls attribute
+ +### TextField and TextArea + +The `TextField` class in v2 has been replaced with the `TextInput` class in v3. Additionally, the `` tag has been renamed to `` in v3. + + + - - - - + + + + + + - - - + + - - - - - - - - + + - - - - - + +
textπŸ†•v2 Component Classv3 Component Classv2 tag namev3 Equivalent
text-areaβœ…πŸ”€TextFieldTextInput - Renamed β†’ See textarea + <fluent-text-field>
textareaπŸ”€ - Previously named text-area + <fluent-text-input>
text-fieldβœ…πŸ”€TextAreaTextArea - Renamedβ†’ See text-input + <fluent-text-area>
text-inputπŸ”€ - Previously named text-field + <fluent-textarea>
+ +### TreeView + +The `TreeView` class in v2 has been replaced with the `Tree` class in v3. `TreeItem` remains unchanged. + + + - - - - - - - - - - - - - - - - + + + + + + - - - - + + + +
toolbarβœ…
tooltipβœ…βœ…βš οΈ API differs from React implementation
tree-itemβœ…βœ…v2 Component Classv3 Component Classv2 tag namev3 Equivalent
tree-viewβœ…βœ…TreeViewTree + <fluent-tree-view> + + <fluent-tree> +
- -### Notable API Changes - -Here's an overview of the more significant changes in the project. Other smaller changes (like attribute renaming) will be reflected in the improved Storybook docs. - -### Anchor - -Anchor is deprecated in favor of `` (for text links) and `` (for links that look like buttons). - -### Dialog - -The previous dialog didn't allow for expressive dialogs without the default padding and presentation (like full-width imagery). This introduction of the `` element allows for more custom compositions. - -#### BEFORE: - -```html - - -

Title goes here

- - Contents go here - -``` - -#### AFTER: - -```html - - - optional image - -

Title goes here

- Contents go here - - -``` - -### Field - -We have a new form Field component to control label placement and validation errors for form controls. - -```html - - - - - -``` - -This is also used by `` (see below). - -Due to web platform labelling constraints of the ShadowDOM, the labelling API for `` and `` is slightly different. Note that `` uses the default slot for label, while `` uses the label slot due to its default slot is reserved for the content inside the text area. - -```html - - Label goes here - - - - Label goes here - -``` - -### RadioGroup - -#### BEFORE: - -```html - - Apple - Banana - -``` - -#### AFTER: - -```html - - - - - - - - - - - - - - -``` - -### Bundles - -The package ships two CDN-ready bundles, each available in minified and non-minified versions: - -- **`web-components.js`** / **`web-components.min.js`** β€” Registers all components and exposes `Fluent.setTheme` on `globalThis`. This is the recommended bundle for most CDN and script-tag consumers. -- **`web-components-all.js`** / **`web-components-all.min.js`** β€” Everything in the standard bundle, plus all named exports from the package (base classes, templates, styles, design tokens, and utilities). Use this if you need programmatic access to the full API surface from a CDN context. - -### setTheme - -- `setTheme()` can set themes such as `setTheme(webLightTheme)` (defaults to document) or `setTheme(webDarkTheme, element)` to theme an element and its children -- `setTheme()` can unset themes with `setTheme(null)` or `setTheme( null, element )` - -### Case studies - -- [Edge is seeing impressive results](https://blogs.windows.com/msedgedev/2024/05/28/an-even-faster-microsoft-edge/) when switching WebView UI to Fluent Web Components v3. diff --git a/packages/web-components/src/_docs/developer/sticker-sheet.mdx b/packages/web-components/src/_docs/developer/sticker-sheet.mdx index a2d81527d8d181..20b57539078258 100644 --- a/packages/web-components/src/_docs/developer/sticker-sheet.mdx +++ b/packages/web-components/src/_docs/developer/sticker-sheet.mdx @@ -62,8 +62,8 @@ export const stickerSheetHTML = /* html */`

Accordion

- - + + Accordion header 1 Accordion panel 1 @@ -146,7 +146,7 @@ export const stickerSheetHTML = /* html */` - +
@@ -543,6 +543,10 @@ export const stickerThemes = { export const StickerSheet = () => { const containerRef = React.useRef(null); React.useEffect(() => { + const indeterminateCheckbox = containerRef.current?.querySelector('#sticker-indeterminate-checkbox'); + if (indeterminateCheckbox) { + indeterminateCheckbox.indeterminate = true; + } const applyGlobals = globals => { const themeKey = globals?.theme || 'web-light'; const dir = globals?.dir || 'ltr';