docs(portal): add examples

Author: metonym

docs/src/pages/components/ComposedModal.svx

@@ -18,6 +18,12 @@ Create a modal with a header, body, and footer. Each section can be customized i
 
 <FileSource src="/framed/Modal/ComposedModal" />
 
+## With Portal
+
+Wrap `ComposedModal` in a `Portal` to ensure it renders above all z-index stacking contexts and parent overflow constraints, preventing visual clipping and layering issues.
+
+<FileSource src="/framed/Portal/ComposedModalPortal" />
+
 ## Prevent default close behavior
 
 The modal dispatches a cancelable `close` event, allowing you to prevent the modal from closing using `e.preventDefault()`. The event includes a `trigger` property indicating what triggered the close attempt: `"escape-key"`, `"outside-click"`, or `"close-button"`.

docs/src/pages/components/Modal.svx

@@ -16,6 +16,12 @@ Create a basic modal dialog with primary and secondary actions. This variant is
 
 <FileSource src="/framed/Modal/Modal" />
 
+## With Portal
+
+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" />
+
 ## Custom focus
 
 Control which element receives focus when the modal opens. Use `selectorPrimaryFocus` to specify the target element using CSS selectors.

docs/src/pages/components/Portal.svx

@@ -0,0 +1,30 @@
+<script>
+  import { Portal } from "carbon-components-svelte";
+  import Preview from "../../components/Preview.svelte";
+</script>
+
+The `Portal` component renders its content directly into `document.body`, allowing you to escape parent overflow constraints and z-index stacking contexts.
+
+## Default Portal
+
+Render content in a portal. This is useful for modals, tooltips, and menus that need to escape parent containers.
+
+<FileSource src="/framed/Portal/BasicPortal" />
+
+## Multiple Portals
+
+Each portal instance is independent and creates its own element in `document.body`. Each portal is automatically cleaned up when it is removed.
+
+<FileSource src="/framed/Portal/MultiplePortals" />
+
+## Custom Tag
+
+Use the `tag` prop to specify a custom HTML element. By default, Portal uses a `div` element.
+
+<FileSource src="/framed/Portal/CustomTagPortal" />
+
+## Modal with Portal
+
+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" />

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

@@ -0,0 +1,9 @@
+<script>
+  import { Portal } from "carbon-components-svelte";
+</script>
+
+<div>
+  <div>This is rendered inside the div</div>
+  <br />
+  <Portal>This is rendered outside of the div</Portal>
+</div>

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

@@ -0,0 +1,39 @@
+<script>
+  import {
+    Button,
+    ComposedModal,
+    ModalBody,
+    ModalFooter,
+    ModalHeader,
+    Portal,
+    Stack,
+  } from "carbon-components-svelte";
+
+  let open = false;
+</script>
+
+<Stack gap={5} style="overflow: hidden; position: relative; height: 200px;">
+  <p>
+    This container hides overflowing content. Without a portal, the modal would
+    be clipped.
+  </p>
+  <div>
+    <Button on:click={() => (open = true)}>Open modal</Button>
+  </div>
+  <Portal>
+    <ComposedModal bind:open>
+      <ModalHeader title="Composed Modal in Portal" />
+      <ModalBody>
+        <p>
+          This composed modal is rendered in a portal, ensuring it appears above
+          all z-index stacking contexts and parent overflow constraints.
+        </p>
+      </ModalBody>
+      <ModalFooter
+        primaryButtonText="Confirm"
+        secondaryButtonText="Cancel"
+        on:click:button--secondary={() => (open = false)}
+      />
+    </ComposedModal>
+  </Portal>
+</Stack>

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

@@ -0,0 +1,7 @@
+<script>
+  import { Portal } from "carbon-components-svelte";
+</script>
+
+<Portal tag="section">
+  This portal uses a section tag.
+</Portal>

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

@@ -0,0 +1,29 @@
+<script>
+  import { Button, Modal, Portal, Stack } from "carbon-components-svelte";
+
+  let open = false;
+</script>
+
+<Stack gap={5} style="overflow: hidden; position: relative; height: 200px;">
+  <p>
+    This container hides overflowing content. Without a portal, the modal would
+    be clipped.
+  </p>
+  <div>
+    <Button on:click={() => (open = true)}>Open modal</Button>
+  </div>
+  <Portal>
+    <Modal
+      bind:open
+      modalHeading="Modal in Portal"
+      primaryButtonText="Confirm"
+      secondaryButtonText="Cancel"
+      on:click:button--secondary={() => (open = false)}
+    >
+      <p>
+        This modal is rendered in a portal, escaping the parent container's
+        overflow constraints and ensuring it appears above all other content.
+      </p>
+    </Modal>
+  </Portal>
+</Stack>

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

@@ -0,0 +1,27 @@
+<script>
+  import { Button, ButtonSet, Portal } from "carbon-components-svelte";
+
+  let showPortal1 = false;
+  let showPortal2 = false;
+</script>
+
+<ButtonSet>
+  <Button on:click={() => (showPortal1 = !showPortal1)}>
+    {showPortal1 ? "Unmount portal 1" : "Mount portal 1"}
+  </Button>
+  <Button on:click={() => (showPortal2 = !showPortal2)}>
+    {showPortal2 ? "Unmount portal 2" : "Mount portal 2"}
+  </Button>
+</ButtonSet>
+
+{#if showPortal1}
+  <Portal>
+    Portal content 1
+  </Portal>
+{/if}
+
+{#if showPortal2}
+  <Portal>
+    Portal content 2
+  </Portal>
+{/if}