diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 3241ec03e771e4..6eb57b9e6f9518 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -128,7 +128,7 @@ apps/public-docsite-v9 @microsoft/cxe-red @microsoft/cxe-prg @microsoft/teams-pr apps/theming-designer @microsoft/fluentui-react apps/ssr-tests-v9 @microsoft/fluentui-react-build apps/react-18-tests-v8 @microsoft/cxe-red @micahgodbolt -apps/react-18-tests-v9 @microsoft/cxe-red @micahgodbolt +apps/react-18-tests-v9 @microsoft/fluentui-react-build #### Packages packages/azure-themes @Jacqueline-ms @robtaft-ms @@ -163,15 +163,15 @@ packages/react-components/react-positioning @microsoft/teams-prg packages/react-components/react-overflow @microsoft/teams-prg packages/react-components/react-overflow/library @microsoft/teams-prg packages/react-components/react-overflow/stories @microsoft/teams-prg -packages/react-components/react-shared-contexts @microsoft/teams-prg @microsoft/cxe-red -packages/react-components/react-shared-contexts/library @microsoft/teams-prg @microsoft/cxe-red -packages/react-components/react-shared-contexts/stories @microsoft/teams-prg @microsoft/cxe-red +packages/react-components/react-shared-contexts @microsoft/teams-prg @microsoft/cxe-prg +packages/react-components/react-shared-contexts/library @microsoft/teams-prg @microsoft/cxe-prg +packages/react-components/react-shared-contexts/stories @microsoft/teams-prg @microsoft/cxe-prg packages/react-components/react-storybook-addon @microsoft/cxe-prg packages/react-components/react-tabster @microsoft/teams-prg packages/react-components/react-theme @microsoft/teams-prg packages/react-components/react-theme/library @microsoft/teams-prg packages/react-components/react-theme/stories @microsoft/teams-prg -packages/react-components/react-utilities @microsoft/teams-prg +packages/react-components/react-utilities @microsoft/teams-prg @microsoft/cxe-prg packages/storybook @microsoft/cxe-prg @microsoft/teams-prg packages/style-utilities @dzearing @microsoft/cxe-red packages/style-utilities/src/interfaces @phkuo @dzearing @microsoft/cxe-red @@ -188,50 +188,50 @@ common/_common.scss @microsoft/cxe-red @phkuo ## vNext packages packages/react-components/keyboard-keys @microsoft/teams-prg -packages/react-components/react-accordion @microsoft/cxe-red -packages/react-components/react-accordion/library @microsoft/cxe-red -packages/react-components/react-accordion/stories @microsoft/cxe-red -packages/react-components/react-avatar @microsoft/cxe-red @behowell @khmakoto @sopranopillow -packages/react-components/react-avatar/library @microsoft/cxe-red @behowell @khmakoto @sopranopillow -packages/react-components/react-avatar/stories @microsoft/cxe-red @behowell @khmakoto @sopranopillow -packages/react-components/react-badge @microsoft/cxe-red @behowell -packages/react-components/react-badge/library @microsoft/cxe-red @behowell -packages/react-components/react-badge/stories @microsoft/cxe-red @behowell +packages/react-components/react-accordion @microsoft/cxe-prg +packages/react-components/react-accordion/library @microsoft/cxe-prg +packages/react-components/react-accordion/stories @microsoft/cxe-prg +packages/react-components/react-avatar @microsoft/cxe-prg +packages/react-components/react-avatar/library @microsoft/cxe-prg +packages/react-components/react-avatar/stories @microsoft/cxe-prg +packages/react-components/react-badge @microsoft/cxe-prg +packages/react-components/react-badge/library @microsoft/cxe-prg +packages/react-components/react-badge/stories @microsoft/cxe-prg packages/react-components/react-button @microsoft/cxe-red @khmakoto packages/react-components/react-button/library @microsoft/cxe-red @khmakoto packages/react-components/react-button/stories @microsoft/cxe-red @khmakoto packages/react-components/react-card @microsoft/cxe-prg @marcosmoura packages/react-components/react-card/library @microsoft/cxe-prg @marcosmoura packages/react-components/react-card/stories @microsoft/cxe-prg @marcosmoura -packages/react-components/react-checkbox @microsoft/cxe-red @khmakoto -packages/react-components/react-checkbox/library @microsoft/cxe-red @khmakoto -packages/react-components/react-checkbox/stories @microsoft/cxe-red @khmakoto -packages/react-components/react-combobox @microsoft/cxe-red @microsoft/teams-prg @smhigley -packages/react-components/react-combobox/library @microsoft/cxe-red @microsoft/teams-prg @smhigley -packages/react-components/react-combobox/stories @microsoft/cxe-red @microsoft/teams-prg @smhigley +packages/react-components/react-checkbox @microsoft/cxe-prg +packages/react-components/react-checkbox/library @microsoft/cxe-prg +packages/react-components/react-checkbox/stories @microsoft/cxe-prg +packages/react-components/react-combobox @microsoft/cxe-prg @microsoft/teams-prg +packages/react-components/react-combobox/library @microsoft/cxe-prg @microsoft/teams-prg +packages/react-components/react-combobox/stories @microsoft/cxe-prg @microsoft/teams-prg packages/react-components/react-components @microsoft/fluentui-react packages/react-components/react-dialog @microsoft/teams-prg packages/react-components/react-dialog/library @microsoft/teams-prg packages/react-components/react-dialog/stories @microsoft/teams-prg -packages/react-components/react-divider @microsoft/cxe-red -packages/react-components/react-divider/library @microsoft/cxe-red -packages/react-components/react-divider/stories @microsoft/cxe-red -packages/react-components/react-field @microsoft/cxe-red @behowell -packages/react-components/react-field/library @microsoft/cxe-red @behowell -packages/react-components/react-field/stories @microsoft/cxe-red @behowell +packages/react-components/react-divider @microsoft/cxe-prg +packages/react-components/react-divider/library @microsoft/cxe-prg +packages/react-components/react-divider/stories @microsoft/cxe-prg +packages/react-components/react-field @microsoft/cxe-prg +packages/react-components/react-field/library @microsoft/cxe-prg +packages/react-components/react-field/stories @microsoft/cxe-prg packages/react-focus @microsoft/cxe-red @khmakoto packages/react-components/react-image @microsoft/cxe-prg packages/react-components/react-image/library @microsoft/cxe-prg packages/react-components/react-image/stories @microsoft/cxe-prg -packages/react-components/react-input @microsoft/cxe-red @spmonahan -packages/react-components/react-input/library @microsoft/cxe-red @spmonahan -packages/react-components/react-input/stories @microsoft/cxe-red @spmonahan -packages/react-components/react-label @microsoft/cxe-red @sopranopillow @micahgodbolt -packages/react-components/react-label/library @microsoft/cxe-red @sopranopillow @micahgodbolt -packages/react-components/react-label/stories @microsoft/cxe-red @sopranopillow @micahgodbolt -packages/react-components/react-link @microsoft/cxe-red @khmakoto -packages/react-components/react-link/library @microsoft/cxe-red @khmakoto -packages/react-components/react-link/stories @microsoft/cxe-red @khmakoto +packages/react-components/react-input @microsoft/cxe-prg +packages/react-components/react-input/library @microsoft/cxe-prg +packages/react-components/react-input/stories @microsoft/cxe-prg +packages/react-components/react-label @microsoft/cxe-prg +packages/react-components/react-label/library @microsoft/cxe-prg +packages/react-components/react-label/stories @microsoft/cxe-prg +packages/react-components/react-link @microsoft/cxe-prg +packages/react-components/react-link/library @microsoft/cxe-prg +packages/react-components/react-link/stories @microsoft/cxe-prg packages/react-components/react-menu @microsoft/teams-prg packages/react-components/react-menu/library @microsoft/teams-prg packages/react-components/react-menu/stories @microsoft/teams-prg @@ -247,33 +247,33 @@ packages/react-components/react-provider/stories @microsoft/teams-prg packages/react-components/react-radio @microsoft/cxe-red @behowell @spmonahan packages/react-components/react-radio/library @microsoft/cxe-red @behowell @spmonahan packages/react-components/react-radio/stories @microsoft/cxe-red @behowell @spmonahan -packages/react-components/react-select @microsoft/cxe-red @smhigley -packages/react-components/react-select/library @microsoft/cxe-red @smhigley -packages/react-components/react-select/stories @microsoft/cxe-red @smhigley -packages/react-components/react-slider @microsoft/cxe-red @micahgodbolt -packages/react-components/react-slider/library @microsoft/cxe-red @micahgodbolt -packages/react-components/react-slider/stories @microsoft/cxe-red @micahgodbolt -packages/react-components/react-spinbutton @microsoft/cxe-red @spmonahan -packages/react-components/react-spinbutton/library @microsoft/cxe-red @spmonahan -packages/react-components/react-spinbutton/stories @microsoft/cxe-red @spmonahan -packages/react-components/react-spinner @microsoft/cxe-red @tomi-msft -packages/react-components/react-spinner/library @microsoft/cxe-red @tomi-msft -packages/react-components/react-spinner/stories @microsoft/cxe-red @tomi-msft -packages/react-components/react-switch @microsoft/cxe-red @behowell @khmakoto -packages/react-components/react-switch/library @microsoft/cxe-red @behowell @khmakoto -packages/react-components/react-switch/stories @microsoft/cxe-red @behowell @khmakoto +packages/react-components/react-select @microsoft/cxe-prg +packages/react-components/react-select/library @microsoft/cxe-prg +packages/react-components/react-select/stories @microsoft/cxe-prg +packages/react-components/react-slider @microsoft/cxe-prg +packages/react-components/react-slider/library @microsoft/cxe-prg +packages/react-components/react-slider/stories @microsoft/cxe-prg +packages/react-components/react-spinbutton @microsoft/cxe-prg +packages/react-components/react-spinbutton/library @microsoft/cxe-prg +packages/react-components/react-spinbutton/stories @microsoft/cxe-prg +packages/react-components/react-spinner @microsoft/cxe-prg +packages/react-components/react-spinner/library @microsoft/cxe-prg +packages/react-components/react-spinner/stories @microsoft/cxe-prg +packages/react-components/react-switch @microsoft/cxe-prg +packages/react-components/react-switch/library @microsoft/cxe-prg +packages/react-components/react-switch/stories @microsoft/cxe-prg packages/react-components/react-tabs @microsoft/cxe-prg @dmytrokirpa packages/react-components/react-tabs/library @microsoft/cxe-prg @dmytrokirpa packages/react-components/react-tabs/stories @microsoft/cxe-prg @dmytrokirpa packages/react-components/react-text @microsoft/cxe-prg @marcosmoura packages/react-components/react-text/library @microsoft/cxe-prg @marcosmoura packages/react-components/react-text/stories @microsoft/cxe-prg @marcosmoura -packages/react-components/react-textarea @microsoft/cxe-red @sopranopillow -packages/react-components/react-textarea/library @microsoft/cxe-red @sopranopillow -packages/react-components/react-textarea/stories @microsoft/cxe-red @sopranopillow -packages/react-components/react-tooltip @microsoft/cxe-red @behowell @khmakoto -packages/react-components/react-tooltip/library @microsoft/cxe-red @behowell @khmakoto -packages/react-components/react-tooltip/stories @microsoft/cxe-red @behowell @khmakoto +packages/react-components/react-textarea @microsoft/cxe-prg +packages/react-components/react-textarea/library @microsoft/cxe-prg +packages/react-components/react-textarea/stories @microsoft/cxe-prg +packages/react-components/react-tooltip @microsoft/cxe-prg +packages/react-components/react-tooltip/library @microsoft/cxe-prg +packages/react-components/react-tooltip/stories @microsoft/cxe-prg packages/react-components/react-toolbar @microsoft/teams-prg @chpalac @ling1726 packages/react-components/react-toolbar/library @microsoft/teams-prg @chpalac @ling1726 packages/react-components/react-toolbar/stories @microsoft/teams-prg @chpalac @ling1726 @@ -286,32 +286,32 @@ packages/react-components/babel-preset-global-context @microsoft/teams-prg packages/react-components/react-table @microsoft/teams-prg packages/react-components/react-table/library @microsoft/teams-prg packages/react-components/react-table/stories @microsoft/teams-prg -packages/react-components/react-progress @microsoft/cxe-red @tomi-msft -packages/react-components/react-progress/library @microsoft/cxe-red @tomi-msft -packages/react-components/react-progress/stories @microsoft/cxe-red @tomi-msft -packages/react-components/react-persona @microsoft/cxe-red @sopranopillow -packages/react-components/react-persona/library @microsoft/cxe-red @sopranopillow -packages/react-components/react-persona/stories @microsoft/cxe-red @sopranopillow +packages/react-components/react-progress @microsoft/cxe-prg +packages/react-components/react-progress/library @microsoft/cxe-prg +packages/react-components/react-progress/stories @microsoft/cxe-prg +packages/react-components/react-persona @microsoft/cxe-prg +packages/react-components/react-persona/library @microsoft/cxe-prg +packages/react-components/react-persona/stories @microsoft/cxe-prg packages/react-components/react-tree @microsoft/teams-prg packages/react-components/react-tree/library @microsoft/teams-prg packages/react-components/react-tree/stories @microsoft/teams-prg packages/react-components/react-virtualizer @microsoft/xc-uxe @Mitch-At-Work packages/react-components/react-virtualizer/library @microsoft/xc-uxe @Mitch-At-Work packages/react-components/react-virtualizer/stories @microsoft/xc-uxe @Mitch-At-Work -packages/react-components/react-skeleton @microsoft/cxe-red -packages/react-components/react-skeleton/library @microsoft/cxe-red -packages/react-components/react-skeleton/stories @microsoft/cxe-red +packages/react-components/react-skeleton @microsoft/cxe-prg +packages/react-components/react-skeleton/library @microsoft/cxe-prg +packages/react-components/react-skeleton/stories @microsoft/cxe-prg packages/tokens @microsoft/teams-prg -packages/react-components/react-tags @microsoft/cxe-red @microsoft/teams-prg -packages/react-components/react-tags/library @microsoft/cxe-red @microsoft/teams-prg -packages/react-components/react-tags/stories @microsoft/cxe-red @microsoft/teams-prg +packages/react-components/react-tags @microsoft/cxe-prg @microsoft/teams-prg +packages/react-components/react-tags/library @microsoft/cxe-prg @microsoft/teams-prg +packages/react-components/react-tags/stories @microsoft/cxe-prg @microsoft/teams-prg packages/react-components/react-migration-v0-v9/library @microsoft/teams-prg packages/react-components/react-migration-v0-v9/stories @microsoft/teams-prg -packages/react-components/react-datepicker-compat @microsoft/cxe-red @sopranopillow @khmakoto -packages/react-components/react-datepicker-compat/library @microsoft/cxe-red @sopranopillow @khmakoto -packages/react-components/react-datepicker-compat/stories @microsoft/cxe-red @sopranopillow @khmakoto -packages/react-components/react-migration-v8-v9/library @microsoft/cxe-red @geoffcoxmsft -packages/react-components/react-migration-v8-v9/stories @microsoft/cxe-red @geoffcoxmsft +packages/react-components/react-datepicker-compat @microsoft/cxe-prg +packages/react-components/react-datepicker-compat/library @microsoft/cxe-prg +packages/react-components/react-datepicker-compat/stories @microsoft/cxe-prg +packages/react-components/react-migration-v8-v9/library @microsoft/cxe-prg @geoffcoxmsft +packages/react-components/react-migration-v8-v9/stories @microsoft/cxe-prg @geoffcoxmsft packages/react-components/react-breadcrumb @microsoft/cxe-prg packages/react-components/react-breadcrumb/library @microsoft/cxe-prg packages/react-components/react-breadcrumb/stories @microsoft/cxe-prg @@ -324,9 +324,9 @@ packages/react-components/react-jsx-runtime @microsoft/teams-prg packages/react-components/react-toast @microsoft/teams-prg packages/react-components/react-toast/library @microsoft/teams-prg packages/react-components/react-toast/stories @microsoft/teams-prg -packages/react-components/react-search @microsoft/cxe-red @smhigley -packages/react-components/react-search/library @microsoft/cxe-red @smhigley -packages/react-components/react-search/stories @microsoft/cxe-red @smhigley +packages/react-components/react-search @microsoft/cxe-prg +packages/react-components/react-search/library @microsoft/cxe-prg +packages/react-components/react-search/stories @microsoft/cxe-prg packages/react-components/react-colorpicker-compat @microsoft/cxe-red @sopranopillow packages/react-components/react-nav-preview @microsoft/cxe-red @microsoft/xc-uxe @mltejera packages/react-components/react-nav-preview/library @microsoft/cxe-red @microsoft/xc-uxe @mltejera @@ -334,18 +334,18 @@ packages/react-components/react-nav-preview/stories @microsoft/cxe-red @microsof packages/react-components/react-message-bar @microsoft/teams-prg packages/react-components/react-message-bar/library @microsoft/teams-prg packages/react-components/react-message-bar/stories @microsoft/teams-prg -packages/react-components/react-rating @microsoft/cxe-red @tomi-msft -packages/react-components/react-rating/library @microsoft/cxe-red @tomi-msft -packages/react-components/react-rating/stories @microsoft/cxe-red @tomi-msft +packages/react-components/react-rating @microsoft/cxe-prg +packages/react-components/react-rating/library @microsoft/cxe-prg +packages/react-components/react-rating/stories @microsoft/cxe-prg packages/react-components/react-swatch-picker @microsoft/cxe-prg packages/react-components/react-swatch-picker/library @microsoft/cxe-prg packages/react-components/react-swatch-picker/stories @microsoft/cxe-prg -packages/react-components/react-calendar-compat @microsoft/cxe-red @sopranopillow -packages/react-components/react-calendar-compat/library @microsoft/cxe-red @sopranopillow -packages/react-components/react-calendar-compat/stories @microsoft/cxe-red @sopranopillow -packages/react-components/react-infolabel @microsoft/cxe-red @sopranopillow -packages/react-components/react-infolabel/library @microsoft/cxe-red @sopranopillow -packages/react-components/react-infolabel/stories @microsoft/cxe-red @sopranopillow +packages/react-components/react-calendar-compat @microsoft/cxe-prg +packages/react-components/react-calendar-compat/library @microsoft/cxe-prg +packages/react-components/react-calendar-compat/stories @microsoft/cxe-prg +packages/react-components/react-infolabel @microsoft/cxe-prg +packages/react-components/react-infolabel/library @microsoft/cxe-prg +packages/react-components/react-infolabel/stories @microsoft/cxe-prg packages/react-components/react-list-preview @microsoft/teams-prg packages/react-components/react-list-preview/library @microsoft/teams-prg packages/react-components/react-list-preview/stories @microsoft/teams-prg @@ -370,8 +370,8 @@ packages/react-components/react-carousel-preview/stories @microsoft/xc-uxe @micr packages/react-components/recipes @microsoft/fluentui-react @sopranopillow packages/react-components/react-motion-components-preview/library @microsoft/teams-prg packages/react-components/react-motion-components-preview/stories @microsoft/teams-prg -packages/react-components/react-utilities-compat/library @microsoft/cxe-red -packages/react-components/react-utilities-compat/stories @microsoft/cxe-red +packages/react-components/react-utilities-compat/library @microsoft/cxe-prg +packages/react-components/react-utilities-compat/stories @microsoft/cxe-prg packages/react-components/react-color-picker-preview/library @microsoft/cxe-prg packages/react-components/react-color-picker-preview/stories @microsoft/cxe-prg packages/react-components/react-keytips-preview/library @microsoft/cxe-prg diff --git a/.storybook/docs-root.css b/.storybook/docs-root.css index 713bc7f97807bd..81aa81ca4f9357 100644 --- a/.storybook/docs-root.css +++ b/.storybook/docs-root.css @@ -15,12 +15,12 @@ margin-top: 49px; } -#storybook-docs details { +#storybook-docs details:not(.sbdocs-preview details) { position: relative; z-index: 99; } -#storybook-docs .sbdocs:not(.sbdocs-preview) p { +#storybook-docs .sbdocs p:not(.sbdocs-preview p) { font-family: 'Segoe UI', 'Segoe UI Web (West European)', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', sans-serif; font-size: 18px; @@ -45,13 +45,13 @@ border-radius: 24px; } -#storybook-docs .sbdocs:not(.sbdocs-preview) hr { +#storybook-docs .sbdocs hr:not(.sbdocs-preview hr) { margin: 48px 0; height: 0; border-top: 1px solid #ebebeb; } -#storybook-docs .sbdocs h2 { +#storybook-docs .sbdocs h2:not(.sbdocs-preview h2) { font-family: 'Segoe UI', 'Segoe UI Web (West European)', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', sans-serif; font-size: 24px; @@ -64,7 +64,7 @@ padding: 48px 0 0 0; } -#storybook-docs .sbdocs h2 code { +#storybook-docs .sbdocs h2 code:not(.sbdocs-preview h2 code) { border-radius: 4px; font-size: 20px; } @@ -92,7 +92,7 @@ margin: -40px 0 0; } -#storybook-docs .sbdocs:not(.sbdocs-preview) li { +#storybook-docs .sbdocs li:not(.sbdocs-preview li) { font-family: 'Segoe UI', 'Segoe UI Web (West European)', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', sans-serif; font-size: 16px; @@ -104,11 +104,11 @@ margin-top: 8px; } -#storybook-docs .sbdocs:not(.sbdocs-preview) ul { +#storybook-docs .sbdocs ul:not(.sbdocs-preview ul) { margin: 12px 0; } -#storybook-docs .sbdocs-ul .sbdocs:not(.sbdocs-preview) li { +#storybook-docs .sbdocs-ul li:not(.sbdocs-preview .sbdocs-ul li) { list-style: none; position: relative; } @@ -190,26 +190,26 @@ text-decoration: underline; } -/* Styles for Github-flawored Markdown tables */ -#storybook-docs table:not(.docblock-argstable) { +/* Styles for Github-flavored Markdown tables */ +#storybook-docs table:not(.docblock-argstable, .sbdocs-preview table) { margin: 16px 0px; font-size: 14px; line-height: 24px; padding: 0; border-collapse: collapse; } -#storybook-docs table:not(.docblock-argstable) tr { +#storybook-docs table:not(.docblock-argstable, .sbdocs-preview table) tr { border-top: 1px solid rgba(0, 0, 0, 0.1); } -#storybook-docs table:not(.docblock-argstable) th { +#storybook-docs table:not(.docblock-argstable, .sbdocs-preview table) th { font-weight: bold; color: rgb(51, 51, 51); border: 1px solid rgba(0, 0, 0, 0.1); padding: 6px 13px; } -#storybook-docs table:not(.docblock-argstable) td { +#storybook-docs table:not(.docblock-argstable, .sbdocs-preview table) td { border: 1px solid rgba(0, 0, 0, 0.1); padding: 6px 13px; } @@ -276,7 +276,7 @@ line-height: 21px; } -#storybook-docs code, +#storybook-docs code:not(.sbdocs-preview code), #storybook-docs .docblock-argstable tbody tr td:nth-child(3) > div > span, #storybook-docs .docblock-argstable-body > tr > td:nth-child(2) > div:nth-child(2) span, #storybook-docs .docblock-argstable-body > tr > td:nth-child(2) > div:nth-child(1) > div > span, @@ -313,7 +313,7 @@ white-space: normal; } -#storybook-docs code { +#storybook-docs code:not(.sbdocs-preview code) { padding: 0.1em 0.2em; display: inline-block; background-color: rgba(17, 16, 15, 0.1); @@ -426,7 +426,7 @@ h1.fluent { letter-spacing: -0.16px; } -h1 .fluent-version { +h1.fluent .fluent-version { display: block; font-size: 24px; /* --font-size-base-600 */ line-height: 32px; diff --git a/apps/public-docsite-v9/src/Concepts/WebComponentsInterop/UsingFluentReactWithWebComponents.stories.mdx b/apps/public-docsite-v9/src/Concepts/WebComponentsInterop/UsingFluentReactWithWebComponents.stories.mdx index 6f19016d8720dd..9804d9426c0a73 100644 --- a/apps/public-docsite-v9/src/Concepts/WebComponentsInterop/UsingFluentReactWithWebComponents.stories.mdx +++ b/apps/public-docsite-v9/src/Concepts/WebComponentsInterop/UsingFluentReactWithWebComponents.stories.mdx @@ -31,6 +31,8 @@ import { FluentProvider, webLightTheme, Button } from '@fluentui/react-component In the above example, note that `FluentProvider` sits outside the shadow DOM. When `FluentProvider` is inside the shadow DOM styling/theming will not work as expected. +> ⚠️ `FluentProvider` must be in the light DOM for this method to work. + ```tsx // ❌ This will not render correctly, for example purposes only ❌ import { root } from '@fluentui-contrib/react-shadow'; diff --git a/apps/public-docsite-v9/src/DocsComponents/FluentDocsPage.stories.tsx b/apps/public-docsite-v9/src/DocsComponents/FluentDocsPage.stories.tsx index d2c9c19641ac5b..aaf9bf8cc8b023 100644 --- a/apps/public-docsite-v9/src/DocsComponents/FluentDocsPage.stories.tsx +++ b/apps/public-docsite-v9/src/DocsComponents/FluentDocsPage.stories.tsx @@ -1,13 +1,14 @@ import * as React from 'react'; import { DocsContext, - ArgTypes, + ArgsTable, Title, Subtitle, Description, HeaderMdx, Primary, Stories, + type DocsContextProps, } from '@storybook/addon-docs'; import type { SBEnumType } from '@storybook/csf'; import { makeStyles, shorthands, tokens, Link, Text } from '@fluentui/react-components'; @@ -135,6 +136,8 @@ export const FluentDocsPage = () => { const primaryStory = stories[0]; const primaryStoryContext = context.getStoryContext(primaryStory); + assertStoryMetaValues(primaryStory); + const dir = primaryStoryContext.parameters?.dir ?? primaryStoryContext.globals?.[DIR_ID] ?? 'ltr'; const selectedTheme = themes.find(theme => theme.id === primaryStoryContext.globals![THEME_ID]); @@ -171,7 +174,7 @@ export const FluentDocsPage = () => { {primaryStory.name} - + {primaryStory.argTypes.as && primaryStory.argTypes.as?.type?.name === 'enum' && (
@@ -196,3 +199,15 @@ export const FluentDocsPage = () => {
); }; + +function assertStoryMetaValues(story: ReturnType[number]) { + if (story.component === null) { + throw new Error( + [ + '🚨 Invalid Story Meta declaration:', + `- primaryStory.component of componentId:${story.componentId} is "null"`, + '- to resolve this error, please update "component" property value in your story definition to reference a React Component or remove it if it is not needed.', + ].join('\n'), + ); + } +} diff --git a/azure-pipelines.release-vnext-nightly.yml b/azure-pipelines.release-vnext-nightly.yml index 6486a9ef66f01f..8ff8ac0097968f 100644 --- a/azure-pipelines.release-vnext-nightly.yml +++ b/azure-pipelines.release-vnext-nightly.yml @@ -83,15 +83,15 @@ extends: displayName: 'Bump and commit nightly versions' - script: | - yarn nx run react-components:build --nxBai + yarn nx run react-components:build --nxBail displayName: build - script: | - yarn nx run react-components:lint --nxBai + yarn nx run react-components:lint --nxBail displayName: lint - script: | - yarn nx run react-components:test --nxBai + yarn nx run react-components:test --nxBail displayName: test - script: | diff --git a/azure-pipelines.release-vnext.yml b/azure-pipelines.release-vnext.yml index 73c57ca9404ad3..e38b42f809b8e3 100644 --- a/azure-pipelines.release-vnext.yml +++ b/azure-pipelines.release-vnext.yml @@ -70,15 +70,15 @@ extends: displayName: yarn - script: | - yarn nx run-many -t build -p tag:vNext --exclude 'tag:tools,apps/**' --nxBail --production + FLUENT_PROD_BUILD=true yarn nx run-many -t build -p tag:vNext --exclude 'tag:tools,tag:type:stories,apps/**' --nxBail displayName: build - script: | - yarn nx run-many -t test -p tag:vNext --exclude 'tag:tools,apps/**' --nxBail + FLUENT_PROD_BUILD=true yarn nx run-many -t test -p tag:vNext --exclude 'tag:tools,tag:type:stories,apps/**' --nxBail displayName: test - script: | - yarn nx run-many -t lint -p tag:vNext --exclude 'tag:tools,apps/**' --nxBail + FLUENT_PROD_BUILD=true yarn nx run-many -t lint -p tag:vNext --exclude 'tag:tools,tag:type:stories,apps/**' --nxBail displayName: lint - script: | diff --git a/azure-pipelines.release.tools.yml b/azure-pipelines.release.tools.yml index 4bbf06a112c8c2..613d26f156427a 100644 --- a/azure-pipelines.release.tools.yml +++ b/azure-pipelines.release.tools.yml @@ -59,15 +59,15 @@ extends: displayName: yarn - script: | - yarn nx run-many -t build -p tag:tools --exclude 'apps/**' --nxBail --production + FLUENT_PROD_BUILD=true yarn nx run-many -t build -p tag:tools --exclude 'apps/**' --nxBail displayName: build - script: | - yarn nx run-many -t test -p tag:tools --exclude 'apps/**' --nxBail + FLUENT_PROD_BUILD=true yarn nx run-many -t test -p tag:tools --exclude 'apps/**' --nxBail displayName: test - script: | - yarn nx run-many -t lint -p tag:tools --exclude 'apps/**' --nxBail + FLUENT_PROD_BUILD=true yarn nx run-many -t lint -p tag:tools --exclude 'apps/**' --nxBail displayName: lint - script: | diff --git a/change/@fluentui-react-carousel-preview-3334f542-c831-4e06-8558-bad1d236135e.json b/change/@fluentui-react-carousel-preview-3334f542-c831-4e06-8558-bad1d236135e.json new file mode 100644 index 00000000000000..43da3325750ec0 --- /dev/null +++ b/change/@fluentui-react-carousel-preview-3334f542-c831-4e06-8558-bad1d236135e.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "chore: cleanup before the release", + "packageName": "@fluentui/react-carousel-preview", + "email": "olfedias@microsoft.com", + "dependentChangeType": "patch" +} diff --git a/change/@fluentui-react-carousel-preview-f1b94266-3a02-4f4f-924e-a6b3b229ec0f.json b/change/@fluentui-react-carousel-preview-f1b94266-3a02-4f4f-924e-a6b3b229ec0f.json new file mode 100644 index 00000000000000..03b10f297bee4b --- /dev/null +++ b/change/@fluentui-react-carousel-preview-f1b94266-3a02-4f4f-924e-a6b3b229ec0f.json @@ -0,0 +1,7 @@ +{ + "type": "minor", + "comment": "feat: Add CarouselNavContainer for easy layout options, add missing exports and cleanup focus behavior of multiple cards", + "packageName": "@fluentui/react-carousel-preview", + "email": "mifraser@microsoft.com", + "dependentChangeType": "patch" +} diff --git a/change/@fluentui-react-dialog-a4232c34-ea7b-4222-a164-74574abfa9e1.json b/change/@fluentui-react-dialog-a4232c34-ea7b-4222-a164-74574abfa9e1.json new file mode 100644 index 00000000000000..2b0f889f3fd041 --- /dev/null +++ b/change/@fluentui-react-dialog-a4232c34-ea7b-4222-a164-74574abfa9e1.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "fix: Adjust window height comparison in fractional cases.", + "packageName": "@fluentui/react-dialog", + "email": "owcampbe@microsoft.com", + "dependentChangeType": "patch" +} diff --git a/change/@fluentui-react-drawer-6bf581dd-1ead-41a7-8f5c-1e543da04967.json b/change/@fluentui-react-drawer-6bf581dd-1ead-41a7-8f5c-1e543da04967.json new file mode 100644 index 00000000000000..6afb42d0f39454 --- /dev/null +++ b/change/@fluentui-react-drawer-6bf581dd-1ead-41a7-8f5c-1e543da04967.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "fix: update scroll state when children changes", + "packageName": "@fluentui/react-drawer", + "email": "marcosvmmoura@gmail.com", + "dependentChangeType": "patch" +} diff --git a/change/@fluentui-react-provider-3bd9a3d1-66ee-4ddd-a588-4705107c3820.json b/change/@fluentui-react-provider-3bd9a3d1-66ee-4ddd-a588-4705107c3820.json deleted file mode 100644 index 74d34f9f18cc84..00000000000000 --- a/change/@fluentui-react-provider-3bd9a3d1-66ee-4ddd-a588-4705107c3820.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "none", - "comment": "docs: remove now-uneeded comment on tree", - "packageName": "@fluentui/react-provider", - "email": "sarah.higley@microsoft.com", - "dependentChangeType": "none" -} diff --git a/change/@fluentui-react-tag-picker-93adf770-e205-4d89-9513-308f47d37af6.json b/change/@fluentui-react-tag-picker-93adf770-e205-4d89-9513-308f47d37af6.json deleted file mode 100644 index d7fe44e0c52c6a..00000000000000 --- a/change/@fluentui-react-tag-picker-93adf770-e205-4d89-9513-308f47d37af6.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "patch", - "comment": "bugfix: ensures input behaviour on text selection", - "packageName": "@fluentui/react-tag-picker", - "email": "bernardo.sunderhus@gmail.com", - "dependentChangeType": "patch" -} diff --git a/change/@fluentui-react-tag-picker-9be006cd-1c03-46c8-a255-b35dd8971bee.json b/change/@fluentui-react-tag-picker-9be006cd-1c03-46c8-a255-b35dd8971bee.json deleted file mode 100644 index c80020a4e2f726..00000000000000 --- a/change/@fluentui-react-tag-picker-9be006cd-1c03-46c8-a255-b35dd8971bee.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "patch", - "comment": "fix(react-tag-picker): allows TagPickerGroup to be disabled", - "packageName": "@fluentui/react-tag-picker", - "email": "jiangemma@microsoft.com", - "dependentChangeType": "patch" -} diff --git a/change/@fluentui-react-tags-85ae0473-8232-428f-b0a7-cdb10bbd84df.json b/change/@fluentui-react-tags-85ae0473-8232-428f-b0a7-cdb10bbd84df.json deleted file mode 100644 index d38069dcc85c35..00000000000000 --- a/change/@fluentui-react-tags-85ae0473-8232-428f-b0a7-cdb10bbd84df.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "patch", - "comment": "fix(react-tags): allows TagGroup to be disabled", - "packageName": "@fluentui/react-tags", - "email": "jiangemma@microsoft.com", - "dependentChangeType": "patch" -} diff --git a/change/@fluentui-react-tree-a5434551-fc6b-46b6-8aed-3f40515ba2b0.json b/change/@fluentui-react-tree-a5434551-fc6b-46b6-8aed-3f40515ba2b0.json deleted file mode 100644 index 2d206e64f480a2..00000000000000 --- a/change/@fluentui-react-tree-a5434551-fc6b-46b6-8aed-3f40515ba2b0.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "patch", - "comment": "fix: remove unnecessary aria-hidden attributes that were causing accessibility issues", - "packageName": "@fluentui/react-tree", - "email": "sarah.higley@microsoft.com", - "dependentChangeType": "patch" -} diff --git a/docs/react-v9/contributing/rfcs/react-components/convergence/assets/arbitrary-z-index-values.png b/docs/react-v9/contributing/rfcs/react-components/convergence/assets/arbitrary-z-index-values.png new file mode 100644 index 00000000000000..fef9362115dc79 Binary files /dev/null and b/docs/react-v9/contributing/rfcs/react-components/convergence/assets/arbitrary-z-index-values.png differ diff --git a/docs/react-v9/contributing/rfcs/react-components/convergence/extended-design-tokens.md b/docs/react-v9/contributing/rfcs/react-components/convergence/extended-design-tokens.md new file mode 100644 index 00000000000000..c66f0b8ec932a6 --- /dev/null +++ b/docs/react-v9/contributing/rfcs/react-components/convergence/extended-design-tokens.md @@ -0,0 +1,461 @@ +# Extended tokens for Fluent UI React + +A proposal for cross-platform customization by extending existing Design Tokens. + +**✍️ Document owners:** Brandon Thomas, Peter Jahn, Ed Wang + +**🎯 Document objectives**: Inform, discuss, decide, align, execute + +**✏️ Document status**: Review + +**🎬 Prototypes and demo PRs:** + +- [(Architecture Prototype): Extended tokens on each component](https://github.com/microsoft/fluentui/pull/31330) + + - [Default Button Demo](https://fluentuipr.z22.web.core.windows.net/pull/31330/public-docsite-v9/storybook/index.html?path=/docs/components-button-button--default#appearance) + + - [ToggleButton Demo](https://fluentuipr.z22.web.core.windows.net/pull/31330/public-docsite-v9/storybook/index.html?path=/docs/components-button-togglebutton--default#appearance) + + - [ComboBox Demo](https://fluentuipr.z22.web.core.windows.net/pull/31330/public-docsite-v9/storybook/index.html?path=/docs/components-combobox--default#appearance) + + - [Switch Demo](https://fluentuipr.z22.web.core.windows.net/pull/31330/public-docsite-v9/storybook/index.html?path=/docs/components-switch--default#checked) + +- [(Architecture Prototype): Adding semantic tokens to FluentProvider typing](https://github.com/microsoft/fluentui/pull/32104) + +- [(Performance testing): on tokens.ts (not actual architecture)](https://github.com/microsoft/fluentui/pull/31672) + +- [(Performance testing): on each component for Teams](https://github.com/microsoft/fluentui/pull/31692) + +- [(Performance testing): hashed tokens for bundle size](https://github.com/microsoft/fluentui/pull/32304) + +**🎨 Design WIP** + +- [Control and Semantics Tokens Figma File with components](https://www.figma.com/design/QvbzVbuxcLKGMTNCHpAsjt/Fluent-Semantic-Token-Library?m=auto&node-id=11392-41202&t=UupAnqOZkQ3PuSbj-1) + +- [Figma plugin for exporting extended tokens set](https://github.com/Jeremy-Knudsen/Fluent-Tokens-Exporter) + +- [Script for pruning Control, Semantic, and Alias tokens into smallest set](https://github.com/EdDaWord/design-tokens-collapse) + +**📖 Related RFCs**: + +- [RFC: Custom Styling](https://github.com/microsoft/fluentui/blob/master/docs/react-v9/contributing/rfcs/react-components/convergence/custom-styling.md) + +- [RFC: Theme Tokens](https://github.com/microsoft/fluentui/blob/master/docs/react-v9/contributing/rfcs/react-components/convergence/theme-tokens.md) + +- [RFC: Reduce number of shared color alias tokens](https://github.com/microsoft/fluentui/blob/master/docs/react-v9/contributing/rfcs/react-components/convergence/theme-shared-colors.md) + +- [RFC: Update theme shape](https://github.com/microsoft/fluentui/blob/master/docs/react-v9/contributing/rfcs/react-components/convergence/theme-shape.md) + +**🎤 Types of feedback requested:** + +- Implementation suggestions, especially on var() fallback strategy. + +- Performance considerations. + +- Dev experience. + +- Insight on open questions. + +## Summary + +This RFC outlines implementation details for an expansion of Fluent UI React's token system to enable better cross-platform support and more intuitive and predictable customization. **It is effectively adding an additional component token layer to complete the original tokens proposal, which today only includes global and alias.** + +It is also part of a broader effort to align and unify tokens across various implementations of Microsoft's design system. This expanded token system will also serve as a mechanism to achieve visual alignment between products and libraries implementing Fluent 2. + +## Background + +Increasingly, Fluent is being asked to deliver common shared experiences which can show up on platforms that have different UX styling from out-of-the-box Fluent 2 web libraries (Windows, mobile). Often these experiences require a common design spec but use different UI libraries and platform technologies to implement, such as React or Web Components on web, or Compose and XML on Android. + +Keeping these experiences visually aligned requires a token system with enough fidelity to make component-level adjustments to ensure UI elements feel natural on every platform without requiring wholesale restyling or expensive to build and maintain conditional rendering (e.g. rendering custom UI for specific platforms). + +In the long term, a more flexible token system also helps Fluent UI React (FUIR) be more resilient to design language changes in response to evolving business needs. + +## Problems with current Fluent tokens ecosystem + +Fluent UI React's current token system and the broader Fluent tokens ecosystem have three core shortcomings that make it challenging to fully support cross-platform, theme-based customization. + +1. Current FUIR tokens lack component-level tokens. + +2. Alias token names lack usage semantics: Density + +3. Token names and semantics differ between platforms and libraries + +## Current FUIR tokens lack component tokens + +The current Theme definition only supports global and alias tokens, with no support for component-level tokens. This has been discussed previously ([Theme Tokens](https://github.com/microsoft/fluentui/blob/6e6a1bf624e5a682b3607d918793d6f0eeb6b12a/rfcs/react-components/convergence/theme-tokens.md#component-tokens), [Custom Styling](https://github.com/microsoft/fluentui/blob/6e6a1bf624e5a682b3607d918793d6f0eeb6b12a/rfcs/react-components/convergence/custom-styling.md#extended-design-tokens)), but never implemented due to the [performance cost](https://github.com/microsoft/fluentui/blob/6e6a1bf624e5a682b3607d918793d6f0eeb6b12a/rfcs/react-components/convergence/theme-shape.md#performance-analysis) from the number of CSS variables that would be injected. As a result, the system doesn't have enough fidelity to support different platforms' component customization needs at the _theming layer_. + +Additionally, FUIR's components consume these alias tokens directly: + +```javascript +// useButtonStyles.styles.ts +const useRootBaseClassName = makeStyles({ + ... + backgroundColor: tokens.colorNeutralBackground1, + ... +}); +``` + +This effectively tightly-couples components together from a styling POV. There is no abstraction layer at the component level to prevent theme-level token changes from affecting other components. + +Example: Changing the border radius and border width of all Button components through the theme requires modifying borderRadiusMedium and strokeWidthThin, which are used extensively throughout the library. There is no way to change these values at the theme layer just for Buttons without affecting other components. + +The CustomStyleHook is an alternative that enables deeper customization of all instances of a specific component, but this is limited to apps using v9 and React. We need a solution that is agnostic to the rendering tech. + +## Alias token names lack usage semantics + +Fluent's alias tokens add some semantic context to global tokens by assigning design language category, foreground/background, interactive state, and occasionally other descriptors like inverted, static, alpha, etc. These tokens give some meaning to static values, but by design are generic and do not indicate in what contexts they should be used; usage is not self-evident from the names. + +Without this meaning, it can be difficult to know how to apply tokens correctly. For example, the tokens don't differentiate between surfaces (app page, container controls) and control backgrounds, so an app that wanted to use `colorNeutralBackground3` for its page background would find that it is also used as backgrounds for [Tag](https://github.com/microsoft/fluentui/blob/ff79ac88545c9cbc7966f75f61a9d506f3ebb963/packages/react-components/react-tags/src/components/Tag/useTagStyles.styles.ts#L107) or certain variants of [Input](https://github.com/microsoft/fluentui/blob/ff79ac88545c9cbc7966f75f61a9d506f3ebb963/packages/react-components/react-input/src/components/Input/useInputStyles.styles.ts#L181). Adjusting this color at the theme layer would result in styling changes to components that may not have been desired or expected. + +This type of outcome can be mitigated with clearer guidance (documentation, theme typings, UI toolkit notes, etc), but context-specific names that guide developers to the right usage can prevent them from occurring in the first place. + +## Token names and semantics differ between platforms and libraries + +Among apps and libraries implementing Fluent, the conventions for naming tokens/brushes/slots varies in terms of the labels as well as the level of granularity exposed. This isn't strictly an issue with FUIR but presents a challenge when seeking to use a single design spec for a shared experience that renders in multiple contexts. It requires interop layers between theming systems where semantic concepts may not map 1:1, which can lead to issues like inaccessible color pairings or insufficient styling knobs when embedding an experience built with v9 into a host environment. Differences like these are the key motivating factor in the broader tokens unification effort this RFC is representing. + +**Example: WinUI brushes** + +An example is Windows' WinUI brushes, which use more granular labels like text-on-accent-fill-color-primary in addition to more primitive ones like text-fill-color-primary. This table illustrates an attempted mapping of WinUI's Text brushes to Fluent UI's closest equivalent alias tokens, which would be needed to create a "Windows theme" for Fluent UI. Bolded items are missing. + +| WinUI Brush | Closest Fluent UI Alias token | Usage | +| ----------------------------------- | ----------------------------- | ----------------------------------------------------- | +| text-fill-color-primary | Neutral Foreground 1 | Primary text and icon color at rest | +| text-fill-color-secondary | Neutral Foreground 1 hover | Primary text pressed, Secondary text at rest | +| text-fill-color-tertiary | Neutral Foreground 3 | Secondary text pressed. **Not accessible on Windows** | +| text-fill-color-disabled | Neutral Foreground Disabled | Not accessible. Primary text and icon color disabled | +| accent-text-fill-color-primary | Brand Foreground Link | The color of a link | +| accent-text-fill-color-secondary | Brand Foreground Link Hover | Link while hovering | +| accent-text-fill-color-tertiary | Brand Foreground Link Pressed | Link while pressing | +| accent-text-fill-color-disabled | **No direct replacement** | Link while pressing | +| text-on-accent-fill-color-primary | Neutral Foreground on Brand | Primary text and icon color disabled | +| text-on-accent-fill-color-secondary | **No direct replacement** | Primary text and icon color disabled | +| text-on-accent-fill-color-disabled | **No direct replacement** | Primary text and icon color disabled | + +While some of the more generic brushes can map 1:1 with Fluent UI's global or alias tokens, in some cases there are no direct mappings, which would represent a loss of semantic meaning. In practice this would necessitate new alias tokens to ensure full fidelity. + +## Requirements + +1. No disruption to existing Fluent 2 token users. + +2. No or low performance impact. Dimensions to consider: + + a. Bundle size + + b. Reflow calculations + + c. Memory + +## Goals + +1. Backwards-compatibility with existing Fluent 2 tokens. Transparent update to customers. + +2. Unified token API with other Fluent 2 implementations, e.g. Fluent Web Components and WinUI + +## Non-goals + +1. Modify, deprecate, or remove existing tokens. + +2. Require existing themes to consume the new tokens. + +# Proposed changes + +## Solution summary + +We propose extending the token layer to effectively complete the existing system that was originally introduced with the v9 theme shape, which lacked component-specific tokens. + +The changes needed to do this will be **additive**, rather than a replacement. The proposal consists of 3 elements: + +1. New expanded tokens: Semantic and Control tokens + +2. Expose Semantic tokens in Theme via `tokens/src/types.ts` + +3. Update components to optionally consume Control tokens with fallbacks to Semantic if Control in Theme is absent. Similarly if Semantics are absent in Theme then fallback to Alias tokens (Fluent 2). + +## New extended tokens + +The expanded tokens have 2 types of tokens available to customize different aspects of the theme at various levels of granularity. Both are optional, only to be used when customizing specific components in the theme; existing components will always fall back on alias tokens. From more generic to more specific, these token types are: + +1. Semantic tokens + +2. Control tokens + +## Semantic tokens + +Many components share common design elements like spacing, colors, border radius, etc. and can reasonably expect to be customized together as a family. **Semantic tokens** capture these shared design decisions and allow more granular customization of component families compared to alias tokens while keeping the ceiling of additional required tokens lower than if only control-level tokens were used. + +Conceptually they are similar to alias tokens, which also provides semantic meaning with foreground/background and interactive states, but lack the component information of semantic tokens. + +These semantic token groups might include but aren’t limited to: + +- Button + + - Default + + - Brand + + - Outline + + - Subtle + +- Choice + + - Checkbox + + - Radio + +- Input + + - Input + + - Textarea + + - Searchbox + + - SpinButton + +- Progress + + - ProgressBar + + - Spinner + +## Control tokens + +**Control tokens** are used to customize all instances of a specific component or variant. Because they are more narrowly scoped, they should only be used when needing to make precise changes that don't affect related components, or when a semantic token is not available for a particular change. + +Examples: + +- ctrlButtonForegroundColorRest + +- ctrlInputBaseBackgroundColor + +## Token naming: Semantic and control tokens + +Semantic and control tokens use a 6-part structure for creating their names. Like alias tokens, the parts start with broad context and become increasingly granular. Note that not all every part will always be present: for example, base components won’t include variant, and some properties may not include modifiers. + +_Prefix – Component – Variant – Part – Property – Modifier_ + +| Term | Definition | Examples | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| Prefix | Prefix to distinguish control-specific tokens from semantic tokens that might share the same name, e.g. Button. Only applies to control tokens | ctrl / smtc | +| Component | The base UI component or component family, aka semantic group | Button
Switch | +| Variant | A variant of the base component for more specific use cases | Secondary
Compound
Brand | +| Part | A specific element within the default component. Can be a single part or multiple parts. Typically maps to a DOM element | Icon
SecondaryIcon | +| Property | A visual attribute of the Component or Part. Often maps to a CSS property, but not always (e.g. stroke) | ForegroundColor
BackgroundColor
IconAfter
StrokeWidth | +| Modifier | Context that changes the value of a property based on state or mode. Usually maps to an interactive state or mode. | Rest
Hover
Pressed
Disabled
Selected-\* | + +_Variants_ + +The term “variants” is often used to describe alternative forms or styles of components. There are typically 3 types of variants representing different axes of changes: + +1. **Style variant**: Component has a different look and feel, but same behaviors and visual structure as the base component. + + a. In code, v9 typically uses appearance prop + + b. In Figma, the Style property controls these + + c. Example: Button has Secondary, Primary, Subtle, Transparent style variants + +2. **Layout variant**: Component has a different visual structure from the base component, but typically retains the same behaviors and data. Different Parts may be toggled on/off or have different visual treatments due to their composition. + + a. In code, this might be controlled through optional component props e.g. Button icon and iconPosition + + b. In Figma, + + c. Example: Buttons can have just a text label, just an icon, or an icon and Button + +3. **Functional variant**: Component exposes different interactions or data than the base component. + + a. In code, these might be separate components with different APIs + +## Expose expanded tokens in Theme + +Each component that exposes tokens would add a Component.tokens.ts file to expose its tokens API: + +```javascript +// Button.tokens.ts + +import { tokens } from '@fluentui/react-theme'; + +// Semantic button, shared between all Button-family components + +export const buttonGroupTokens = { + + buttonBorderRadius: `var(--buttonBorderRadius, ${tokens.borderRadiusMedium})`, + + buttonFontFamily: `var(--buttonFontFamily,${tokens.fontFamilyBase})`, + + // ... + +} +// Button control tokens, used by Default button + +export const buttonTokens = { + + // Default + + ctrlButtonBorderRadius: `var(--ctrlButtonBorderRadius, ${buttonGroupTokens.buttonBorderRadius})`, + + ctrlButtonFontFamily: `var(--ctrlButtonFontFamily,${buttonGroupTokens.buttonFontFamily})`, + + ... + +} + +``` + +These would then be added to the current Theme object: + +```javascript +// Tokens/src/types.ts +import { ButtonTokens } from '@fluentui/react-components'; + +export type Theme = FontSizeTokens & + LineHeightTokens & + BorderRadiusTokens & + StrokeWidthTokens & + HorizontalSpacingTokens & + VerticalSpacingTokens & + DurationTokens & + CurveTokens & + ShadowTokens & + ShadowBrandTokens & + FontFamilyTokens & + FontWeightTokens & + ColorPaletteTokens & + ColorStatusTokens & + ColorTokens & + ButtonTokens; // Addition +``` + +### Other options considered + +| Option | Pros | Cons | +| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Option A: Add all tokens to current FluentProvider** | • Simple
• Builds on existing API
• No additional deps for partners | • Theme typings will get large as we'd include all component tokens
• Tokens object will get larger but not massive since we'd only ship values for component groups and not component tokens (these are optional slots) | +| Option B.1: Create separate semantic FluentProvider | • Separates Fluent Semantic Tokens (FSTs) from FluentProvider and Theme.
• Optional layering so partners only pull it in when needed. | • Requires extra layer
• May not be as intuitive as just using the existing provider already in applications
• May not provide much value since the components still need to have some level of awareness of the group and component tokens. | +| Option B.2: Create separate semantic FluentProvider and package | • Same pros as above but with added flexibility around packaging and versioning | See above | + +## Update components to optionally consume expanded tokens + +Once exposed in the theme, the new tokens could be accessed in existing components simply by updating existing references to alias tokens with var(), passing the more precise token as the first argument and retaining original alias token as the second. + +For example, instead of: + +```javascript +const useRootBaseClassName = makeStyles({ backgroundColor: 'var(--colorNeutralForeground1)' }); +``` + +We would use this: + +```javascript +const useRootBaseClassName = makeStyles({ + backgroundColor: 'var(--buttonBackgroundColorRest, var(--colorNeutralForeground1))', +}); +``` + +This leverages `var()`’s fallback feature to read the new token’s value first only if defined in the theme, while falling back on the existing alias token if not defined. + +To ensure backwards compatibility with existing themes, all v9 components consuming the new tokens should **always** use alias token fallbacks. + +## Performance + +Given [previously observed performance issues](https://github.com/microsoft/fluentui/blob/6e6a1bf624e5a682b3607d918793d6f0eeb6b12a/rfcs/react-components/convergence/theme-shape.md#performance-analysis) when injecting a class with many CSS variables that referenced other CSS variables, we wanted to be sensitive to bloating the theme object with additional tokens. We noticed that performance penalties in the original tests were not concentrated at variable lookup time, but instead due to the root-level nature of the custom properties: each of the FluentProviders injected tokens that were associated with DOM elements, causing more reflows than would be expected with more scoped properties. + +Our hypothesis is that more granularly scoped tokens tied to fewer DOM nodes would not incur the same performance penalties, although of course this needs to be tested. + +### var() fallback test + +To test the effect of many var() fallbacks, we configured a test using [tensile-perf](https://github.com/microsoft/tensile-perf) to generate an extremely large DOM. We then defined a series of CSS classes with varying levels of fallbacks, often going 20 layers deep. + +[Test repo](https://github.com/brandonthomas/var-fallback-perf-test) _(currently private. Will make public asap)_ + +[Raw tensile-perf test results](https://github.com/brandonthomas/var-fallback-perf-test/tree/main/results) + +In both Chrome and tensile-perf, we saw little to no difference in both render and paint times compared to the baseline. + +Other options considered + +| Option | Pros | Cons | +| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Option A: Update existing components with var() fallbacks** | • Existing consumers automatically get the FST system without additional work beyond updating their packages
• Everyone stays in sync and should have equal capability improving interop and portability | • Once the changes are made, we are somewhat stuck with them (until the next major version)
• All consumers will pull these changes which means some increases in bundle size (gzipped impact seems minor based on our test PR so far). | +| Option B: Custom style hooks | • Fully opt in
• Removes component changes at the root and could allow us to ship separately from the core packages meaning breaking changes could be managed more easily in a separate package | • performance regressions were noted in testing. This might be due to the fact that styles were generated and inserted in runtime. Additionally, it depends on React's context which re-renders components.
• Because it's opt in we wouldn't have uniform adoption

Opportunity: If we can fix the performance issues or understand them better this might be a really interesting option with lower risk. Can we investigate using these styles hooks but with Griffel outputting static CSS? | +| Option C: Create component variants through recomposition | • Could be shipped in separate packages
• avoids breaking changes | • Could create confusion (which Button do consumers use? The base one or our SemanticTokenButton?)
There could be confusing ways in which semantic tokens could work in some places but not others if the right variants aren't used. | + +## Bundle Size + +On option to reduce bundle size is to hash the Control and Semantic tokens. In our tests we've shown a reduction in the GZipped file from [22 kB](https://github.com/microsoft/fluentui/pull/31692) to [18 kB](https://github.com/microsoft/fluentui/pull/32304) + +## Open questions + +In-product performance testing + +To date, we’ve mostly conducted synthetic tests against var() fallback performance. We still need to run integration tests against product scenarios to test real-world effects of additional CSS variables and fallbacks, as well as the overall dev experience. We plan to test this in Teams and will update accordingly. + +### Package location + +Where should the expanded tokens live? We’re leaning towards Option A (**bolded**) now but would like feedback. + +| Option | Pros | Cons | +| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **A: Expanded tokens would be co-located with corresponding components, adjacent to component code** | • Straightforward conceptual grouping for control tokens
• Easier to manage API surface for specific components | • Introduces circular dependency: react-components depends on tokens via react-theme, but not the other way around
• Where to host semantic tokens is less clear since they represent groups of components | +| B: Expanded tokens would be added adjacent to current tokens in @fluentui/tokens | • Doesn't introduce circular dependency
• Single entry point for all tokens
• Simpler to opt-in | • Ergonomics of splitting out component token API from component code might be awkward | +| C: In a new package, e.g. @fluentui/tokens-expanded | • Doesn't introduce circular dependency
• Flexibility around packaging & versioning
• Insulates @fluentui/tokens from control token churn | • More friction to opt-in to expanded tokens
• Adds overhead | + +## How far do we go in exposing semantic tokens? + +The expanded token system opens the door to adding many more tokens than might be needed while growing the API surface. We should consider the strategy we’ll use to scope and prioritize which components and variants will be tokenized, and how tokens will be exposed over time. We’re leaning towards Option C (**bolded**) but would like feedback. + +| Option | Pros | Cons | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Option A: Tokenize everything, even if it's a variant. This includes recreating tokens for those variants even if the base has tokens.

e.g. base button includes ctrlButtonBackgroundRest, rounded would then have ctrlButtonRoundedBackgroundRest | • Tokens can control all aspects of each control and its variants. | • Huge API surface
• A lot more work to implement
• Could easily get out of hand
• Hard to roll back (we basically couldn't) if we find we don't need this level of fidelity | +| Option B: Tokenize only the base styles, and use style overrides for variants and keep the tokens the same for the variants (pointing to alias or globals) aka don't have variant tokens | • Simpler mental model, no figuring out what applies to variants vs base etc. | • Less fidelity and no cross library interop. Overrides have to be done in the context of v9 (this doesn't meet some of our requirements)
• Could still allow for future expansion to include variants | +| **Option C: Tokenize the base and variant overrides only, expand the tokens to include additional variant tokens if needed.** | • Still a somewhat simple mental model but with enough fidelity that we can control what we currently see.
• Matches the way design is approaching this in Figma | • If there is a need to modify variants we might be prevented from doing so within the token system and need to expand it down the road.
• Could still allow for future expansion | + +## Usage guidance + +### Semantic tokens + +The expanded token enables deeper, more portable customization, but adding many extra CSS variables to a theme can have a performance tradeoff. To guide developers to make the most of this system, we’d propose adding the following guidance to the [Styles Handbook](https://github.com/microsoft/fluentui/blob/master/docs/react-v9/contributing/rfcs/react-components/styles-handbook.md) and/or [Theming page](https://react.fluentui.dev/?path=/docs/concepts-developer-theming--page). + +1. **Only include the tokens you need to customize in a theme.** Component tokens are pay-for-play: there is a small but measurable cost to using them. + +2. **Start by customizing semantic tokens, which target groups of components.** Semantic tokens are meant to share styling rules between highly related components. Only use control tokens when you truly need to scope changes to specific components, and take care that customizations are coherent with the application. + +3. Consider if other [v9 customization scenarios](https://github.com/microsoft/fluentui/blob/6e6a1bf624e5a682b3607d918793d6f0eeb6b12a/rfcs/react-components/convergence/custom-styling.md#appendix-current-mechanisms-analysis) meet your needs. Each has capabilities, limitations, and varying complexity that impact suitability. + + a. Custom themes using extended tokens = Customize a single component, family of components, or all components + + b. Custom themes using alias tokens => Customize generic style values for all components + + c. CustomStyleHook => Customize the style of all instances of a component + + d. classname prop => Customize the style of one instance of a component + + e. Hooks recomposition => Create a new component customizing the behavior, style, or rendering of an existing component. + +4. Consider local application or repository policies to limit usage of semantic tokens + +### Custom tokens + +We also propose adding formal guidance and best practices for how to handle **custom tokens** in projects. It might consist of: + +1. Follow Fluent’s naming guidelines for new tokens + +2. Prefix custom tokens with a product/brand prefix, e.g. OneDrive = --od-_token_ + +3. If creating custom tokens targeting a particular platform, always look for a fallback in the existing set + + a. Example: Ensure token extensions fall back to a related control token + +4. Don’t maintain copies of Fluent tokens directly as they are subject to change + +5. Consider creating a “proxy” internal tokens API that merges Fluent tokens and custom product tokens + +6. Clearly denote tokens that are custom and not part of Fluent. Example locations to clarify: + + a. Figma + + b. Code comments + + c. Typings diff --git a/docs/react-v9/contributing/rfcs/react-components/convergence/z-index-handling.md b/docs/react-v9/contributing/rfcs/react-components/convergence/z-index-handling.md new file mode 100644 index 00000000000000..2a8d7703831bab --- /dev/null +++ b/docs/react-v9/contributing/rfcs/react-components/convergence/z-index-handling.md @@ -0,0 +1,337 @@ +# RFC: z-index handling + +--- + +[@marcosmoura](https://github.com/marcosmoura) + +- [RFC: z-index handling](#rfc-z-index-handling) + - [Summary](#summary) + - [Background](#background) + - [Problem statement](#problem-statement) + - [Detailed Design or Proposal](#detailed-design-or-proposal) + - [Research](#research) + - [CSS Isolation and stacking context](#css-isolation-and-stacking-context) + - [Layering/elevation concept](#layeringelevation-concept) + - [What will be covered](#what-will-be-covered) + - [What won't be covered](#what-wont-be-covered) + - [Implementation](#implementation) + - [Pros](#pros) + - [Cons](#cons) + - [Discarded Options](#discarded-options) + - [Expose a named map of layers to z-index values (similarly to typography styles)](#expose-a-named-map-of-layers-to-z-index-values-similarly-to-typography-styles) + - [Pros](#pros-1) + - [Cons](#cons-1) + - [React Context for setting z-index values](#react-context-for-setting-z-index-values) + - [Pros](#pros-2) + - [Cons](#cons-2) + +## Summary + +This RFC outlines the ideas and implementation details for effectively handle z-index globally within Fluent UI components, with a particular focus on standardizing layers across the library. + +## Background + +In [v0](https://github.com/microsoft/fluentui/blob/c3f4b77f8160185518b1fea6d74be239519fba73/packages/style-utilities/src/styles/zIndexes.ts#L1-L11) and [v8](https://github.com/microsoft/fluentui/blob/c3f4b77f8160185518b1fea6d74be239519fba73/packages/fluentui/react-northstar/src/themes/teams/siteVariables.ts#L72-L79), naming conventions were defined to represent the z-index values for each layer. However, for v9, values were not used consistently across the library, leading to a lack of standardization and potential conflicts between components as well as with custom styles in the partner side. + +## Problem statement + +The current z-index handling in Fluent UI v9 is not consistent across components. This inconsistency can be observed by performing a simple code search in the repository: +![z-index inconsistencies](assets/arbitrary-z-index-values.png) + +## Detailed Design or Proposal + +The creation of a global z-index system will help to standardize the values across the library, making it easier to manage and avoid conflicts between components. This system will also provide a way to easily override the z-index values for custom components and applications. + +## Research + +### CSS Isolation and stacking context + +[CSS Isolation](https://developer.mozilla.org/en-US/docs/Web/CSS/isolation) is a new feature that allows developers to create a new stacking context for an element. This means that the element and its children will be rendered isolated from the rest of the page. This can be useful explicitly for components that require a z-index control. +The problem for our case is that we render most of our components that require a z axis control in a portal, which by itself creates a new stacking context. For the elements rendered in a portal, the z-index is relative to the portal element and we need a way to define the priority of them. + +## Layering/elevation concept + +As stated by [Fluent 2 design guidelines](https://fluent2.microsoft.design/elevation), objects/components have a defined elevation value to express its importance and create the sense of hierarchy of layers. These layers should have well defined shadow and z-axis values. Currently, the library have [shadows already defined](https://github.com/marcosmoura/fluentui/blob/943d1f166c5929ff65a683fbed3885434f16f2b9/packages/tokens/src/utils/shadows.ts#L6), but lacking the z-axis values. + +### What will be covered + +This proposal utilize this elevation system to define layers that translate into z-axis values, and those can be used by the components. The concepts are: + +- Each layer have a well-thought z-index number mapped to it +- Multiple components can occupy the same layer, if they share the same importance level in the stack (e.g. Drawer and Nav) +- A component can be defined without a z-index. Its placement fallbacks to its position within the [stack context](https://web.dev/learn/css/z-index/#stacking-context). + +### What won't be covered + +- Negative z-indexes. Components can define negative z-index values to represent background objects. Since this is very subjective, it'll be up to the component to define its own negative z-index values. +- Correlation between shadows and z-indexes. Even though it might be related, this is out of the scope of this proposal. If necessary, it can be covered by a follow-up RFC. + +## Implementation + +> [!NOTE] +> The approach here only standardize the layers and define z-index values for them. This is great for the current state of our components that can define arbitrary values, but won't solve a very specific problem: Defining priority for similar UI elements. e.g. Two Dropdowns are created. Which of them should have higher priority and therefore be displayed on top? + +Expose the z-index values as tokens. This would map the layers into token values that can be used anywhere in styles. + +The layers can be defined as follows: + +```ts +// packages/tokens/src/types.ts + +/** + * Design tokens for z-index groups and levels + */ +export type ZIndexTokens = { + zIndexBackground: string; + zIndexContent: string; + zIndexOverlay: string; + zIndexPopup: string; + zIndexMessages: string; + zIndexFloating: string; + zIndexPriority: string; + zIndexDebug: string; +}; +``` + +```ts +// packages/tokens/src/global/zIndexes.ts + +import type { ZIndexTokens } from '../types'; + +/** + * ZIndex global defaults + */ +export const zIndexes: ZIndexTokens = { + zIndexBackground: '0', // Elevation 0 + zIndexContent: '1', // Elevation 2 + zIndexOverlay: '1000', // Elevation 4 + zIndexPopup: '2000', // Elevation 8 + zIndexMessages: '3000', // Elevation 16 + zIndexFloating: '4000', // Elevation 28 + zIndexPriority: '5000', // Elevation 64 + zIndexDebug: '6000', // Used for debugging +}; +``` + +```ts +// Fluent/partner code + +import { tokens } from '@fluentui/theme'; + +const styles = { + root: { + zIndex: tokens.zIndexOverlay /* var(--zIndexOverlay, 1000) */, + }, +}; +``` + +In case the partner wants to override the z-index values, they can do so by providing a theme with the new values: + +```ts +// Fluent/partner code +import { FluentProvider, Theme, webLightTheme } from '@fluentui/react-components'; + +const customTheme: Theme = { + ...webLightTheme, + // 👇 customized values + zIndexOverlay: 100000, +}; + +function App() { + return ; +} +``` + + + +_NOTE: The names above are not final and only serve as an example. As of the moment this RFC was introduced, there are ongoing discussions with the Design team to define all the layers. This RFC will be updated before the final approval to include the definitive names._ + +### Pros + +- 👍 Clear separation by group of UI elements +- 👍 Easy to override, extend and update +- 👍 Partners can override the tokens through themes + +### Cons + +- 👎 Naming convention can be hard +- 👎 Bloating the tokens with more variables +- 👎 Not possible to validate for user errors. Partners can override the tokens freely. + +## Discarded Options + +The options below were explored but discarded due to the complexity of the implementation. It can be revisited in the future if necessary. + +### Expose a named map of layers to z-index values (similarly to typography styles) + +Exposes a named map of layers to z-index values. This map can be used by components to define their z-index values. +This would required the creation of a new file and export under `@fluentui/tokens`, to make the map available. + +The layers can be defined as follows: + +```ts +// packages/tokens/src/global/zIndexes.ts + +import { ZIndexLayers } from '../types'; + +/** + * Global z-index values for elements + */ +export const zIndexes: ZIndexLayers = { + background: 0, // default + content: 1, // content - header, footer, sidebar + overlay: 1000, // overlay elements - drawer, nav + popup: 2000, // popup layers - popups, modals, dialogs + messages: 3000, // communication elements - banners, messages, toasts, snackbar + floating: 4000, // floating elements - dropdowns, teaching + priority: 5000, // priority elements - tooltips + debug: 6000, // debug - error overlays, debug messages +}; +``` + +```ts +// Fluent/partner code + +import { zIndexes } from '@fluentui/theme'; + +const styles = { + root: { + zIndex: zIndexes.overlay, + }, +}; +``` + + + +_NOTE: The names above are not final and only serve as an example. As of the moment this RFC was introduced, there are ongoing discussions with the Design team to define all the layers. This RFC will be updated before the final approval to include the definitive names._ + +#### Pros + +- 👍 Clear separation by group of UI elements +- 👍 Easy to override on Fluent side, extend and update + +#### Cons + +- 👎 Naming convention can be hard +- 👎 The values would be fixed globally and not possible for partners to override + +### React Context for setting z-index values + +This context would provide a way to set the z-index values for components and retrieve them when necessary. That allows partners to set the z-index themselves delegating the decision of the z-index order, priority and values to the application. It would be possible to set z-index ordering for multiple elements in the same layer. + +```tsx +// partner side +import { FluentProvider } from '@fluentui/react-components'; + +const App = () => { + const zIndex = { + background: 0, + content: 1, + overlay: 1000, + popup: 2000, + messages: 3000, + floating: 4000, + priority: 5000, + debug: 6000, + }; + + return ( + + + + + ); +}; +``` + +```tsx +import { useZIndex } from '@fluentui/react-components'; + +// component side +export const useComponent_unstable = (props: ComponentProps, ref: React.Ref): ComponentState => { + const { overlay } = useZIndex(); + + return { + components: { + root: 'div', + }, + + root: slot.always( + { + ref, + ...props, + style: { + zIndex: overlay, + }, + }, + { + elementType: 'div', + }, + ), + }; +}; +``` + +Or alternatively, a hook that could be used to set the z-index style directly: + +```tsx +import { useZIndexStyle } from '@fluentui/react-components'; + +// component side +export const useComponent_unstable = (props: ComponentProps, ref: React.Ref): ComponentState => { + useZIndexStyle('overlay', ref); + + return { + components: { + root: 'div', + }, + + root: slot.always( + { + ref, + ...props, + }, + { + elementType: 'div', + }, + ), + }; +}; +``` + +Another possibility would be to use a hook to set z-index priority between two elements: + +```tsx +import { useZIndexPriority } from '@fluentui/react-components'; + +// component side +export const Component = (props: ComponentProps) => { + const drawerStartRef = React.useRef(); + const drawerEndRef = React.useRef(); + const navRef = React.useRef(); + + /* + * This would control the z-index of the elements based on the layering group, + * incrementing based on the priority list + */ + useZIndexPriority('overlay', [drawerStartRef, drawerEndRef, navRef]); + + return ( + <> + // z-index 2003 + // z-index 2002 +