docs(portal): add examples

Author: metonym

docs/src/pages/components/Portal.svx

@@ -0,0 +1,30 @@
+<script>
+  import { Portal, FloatingPortal } from "carbon-components-svelte";
+  import Preview from "../../components/Preview.svelte";
+</script>
+
+The `Portal` component renders its content into a fixed container appended to `document.body`, allowing you to escape parent overflow constraints and z-index stacking contexts. The `FloatingPortal` component extends this functionality with automatic positioning relative to a reference element using the [Floating UI](https://floating-ui.com/) library.
+
+## Default Portal
+
+Render content in a portal container. This is useful for modals, tooltips, and menus that need to escape parent containers.
+
+<FileSource src="/framed/Portal/BasicPortal" />
+
+## Multiple Portals
+
+Multiple portal instances share the same container, which is automatically cleaned up when all instances are removed.
+
+<FileSource src="/framed/Portal/MultiplePortals" />
+
+## 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/BasicPortal.svelte

@@ -0,0 +1,6 @@
+<script>
+  import { Portal } from "carbon-components-svelte";
+</script>
+
+<Portal>Hello world</Portal>
+<Portal>Another portal</Portal>

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>
+

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

@@ -0,0 +1,18 @@
+<script>
+  import { Button, Portal } from "carbon-components-svelte";
+</script>
+
+<Button>Button 1</Button>
+<Portal>
+  <div style="position: absolute; top: 100px; left: 20px; padding: 1rem; background: var(--cds-layer-01); border: 1px solid var(--cds-border-subtle-01);">
+    Portal content 1
+  </div>
+</Portal>
+
+<Button>Button 2</Button>
+<Portal>
+  <div style="position: absolute; top: 150px; left: 20px; padding: 1rem; background: var(--cds-layer-01); border: 1px solid var(--cds-border-subtle-01);">
+    Portal content 2
+  </div>
+</Portal>
+