From 7110cafa3d044bdc65887b8cd52054065a63f397 Mon Sep 17 00:00:00 2001
From: Dave Rupert <rupertdavid@microsoft.com>
Date: Tue, 2 Jul 2024 12:53:51 -0500
Subject: [PATCH] fix(web-components): fix menu positioning in firefox (#31895)

---
 ...-145140b4-12da-4153-93ce-be8aa02f191b.json |  7 +++
 .../web-components/.storybook/preview.mjs     |  2 +-
 .../_docs/developer/polyfilling.stories.mdx   | 51 +++++++++++++++++++
 .../src/menu-item/menu-item.styles.ts         |  1 +
 4 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 change/@fluentui-web-components-145140b4-12da-4153-93ce-be8aa02f191b.json
 create mode 100644 packages/web-components/src/_docs/developer/polyfilling.stories.mdx

diff --git a/change/@fluentui-web-components-145140b4-12da-4153-93ce-be8aa02f191b.json b/change/@fluentui-web-components-145140b4-12da-4153-93ce-be8aa02f191b.json
new file mode 100644
index 0000000000000..9011922ce9650
--- /dev/null
+++ b/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": "rupertdavid@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/web-components/.storybook/preview.mjs b/packages/web-components/.storybook/preview.mjs
index 83f03428f7096..d16b42a1387f1 100644
--- a/packages/web-components/.storybook/preview.mjs
+++ b/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: {
diff --git a/packages/web-components/src/_docs/developer/polyfilling.stories.mdx b/packages/web-components/src/_docs/developer/polyfilling.stories.mdx
new file mode 100644
index 0000000000000..d4a5758e01735
--- /dev/null
+++ b/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.
diff --git a/packages/web-components/src/menu-item/menu-item.styles.ts b/packages/web-components/src/menu-item/menu-item.styles.ts
index 645a485b1b323..416b3e795b823 100644
--- a/packages/web-components/src/menu-item/menu-item.styles.ts
+++ b/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);