feat(web-components): enabling setting theme on an individual element and unsetting themes

change/@fluentui-web-components-d74234e0-b903-4c51-af61-599648aee92d.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat(web-components): enabling setting theme on an individual element and unsetting themes",
+  "packageName": "@fluentui/web-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/web-components/.storybook/preview.mjs

@@ -1,15 +1,26 @@
-import { switchTheme } from '../public/theme-switch.js';
+import { teamsDarkTheme, teamsLightTheme, webDarkTheme, webLightTheme } from '@fluentui/tokens';
 import webcomponentsTheme from './theme.mjs';
+import { setTheme } from '../src/theme/set-theme.js';
 
 import '../src/index-rollup.js';
 import './docs-root.css';
 
+const themes = {
+  'web-light': webLightTheme,
+  'web-dark': webDarkTheme,
+  'teams-light': teamsLightTheme,
+  'teams-dark': teamsDarkTheme,
+};
+
 function changeTheme(/** @type {Event} */ e) {
-  switchTheme(/** @type {Parameters<typeof switchTheme>[number]} */ (/** @type {HTMLInputElement}*/ (e.target).value));
+  setTheme(themes[/** @type {keyof themes} */ (/** @type {HTMLInputElement}*/ (e.target).value)]);
 }
 
+// This is needed in Playwright.
+Object.defineProperty(window, 'setTheme', { value: setTheme });
+
 document.getElementById('theme-switch')?.addEventListener('change', changeTheme, false);
-switchTheme('web-light');
+setTheme(themes['web-light']);
 
 export const parameters = {
   layout: 'fullscreen',

packages/web-components/docs/api-report.md

@@ -118,7 +118,6 @@ export const accordionStyles: ElementStyles;
 export const accordionTemplate: ElementViewTemplate<Accordion>;
 
 // Warning: (ae-different-release-tags) This symbol has another declaration with a different release tag
-// Warning: (ae-forgotten-export) The symbol "BaseAnchor" needs to be exported by the entry point index.d.ts
 // Warning: (ae-internal-mixed-release-tag) Mixed release tags are not allowed for "AnchorButton" because one of its declarations is marked as @internal
 //
 // @public
@@ -451,6 +450,30 @@ export class BaseAccordionItem extends FASTElement {
     id: string;
 }
 
+// @public
+export class BaseAnchor extends FASTElement {
+    constructor();
+    // @internal
+    clickHandler(e: PointerEvent): boolean;
+    // (undocumented)
+    connectedCallback(): void;
+    // (undocumented)
+    disconnectedCallback(): void;
+    download?: string;
+    // @internal
+    elementInternals: ElementInternals;
+    // @internal
+    handleChange(source: any, propertyName: string): void;
+    href?: string;
+    hreflang?: string;
+    keydownHandler(e: KeyboardEvent): boolean | void;
+    ping?: string;
+    referrerpolicy?: string;
+    rel: string;
+    target?: AnchorTarget;
+    type?: string;
+}
+
 // @public
 export class BaseAvatar extends FASTElement {
     constructor();
@@ -3033,12 +3056,12 @@ export const roleForMenuItem: {
 // Warning: (ae-internal-missing-underscore) The name "setTheme" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
-export const setTheme: (theme: Theme) => void;
+export function setTheme(theme: Theme | null, node?: Document | HTMLElement): void;
 
 // Warning: (ae-internal-missing-underscore) The name "setThemeFor" should be prefixed with an underscore because the declaration is marked as @internal
 //
-// @internal (undocumented)
-export const setThemeFor: (element: HTMLElement, theme: Theme) => void;
+// @internal @deprecated (undocumented)
+export function setThemeFor(element: HTMLElement, theme: Theme | null): void;
 
 // @public
 export const shadow16 = "var(--shadow16)";

packages/web-components/src/theme/set-theme.spec.ts

@@ -0,0 +1,42 @@
+import { expect, test } from '@playwright/test';
+import { fixtureURL } from '../helpers.tests.js';
+
+import type { setTheme as _setTheme, Theme } from './set-theme.js';
+
+const theme1: Theme = {
+  foo: 'foo1',
+  bar: 'bar1',
+};
+
+const theme2: Theme = {
+  foo: 'foo2',
+  bar: 'bar2',
+};
+
+declare global {
+  interface Window {
+    setTheme: typeof _setTheme;
+  }
+}
+
+test.describe('setTheme()', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto(fixtureURL('theme-settheme--set-theme'));
+    await page.setContent(`<div></div>`);
+  });
+
+  test('should set tokens with the correct custom property values', async ({ page }) => {
+    await page.evaluate(theme => {
+      window.setTheme(theme);
+    }, theme1);
+    const body = page.locator('body');
+
+    await expect(body).toHaveCSS('--foo', 'foo1');
+
+    await page.evaluate(theme => {
+      window.setTheme(theme);
+    }, theme2);
+
+    await expect(body).toHaveCSS('--foo', 'foo2');
+  });
+});

packages/web-components/src/theme/set-theme.stories.ts

@@ -1,17 +1,35 @@
-import { html } from '@microsoft/fast-element';
+import { html, repeat, when } from '@microsoft/fast-element';
 import { teamsDarkTheme, teamsLightTheme, webDarkTheme, webLightTheme } from '@fluentui/tokens';
-
-import type { Story } from '../helpers.stories.js';
+import type { Meta } from '../helpers.stories.js';
 import { renderComponent } from '../helpers.stories.js';
 import type { Theme } from './set-theme.js';
 import { setTheme } from './set-theme.js';
 
-const fluentTheme: Record<string, Theme> = {
-  webLightTheme,
-  webDarkTheme,
-  teamsLightTheme,
-  teamsDarkTheme,
-};
+const themes: Map<string, Theme | null> = new Map([
+  ['web-light', webLightTheme],
+  ['web-dark', webDarkTheme],
+  ['team-light', teamsLightTheme],
+  ['team-dark', teamsDarkTheme],
+  ['unset', null],
+]);
+
+function updateTheme(evt: Event, type = 'global') {
+  const { value } = evt.target as HTMLSelectElement;
+
+  if (themes.has(value) !== undefined) {
+    switch (type) {
+      case 'global':
+        setTheme(themes.get(value)!);
+        break;
+      case 'local':
+        setTheme(themes.get(value)!, document.querySelector('.local') as HTMLElement);
+        break;
+      case 'shadow':
+        setTheme(themes.get(value)!, document.querySelector('.shadow') as HTMLElement);
+        break;
+    }
+  }
+}
 
 const themeDescription = `
 Flat object of theme tokens. Each object entry must follow these rules:
@@ -26,29 +44,13 @@ you can pass in an arbitrary theme object as long as each entry’s value is eit
 
 export default {
   title: 'Theme/SetTheme',
-  argTypes: {
-    theme: {
-      type: 'string',
-      control: 'select',
-      options: Object.keys(fluentTheme),
-      description: themeDescription,
-    },
-  },
-  args: {
-    theme: 'webLightTheme',
-  },
-};
+} as Meta;
 
 const ComponentCloudTemplate = html`
-  <p><fluent-button>A button</fluent-button></p>
-  <p><fluent-spinner></fluent-spinner></p>
-  <p>
-    <fluent-text-input>
-      <fluent-label>Text input</fluent-label>
-    </fluent-text-input>
-  </p>
-  <fluent-divider></fluent-divider>
   <p>
+    <fluent-button>A button</fluent-button>
+    <fluent-spinner></fluent-spinner>
+    <fluent-slider step="10" min="0" max="100"></fluent-slider>
     <fluent-menu>
       <fluent-menu-button appearance="primary" slot="trigger">Toggle Menu</fluent-menu-button>
       <fluent-menu-list>
@@ -59,11 +61,15 @@ const ComponentCloudTemplate = html`
       </fluent-menu-list>
     </fluent-menu>
   </p>
-  <fluent-divider></fluent-divider>
+  <p>
+    <fluent-text-input>
+      <fluent-label>Text input</fluent-label>
+    </fluent-text-input>
+  </p>
   <p>
     <fluent-field>
       <label slot="label" for="radiogroup">Radio group</label>
-      <fluent-radio-group slot="input" id="radiogroup" orientation="vertical">
+      <fluent-radio-group slot="input" id="radiogroup">
         <fluent-field label-position="after">
           <fluent-radio slot="input" id="radiogroup-radio-1"></fluent-radio>
           <label slot="label" for="radiogroup-radio-1">Option 1</label>
@@ -79,23 +85,117 @@ const ComponentCloudTemplate = html`
       </fluent-radio-group>
     </fluent-field>
   </p>
-  <fluent-divider></fluent-divider>
   <p>
     <fluent-field label-position="after">
       <label slot="label" for="checkbox">I would like this option</label>
       <fluent-checkbox slot="input" id="checkbox"></fluent-checkbox>
     </fluent-field>
   </p>
-  <fluent-divider></fluent-divider>
-  <p>
-    <fluent-slider step="10" min="0" max="100"></fluent-slider>
-  </p>
+  <p></p>
+`;
+
+const ThemeOptionsTemplate = (selected: string = '', hasUnset = false) => html`
+  ${when(hasUnset, html`<option value="unset">unset</option>`)}
+  ${repeat(
+    Array.from(themes.keys()),
+    html`
+      ${when(k => k !== 'unset', html` <option ?selected=${k => selected === k} value="${k => k}">${k => k}</option> `)}
+    `,
+  )}
 `;
 
-export const SetTheme: Story = renderComponent(ComponentCloudTemplate);
-SetTheme.decorators = [
-  (Story, { args: { theme } }) => {
-    theme && setTheme(fluentTheme[theme]);
-    return Story();
-  },
-];
+export const SetTheme = renderComponent(html`
+  <style>
+    .toolbar {
+      align-items: end;
+      display: flex;
+      gap: 1rem;
+      border-block-end: 1px solid #ccc;
+      padding-block-end: 2rem;
+
+      label,
+      select {
+        display: flow-root;
+        inline-size: fit-content;
+      }
+
+      label {
+        flex: 1 0 0;
+      }
+
+      select {
+        inline-size: 100%;
+        margin-block-start: 0.5rem;
+        padding: 0.5rem;
+      }
+    }
+
+    .global {
+      margin-block: 2rem;
+    }
+
+    .local {
+      background: var(--colorNeutralBackground2);
+      border: 1px solid #ccc;
+      color: var(--colorNeutralForeground2);
+      padding: 1rem;
+      margin-trim: block;
+
+      & > :first-child {
+        margin-block-start: 0;
+      }
+
+      & > :last-child {
+        margin-block-end: 0;
+      }
+
+      .shadow {
+        background: var(--colorNeutralBackground2);
+        color: var(--colorNeutralForeground2);
+      }
+    }
+
+    fluent-spinner {
+      vertical-align: middle;
+    }
+  </style>
+  <div class="toolbar">
+    <label>
+      Global theme
+      <select @change="${(_, c) => updateTheme(c.event)}">
+        ${ThemeOptionsTemplate('web-light')}
+      </select>
+    </label>
+
+    <label>
+      Local theme (element without shadow root)
+      <select @change="${(_, c) => updateTheme(c.event, 'local')}">
+        ${ThemeOptionsTemplate('', true)}
+      </select>
+    </label>
+
+    <label>
+      Local theme (element with shadow root)
+      <select @change="${(_, c) => updateTheme(c.event, 'shadow')}">
+        ${ThemeOptionsTemplate('', true)}
+      </select>
+    </label>
+  </div>
+
+  <div class="global">
+    <p>These elements follow the global theme</p>
+    ${ComponentCloudTemplate}
+  </div>
+
+  <div class="local">
+    <p>These elements follow the container element’s theme</p>
+    ${ComponentCloudTemplate}
+
+    <fluent-divider></fluent-divider>
+
+    <p>This element (which has shadow root) follows its own theme when set</p>
+    <fluent-text-input class="shadow">
+      <fluent-label>Text input</fluent-label>
+    </fluent-text-input>
+  </div>
+`);