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

Author: metonym

docs/src/pages/components/Modal.svx

@@ -66,6 +66,12 @@ Use the large size for complex content by setting `size` to `"lg"`. This provide
 
 <FileSource src="/framed/Modal/ModalLarge" />
 
+## 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/ModalPreventClose" />
+
 ## Prevent close on outside click
 
 Disable closing the modal when clicking outside by setting `preventCloseOnClickOutside` to `true`. This is useful for transactional modals where explicit user action is required.

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

@@ -0,0 +1,47 @@
+<script>
+  import { Button, Modal, 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
+>
+
+<Modal
+  bind:open
+  modalHeading="Edit profile"
+  primaryButtonText="Save"
+  secondaryButtonText="Discard changes"
+  on:click:button--secondary={() => {
+    hasUnsavedChanges = false;
+    open = false;
+  }}
+  on:close={(e) => {
+    console.log("Close triggered by:", e.detail.trigger);
+    if (hasUnsavedChanges) {
+      e.preventDefault();
+      showWarning = true;
+    }
+  }}
+  on:submit={() => {
+    hasUnsavedChanges = false;
+    open = false;
+  }}
+>
+  {#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>
+</Modal>