fix(web-components): fix menu positioning in firefox (microsoft#31895)

change/@fluentui-web-components-145140b4-12da-4153-93ce-be8aa02f191b.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "fix(web-components): fix popover positioning in firefox, add docs",
+  "packageName": "@fluentui/web-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -21,7 +21,7 @@ export const parameters = {
   options: {
     storySort: {
       method: 'alphabetical',
-      order: ['Concepts', ['Introduction'], 'Components', 'Theme'],
+      order: ['Concepts', ['Introduction', 'Developer', ['Quick Start']], 'Components', 'Theme'],
     },
   },
   docs: {

packages/web-components/src/_docs/developer/polyfilling.stories.mdx

@@ -0,0 +1,51 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Concepts/Developer/Polyfilling" />
+
+# Polyfilling
+
+Fluent UI Web Components takes a "bring your own polyfill" approach so that projects can opt-in to polyfilling only when necessary. Features gracefully degrade whenever possible but some features might require a small shim to work in older browsers.
+
+## Baseline
+
+Here's a list of features we're leveraging and their current [Baseline](https://web.dev/baseline) browser support.
+
+|                        | Chrome | Edge | Firefox | Safari |
+| ---------------------- | ------ | ---- | ------- | ------ |
+| HTML Popover Attribute | 114    | 114  | 125     | 17     |
+| CSS Anchor Positioning | 125    | 125  | ❌      | ❌     |
+
+## HTML Popover
+
+From Fluent UI Web Components V3 forward, popover-like components will make use of the newer [HTML popover attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover). Broader `[popover]` support beyond the browser baseline will require a polyfill.
+
+To get started, add the [popover polyfill](https://github.com/oddbird/popover-polyfill/) to your package.
+
+```bash
+yarn install @oddbird/popover-polyfill
+```
+
+Then in your `main.js` file after your `setTheme()` call, check for `popover` support and lazily import the package if not supported.
+
+```js
+(async () => {
+  if (!('popover' in HTMLElement.prototype)) {
+    await import('@oddbird/popover-polyfill');
+  }
+})();
+```
+
+Two lines of global CSS are needed to cleanup a potential positioning side effect created by the polyfill and LightDOM authored child components.
+
+```css
+[popover].\:popover-open {
+  inset: unset;
+  border: 1px solid transparent;
+}
+```
+
+<fluent-anchor-button target="_blank" href="https://stackblitz.com/edit/typescript-pqdtqs?file=index.html">Open Demo on StackBlitz</fluent-anchor-button>
+
+## CSS Anchor Positioning
+
+All [CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning) fallbacks are handled minimally in script and CSS. In the near future, we may recommend the [anchor positioning polyfill](https://github.com/oddbird/css-anchor-positioning) but it doesn't cover all of our use cases at this time.

packages/web-components/src/menu-item/menu-item.styles.ts

@@ -149,6 +149,7 @@ export const styles = css`
     }
 
     ::slotted([popover]) {
+      align-self: start; /* Fallback for no anchor-positioning */
       inset-area: inline-end span-block-end;
       margin: 0;
       max-height: var(--menu-max-height, auto);