docs(portal): add floating portal examples

Author: metonym

docs/src/pages/components/Portal.svx

@@ -28,3 +28,15 @@ Use the `tag` prop to specify a custom HTML element. By default, Portal uses a `
 Wrap `Modal` in a `Portal` to escape parent containers with `overflow: hidden` or z-index stacking contexts. This ensures the modal appears above all content and isn't clipped by parent boundaries.
 
 <FileSource src="/framed/Portal/ModalPortal" />
+
+## Floating portal
+
+The `FloatingPortal` component automatically positions content relative to a reference element using [Floating UI](https://floating-ui.com/). This is useful for dropdowns, popovers, and tooltips.
+
+<FileSource src="/framed/Portal/FloatingPortal" />
+
+## Floating portal placement
+
+Control the placement of the floating portal using the `placement` prop.
+
+<FileSource src="/framed/Portal/FloatingPortalPlacement" />

docs/src/pages/framed/Portal/FloatingPortal.svelte

@@ -0,0 +1,22 @@
+<script>
+  import { Button, FloatingPortal } from "carbon-components-svelte";
+
+  let buttonRef = null;
+  let showPortal = false;
+</script>
+
+<Button bind:this={buttonRef} on:click={() => (showPortal = !showPortal)}>
+  Toggle Floating Portal
+</Button>
+
+{#if showPortal && buttonRef}
+  <FloatingPortal reference={buttonRef} placement="bottom" offset={8}>
+    <div style="padding: 1rem; background: var(--cds-layer-01); border: 1px solid var(--cds-border-subtle-01); box-shadow: var(--cds-shadow-03); border-radius: 4px; min-width: 200px;">
+      <p style="margin: 0 0 0.5rem 0;">Floating portal content</p>
+      <p style="margin: 0; font-size: 0.875rem; color: var(--cds-text-secondary);">
+        This content is positioned relative to the button above.
+      </p>
+    </div>
+  </FloatingPortal>
+{/if}
+

docs/src/pages/framed/Portal/FloatingPortalPlacement.svelte

@@ -0,0 +1,53 @@
+<script>
+  import { Button, FloatingPortal } from "carbon-components-svelte";
+
+  let buttonRefs = {};
+  let openPlacements = {};
+
+  const placements = [
+    "top",
+    "top-start",
+    "top-end",
+    "right",
+    "right-start",
+    "right-end",
+    "bottom",
+    "bottom-start",
+    "bottom-end",
+    "left",
+    "left-start",
+    "left-end",
+  ];
+
+  function togglePlacement(placement) {
+    openPlacements[placement] = !openPlacements[placement];
+    openPlacements = { ...openPlacements };
+  }
+</script>
+
+<div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 2rem; padding: 4rem;">
+  {#each placements as placement}
+    <div style="display: flex; justify-content: center; align-items: center;">
+      <Button
+        bind:this={buttonRefs[placement]}
+        on:click={() => togglePlacement(placement)}
+      >
+        {placement}
+      </Button>
+      {#if openPlacements[placement] && buttonRefs[placement]}
+        <FloatingPortal
+          reference={buttonRefs[placement]}
+          placement={placement}
+          offset={8}
+        >
+          <div
+            style="padding: 0.75rem; background: var(--cds-layer-01); border: 1px solid var(--cds-border-subtle-01); box-shadow: var(--cds-shadow-03); border-radius: 4px; white-space: nowrap;"
+          >
+            {placement}
+          </div>
+        </FloatingPortal>
+      {/if}
+    </div>
+  {/each}
+</div>
+