docs(composed-modal): add "Prevent default close behavior" example

Author: metonym

docs/src/pages/components/ComposedModal.svx

@@ -14,6 +14,12 @@ Create a modal with a header, body, and footer. Each section can be customized i
 
 <FileSource src="/framed/Modal/ComposedModal" />
 
+## 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"`.
+
+<FileSource src="/framed/Modal/ComposedModalPreventClose" />
+
 ## Multiple secondary buttons
 
 Set `secondaryButtons` in `ModalFooter` to create a 3-button modal. This prop replaces `secondaryButtonText` and takes a tuple of two button configurations.

docs/src/pages/framed/Modal/ComposedModalPreventClose.svelte

@@ -0,0 +1,59 @@
+<script>
+  import {
+    Button,
+    ComposedModal,
+    ModalHeader,
+    ModalBody,
+    ModalFooter,
+    InlineNotification,
+  } from "carbon-components-svelte";
+
+  let open = false;
+  let hasUnsavedChanges = true;
+  let showWarning = false;
+</script>
+
+<Button
+  on:click={() => {
+    open = true;
+    hasUnsavedChanges = true;
+    showWarning = false;
+  }}>Open modal with unsaved changes</Button
+>
+
+<ComposedModal
+  bind:open
+  on:close={(e) => {
+    console.log("Close triggered by:", e.detail.trigger);
+    if (hasUnsavedChanges) {
+      e.preventDefault();
+      showWarning = true;
+    }
+  }}
+  on:submit={() => {
+    hasUnsavedChanges = false;
+    open = false;
+  }}
+>
+  <ModalHeader title="Edit profile" />
+  <ModalBody>
+    {#if showWarning}
+      <InlineNotification
+        kind="warning"
+        title="Unsaved changes"
+        subtitle="Please save or discard your changes before closing."
+        hideCloseButton
+      />
+    {/if}
+    <p>You have unsaved changes. Click "Save" to apply them.</p>
+  </ModalBody>
+  <ModalFooter
+    primaryButtonText="Save"
+    secondaryButtonText="Discard changes"
+    on:click:button--secondary={async () => {
+      hasUnsavedChanges = false;
+      showWarning = false;
+      open = false;
+    }}
+  />
+</ComposedModal>