wabtec-internal-volt-basic-components 1.2.0 → 1.4.0

package/dist/collection/components/drawer/vds-drawer.js

@@ -1,25 +1,386 @@
 import { Host, h } from "@stencil/core";
 import { combineClasses } from "../../utils/combine-classes";
+/**
+ * @component vds-drawer
+ *
+ * @description
+ * A panel that slides in from the left or right edge of the screen (or of a parent container when
+ * `is-adaptable` is set). It supports two layout modes, an optional backdrop overlay, a built-in
+ * close button, and full theming via CSS custom properties.
+ *
+ * Use `vds-drawer` as a navigation sidebar, a filter panel, a details panel, or any off-canvas UI
+ * that must coexist with the main page content.
+ *
+ * ---
+ *
+ * ## Slots
+ *
+ * | Slot        | Description                                                                      |
+ * |-------------|----------------------------------------------------------------------------------|
+ * | `header`    | Content rendered at the top of the drawer panel (e.g. logo, app name, search).  |
+ * | `drawer`    | Main scrollable body of the drawer panel.                                        |
+ * | `footer`    | Content pinned to the bottom of the drawer panel (e.g. user profile, settings). |
+ * | `container` | Content rendered **beside** the drawer — typically the main page body.           |
+ *
+ * ---
+ *
+ * ## CSS Custom Properties
+ *
+ * | Property                                  | Description                          |
+ * |-------------------------------------------|--------------------------------------|
+ * | `--vds-drawer-background-color`           | Background color of the drawer panel |
+ * | `--vds-drawer-border-color`               | Border color when `show-border=true` |
+ * | `--vds-drawer-backdrop-background-color`  | Color of the backdrop overlay        |
+ *
+ * ---
+ *
+ * ## Examples
+ *
+ * ### Basic usage — side mode, left position
+ * The drawer sits beside the page content and does not overlap it.
+ * ```html
+ * <vds-drawer
+ *   opened="false"
+ *   mode="side"
+ *   position="left"
+ *   show-close-button="true"
+ *   padding="spacing-06"
+ *   show-shadow="true"
+ * >
+ *   <div slot="drawer">
+ *     <p>Navigation links go here</p>
+ *   </div>
+ *   <div slot="container">
+ *     <p>Main page content goes here</p>
+ *     <vds-button onclick="document.querySelector('vds-drawer').opened = !document.querySelector('vds-drawer').opened">
+ *       Toggle Drawer
+ *     </vds-button>
+ *   </div>
+ * </vds-drawer>
+ * ```
+ *
+ * ### Over mode with backdrop — drawer floats on top of page content
+ * ```html
+ * <vds-drawer
+ *   opened="false"
+ *   mode="over"
+ *   position="left"
+ *   backdrop="true"
+ *   show-close-button="true"
+ *   padding="spacing-05"
+ * >
+ *   <div slot="drawer">
+ *     <p>Drawer content overlays the page</p>
+ *   </div>
+ *   <div slot="container">
+ *     <p>Page content remains visible behind the backdrop</p>
+ *     <vds-button onclick="document.querySelector('vds-drawer').opened = true">
+ *       Open Drawer
+ *     </vds-button>
+ *   </div>
+ * </vds-drawer>
+ * ```
+ *
+ * ### Right-side drawer
+ * ```html
+ * <vds-drawer
+ *   opened="false"
+ *   mode="side"
+ *   position="right"
+ *   show-close-button="true"
+ *   padding="spacing-06"
+ * >
+ *   <div slot="drawer">
+ *     <p>Details panel content</p>
+ *   </div>
+ *   <div slot="container">
+ *     <p>Main content area</p>
+ *     <vds-button onclick="document.querySelector('vds-drawer').opened = true">
+ *       Open Details
+ *     </vds-button>
+ *   </div>
+ * </vds-drawer>
+ * ```
+ *
+ * ### Using all four slots — full sidenav pattern
+ * Combine `header`, `drawer`, `footer`, and `container` to build a complete navigation sidebar.
+ * ```html
+ * <vds-drawer
+ *   opened="true"
+ *   mode="side"
+ *   position="left"
+ *   show-close-button="false"
+ *   padding="spacing-00"
+ *   show-shadow="true"
+ * >
+ *   <!-- App branding / logo area -->
+ *   <div slot="header">
+ *     <vds-sidenav-item-app
+ *       value="My App"
+ *       menu-icon="false"
+ *       expanded="true"
+ *       is-active="false"
+ *     >
+ *       <vds-icon slot="img" size="2.5rem" svg-icon="wabtec-icon"></vds-icon>
+ *     </vds-sidenav-item-app>
+ *   </div>
+ *
+ *   <!-- Scrollable nav items -->
+ *   <div slot="drawer">
+ *     <vds-sidenav-item-input
+ *       expanded="true"
+ *       placeholder="Search"
+ *       action-icon="zoom"
+ *     ></vds-sidenav-item-input>
+ *     <vds-sidenav-item
+ *       value="Dashboard"
+ *       icon="desktop-computer"
+ *       expanded="true"
+ *       is-active="true"
+ *     ></vds-sidenav-item>
+ *     <vds-sidenav-item
+ *       value="Reports"
+ *       icon="chart-bar"
+ *       expanded="true"
+ *     ></vds-sidenav-item>
+ *   </div>
+ *
+ *   <!-- User profile / settings area -->
+ *   <div slot="footer">
+ *     <vds-sidenav-item-app
+ *       value="John Doe"
+ *       menu-icon="true"
+ *       expanded="true"
+ *       is-active="false"
+ *     >
+ *       <vds-icon slot="img" size="2.5rem" svg-icon="user-circle"></vds-icon>
+ *     </vds-sidenav-item-app>
+ *   </div>
+ *
+ *   <!-- Main page body -->
+ *   <div slot="container">
+ *     <p>Page content renders here, next to the sidebar.</p>
+ *   </div>
+ * </vds-drawer>
+ * ```
+ *
+ * ### Programmatic control via `open()` and `close()` methods
+ * Use the public methods when you need to control the drawer from JavaScript.
+ * ```html
+ * <vds-drawer id="myDrawer" mode="over" position="left" show-close-button="true">
+ *   <div slot="drawer">
+ *     <p>Drawer body content</p>
+ *   </div>
+ *   <div slot="container">
+ *     <vds-button id="openBtn">Open</vds-button>
+ *     <vds-button id="closeBtn" variant="secondary">Close</vds-button>
+ *   </div>
+ * </vds-drawer>
+ *
+ * <script>
+ *   const drawer = document.getElementById('myDrawer');
+ *   document.getElementById('openBtn').addEventListener('click', () => drawer.open());
+ *   document.getElementById('closeBtn').addEventListener('click', () => drawer.close());
+ * </script>
+ * ```
+ *
+ * ### Listening to `drawerOpened` and `drawerClosed` events
+ * ```html
+ * <vds-drawer id="evtDrawer" mode="side" position="left" show-close-button="true" padding="spacing-05">
+ *   <div slot="drawer"><p>Drawer content</p></div>
+ *   <div slot="container">
+ *     <vds-button onclick="document.getElementById('evtDrawer').open()">Open</vds-button>
+ *   </div>
+ * </vds-drawer>
+ *
+ * <script>
+ *   const drawer = document.getElementById('evtDrawer');
+ *   drawer.addEventListener('drawerOpened', () => console.log('Drawer opened'));
+ *   drawer.addEventListener('drawerClosed', () => console.log('Drawer closed'));
+ * </script>
+ * ```
+ *
+ * ### Locked drawer — `disable-close` prevents the user from dismissing it
+ * Useful for forced onboarding flows or confirmation steps.
+ * ```html
+ * <vds-drawer
+ *   opened="true"
+ *   mode="over"
+ *   position="right"
+ *   show-close-button="true"
+ *   disable-close="true"
+ *   backdrop="true"
+ *   padding="spacing-06"
+ * >
+ *   <div slot="drawer">
+ *     <p>Complete this form before continuing.</p>
+ *     <!-- Unlock programmatically once the form is valid -->
+ *     <vds-button onclick="unlockAndClose()">Submit &amp; Close</vds-button>
+ *   </div>
+ *   <div slot="container">
+ *     <p>Background content is blocked until the drawer is dismissed.</p>
+ *   </div>
+ * </vds-drawer>
+ *
+ * <script>
+ *   function unlockAndClose() {
+ *     const drawer = document.querySelector('vds-drawer');
+ *     drawer.disableClose = false;
+ *     drawer.close();
+ *   }
+ * </script>
+ * ```
+ *
+ * ### Adaptable mode — drawer contained inside a parent element
+ * Set `is-adaptable="true"` when the drawer must be scoped to a specific container rather than
+ * the full viewport. The parent element must have `position: relative` and an explicit height.
+ * ```html
+ * <style>
+ *   .bounded-container { position: relative; width: 400px; height: 300px; overflow: hidden; }
+ * </style>
+ *
+ * <div class="bounded-container">
+ *   <vds-drawer
+ *     opened="false"
+ *     mode="side"
+ *     position="left"
+ *     is-adaptable="true"
+ *     show-close-button="true"
+ *     padding="spacing-04"
+ *   >
+ *     <div slot="drawer"><p>Scoped panel</p></div>
+ *     <div slot="container">
+ *       <p>Content inside the bounded container</p>
+ *       <vds-button onclick="document.querySelector('vds-drawer').opened = true">Open</vds-button>
+ *     </div>
+ *   </vds-drawer>
+ * </div>
+ * ```
+ *
+ * ### Custom theming via CSS custom properties
+ * Override the drawer's color tokens to match a specific brand or context.
+ * ```html
+ * <style>
+ *   #themedDrawer {
+ *     --vds-drawer-background-color: var(--color-background-information-default);
+ *     --vds-drawer-border-color: var(--color-border-danger);
+ *     --vds-drawer-backdrop-background-color: var(--color-background-healthy-lowest-hover);
+ *   }
+ * </style>
+ *
+ * <vds-drawer
+ *   id="themedDrawer"
+ *   opened="false"
+ *   mode="over"
+ *   position="left"
+ *   backdrop="true"
+ *   show-border="true"
+ *   show-close-button="true"
+ *   padding="spacing-06"
+ * >
+ *   <div slot="drawer"><p>Custom-colored drawer</p></div>
+ *   <div slot="container">
+ *     <vds-button onclick="document.getElementById('themedDrawer').opened = true">Open Themed Drawer</vds-button>
+ *   </div>
+ * </vds-drawer>
+ * ```
+ *
+ * @slot header    - Content rendered at the top of the drawer panel (e.g. app logo, title, search input)
+ * @slot drawer    - Main scrollable body of the drawer panel (e.g. nav items, form fields, content list)
+ * @slot footer    - Content pinned to the bottom of the drawer panel (e.g. user profile, logout button)
+ * @slot container - Content rendered beside (or behind in `over` mode) the drawer — typically the main page body
+ */
 export class VdsDrawer {
     constructor() {
-        /** Places the drawer in the screen */
+        /**
+         * Determines which edge of the screen (or adaptable container) the drawer slides in from.
+         * - `"left"` — drawer animates in from the left (default; typical for sidebars)
+         * - `"right"` — drawer animates in from the right (typical for detail / filter panels)
+         * @type {"left" | "right"}
+         * @default "left"
+         * @example <vds-drawer position="right"></vds-drawer>
+         */
         this.position = 'left';
-        /** Mode of the drawer; one of 'over' or 'side'. */
+        /**
+         * Controls how the drawer interacts with the page layout:
+         * - `"side"` — the drawer sits alongside the container content; the container content is pushed
+         *   horizontally to make room for the open drawer.
+         * - `"over"` — the drawer floats on top of the container content; the layout underneath does
+         *   not reflow. Combine with `backdrop="true"` for best visual results.
+         * @type {"over" | "side"}
+         * @default "over"
+         * @example <vds-drawer mode="side"></vds-drawer>
+         * @example <vds-drawer mode="over" backdrop="true"></vds-drawer>
+         */
         this.mode = 'over';
-        /** Allow the vds-drawer to fit inside another html element */
+        /**
+         * When `true`, the drawer is scoped to its nearest positioned ancestor instead of the viewport.
+         * The parent element **must** have `position: relative` and an explicit height/width for the
+         * drawer to render correctly within it.
+         * @type {boolean}
+         * @default false
+         * @example
+         * <!-- Parent must be relatively positioned -->
+         * <div style="position: relative; width: 400px; height: 300px; overflow: hidden;">
+         *   <vds-drawer is-adaptable="true" mode="side" position="left" opened="false">
+         *     <div slot="drawer"><p>Scoped drawer</p></div>
+         *     <div slot="container"><p>Container content</p></div>
+         *   </vds-drawer>
+         * </div>
+         */
         this.isAdaptable = false;
-        /** Allow show or hide the shadow of the drawer */
+        /**
+         * When `true` (default), the drawer panel casts a directional box-shadow to create depth.
+         * Set to `false` to remove the shadow — useful when `show-border` is already providing
+         * visual separation, or when using a flat design aesthetic.
+         * @type {boolean}
+         * @default true
+         * @example <vds-drawer show-shadow="false"></vds-drawer>
+         */
         this.showShadow = true;
-        // Allow display the border of the sidenav
+        /**
+         * When `true`, displays a border on the edge of the drawer that faces the content area.
+         * The border color is controlled by the `--vds-drawer-border-color` CSS custom property.
+         * Can be combined with `show-shadow="false"` for a clean, flat separator.
+         * @type {boolean}
+         * @default false
+         * @example <vds-drawer show-border="true" show-shadow="false"></vds-drawer>
+         * @example
+         * <!-- Override border color via CSS custom property -->
+         * <style>
+         *   vds-drawer { --vds-drawer-border-color: var(--color-border-danger); }
+         * </style>
+         * <vds-drawer show-border="true"></vds-drawer>
+         */
         this.showBorder = false;
+        /**
+         * When `true`, only renders the drawer slotted content — the container slot is ignored and backdrop (if enabled).
+         * @type {boolean}
+         * @default false
+         * @example <vds-drawer drawer-only="true"></vds-drawer>
+         */
+        this.drawerOnly = false;
+        /**
+         * Internal state tracking whether a dropdown inside the drawer is opened
+         * @type {boolean}
+         */
         this.dropdownIsOpened = false;
     }
+    /**
+     * Emits the appropriate event when opened state changes
+     * @returns {void}
+     */
     emitValue() {
         if (this.opened)
             this.drawerOpened.emit();
         else
             this.drawerClosed.emit();
     }
+    /**
+     * Listens for opened/closed events from dropdown components to adjust drawer positioning
+     * @param {CustomEvent<boolean>} evt - The custom event from dropdown components
+     * @returns {void}
+     */
     setPositionRelativeForDropdowns(evt) {
         const target = (evt.target);
         if (target.nodeName === "VDS-BASIC-DROPDOWN" ||
@@ -31,12 +392,48 @@ export class VdsDrawer {
             this.dropdownIsOpened = evt.type === "opened";
         }
     }
+    /**
+     * Programmatically opens the drawer by setting `opened` to `true`.
+     * This is equivalent to setting `drawer.opened = true` but returns a Promise, making it
+     * easier to chain with `await` in async flows.
+     * Emits the `drawerOpened` event after the state change.
+     * @method
+     * @public
+     * @returns {Promise<void>} Resolves once the opened state has been set.
+     * @example
+     * const drawer = document.querySelector('vds-drawer');
+     * await drawer.open();
+     * console.log('Drawer is now open');
+     * @example
+     * // Open on button click
+     * document.getElementById('openBtn').addEventListener('click', () => {
+     *   document.querySelector('vds-drawer').open();
+     * });
+     */
     open() {
         return new Promise(resolve => {
             this.opened = true;
             resolve();
         });
     }
+    /**
+     * Programmatically closes the drawer by setting `opened` to `false`.
+     * The call is silently ignored when `disable-close` is `true` — the drawer remains open.
+     * To force-close a locked drawer, set `disableClose = false` first, then call `close()`.
+     * Emits the `drawerClosed` event after the state change (only when the close is not blocked).
+     * @method
+     * @public
+     * @returns {Promise<void>} Resolves once the closed state has been set (or the call was blocked).
+     * @example
+     * const drawer = document.querySelector('vds-drawer');
+     * await drawer.close();
+     * console.log('Drawer is now closed');
+     * @example
+     * // Force-close a locked drawer
+     * const drawer = document.querySelector('vds-drawer');
+     * drawer.disableClose = false;
+     * await drawer.close();
+     */
     close() {
         return new Promise(resolve => {
             if (!this.disableClose) {
@@ -45,16 +442,30 @@ export class VdsDrawer {
             resolve();
         });
     }
+    /**
+     * Renders the backdrop element based on adaptable mode
+     * @private
+     * @returns {HTMLStencilElement} The rendered backdrop element
+     */
     renderBackdrop() {
         return this.isAdaptable ? h("div", { class: `volt__drawer--backdrop-adaptable` }) : h("div", { class: `volt__drawer--backdrop` });
     }
+    /**
+     * Renders the close icon button
+     * @private
+     * @returns {HTMLStencilElement} The rendered close button element
+     */
     renderCloseIcon() {
         return (h("vds-icon-button", { onClick: () => {
                 this.close();
             }, variant: 'secondary', icon: "close", disabled: this.disableClose, size: "large" }));
     }
+    /**
+     * Renders the drawer component
+     * @returns {HTMLStencilElement} The rendered drawer element
+     */
     render() {
-        return (h(Host, { key: '04a0ae5396f135a3f705da5b2bc95b4526746c83', class: combineClasses(`vds-drawer__${this.mode}`, `vds-drawer__${this.position}`, this.isAdaptable ? 'vds-drawer--adaptable' : '') }, h("div", { key: '2277cf42ad559236e3465fa677e620328a81f4b0', class: combineClasses('volt__drawer', `padding__${this.padding}`, this.opened ? 'volt__drawer--opened' : '', `volt__drawer__element--position-${this.position}`, this.showShadow ? `vds-drawer__shadow--${this.position}` : '', this.showBorder ? `vds-drawer__border--${this.position}` : '', this.dropdownIsOpened ? "vds-drawer__dropdown-is-opened" : "") }, h("div", { key: '426287a215506b507f63dadd08af2821754ea21f', class: `volt__drawer--content` }, h("div", { key: 'ae7358588fa5443c0980a42fc9ee041aa1ae07ff', class: `volt__drawer--header ${this.showCloseButton ? "volt__drawer--header-close-icon" : ""}` }, h("div", { key: '62dc06dae100c113442c5f8e8fed39baca68c0a4', class: "volt__drawer--header-content" }, h("slot", { key: '9980201d3707f32fafad442041bad3aa89688cec', name: "header" })), this.showCloseButton && this.renderCloseIcon()), h("div", { key: '61dbabf20c2b6cc8f1b5377498ab37436cf0f1cc', class: `volt-drawer__body` }, h("slot", { key: '70e974cf002905462fa5e38877d821cf4167a7d4', name: "drawer" })), h("slot", { key: '65484691baee2f614e4d47e1b3becbbc77f26152', name: "footer" }))), h("div", { key: 'f3ea19cec4e4570e3d4bb3f850b86253537765aa', class: 'volt__drawer__container' }, this.backdrop && this.opened ? this.renderBackdrop() : '', h("slot", { key: '0569939d8ca916c80d9a7c77e9351990b6ec2eab', name: "container" }))));
+        return (h(Host, { key: 'c40ef8399325b46dfa1cc6068a39a3f32d3adc32', class: combineClasses(`vds-drawer__${this.mode}`, `vds-drawer__${this.position}`, this.isAdaptable ? 'vds-drawer--adaptable' : '') }, h("div", { key: '2055bc388a19eef5ddbd82dcd7eb8932a1a297b2', class: combineClasses('volt__drawer', `padding__${this.padding}`, this.opened ? 'volt__drawer--opened' : '', `volt__drawer__element--position-${this.position}`, this.showShadow ? `vds-drawer__shadow--${this.position}` : '', this.showBorder ? `vds-drawer__border--${this.position}` : '', this.dropdownIsOpened ? "vds-drawer__dropdown-is-opened" : "") }, h("div", { key: 'a16a35688db8708a40d3cddcb2b2f8e18d370fdd', class: `volt__drawer--content` }, h("div", { key: '5c1c053344852c9216ca05f0cceebff9a76dcf2d', class: `volt__drawer--header ${this.showCloseButton ? "volt__drawer--header-close-icon" : ""}` }, h("div", { key: '68e5755160b752605a305166d4a18506e738474b', class: "volt__drawer--header-content" }, h("slot", { key: '2178dca3dbb1eaa17b39b0878e1854c49f8dd908', name: "header" })), this.showCloseButton && this.renderCloseIcon()), h("div", { key: 'e4be5606f156406eb1b5e07f56abc70f38072727', class: `volt-drawer__body` }, h("slot", { key: 'dc7ab65e278f8523959b066d74f30f0ff439cb8e', name: "drawer" })), h("slot", { key: '16a804246034494537a9953a1b48965e5cf0cab1', name: "footer" }))), !this.drawerOnly && (h("div", { key: '99b7dac492127bef16654b5f4716c5fdd9b6795f', class: 'volt__drawer__container' }, this.backdrop && this.opened ? this.renderBackdrop() : '', h("slot", { key: '802adb9dd3d9edbc0e8112f88905907d44fe5436', name: "container" })))));
     }
     static get is() { return "vds-drawer"; }
     static get encapsulation() { return "shadow"; }
@@ -81,8 +492,20 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Opens/closes the drawer"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer opened=\"true\"></vds-drawer>"
+                        }, {
+                            "name": "example",
+                            "text": "// Toggle from JavaScript\nconst drawer = document.querySelector('vds-drawer');\ndrawer.opened = !drawer.opened;"
+                        }],
+                    "text": "Controls whether the drawer panel is visible.\nCan be toggled declaratively via the attribute or programmatically via the `open()` / `close()` methods.\nWhen the value changes, the `drawerOpened` or `drawerClosed` event is emitted accordingly."
                 },
                 "getter": false,
                 "setter": false,
@@ -100,8 +523,17 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Toggles close button in the drawer"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer show-close-button=\"true\"></vds-drawer>"
+                        }],
+                    "text": "When `true`, renders an `\u00D7` icon button in the top-right corner of the drawer header.\nClicking it calls `close()` internally. The button is disabled while `disable-close` is `true`."
                 },
                 "getter": false,
                 "setter": false,
@@ -119,8 +551,20 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Disables the close button in the drawer"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer opened=\"true\" show-close-button=\"true\" disable-close=\"true\"></vds-drawer>"
+                        }, {
+                            "name": "example",
+                            "text": "// Unlock and close programmatically\nconst drawer = document.querySelector('vds-drawer');\ndrawer.disableClose = false;\ndrawer.close();"
+                        }],
+                    "text": "When `true`, prevents the user from closing the drawer \u2014 both the built-in close button\nand programmatic calls to `close()` are ignored. Use this to lock the drawer open during\nmandatory flows (e.g. onboarding, unsaved-changes warnings).\nUnlock by setting `disableClose = false` before calling `close()`."
                 },
                 "getter": false,
                 "setter": false,
@@ -138,8 +582,17 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Places the drawer in the screen"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"left\" | \"right\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"left\""
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer position=\"right\"></vds-drawer>"
+                        }],
+                    "text": "Determines which edge of the screen (or adaptable container) the drawer slides in from.\n- `\"left\"` \u2014 drawer animates in from the left (default; typical for sidebars)\n- `\"right\"` \u2014 drawer animates in from the right (typical for detail / filter panels)"
                 },
                 "getter": false,
                 "setter": false,
@@ -158,8 +611,17 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Toggles backdrop behind the drawer in the screen"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer mode=\"over\" backdrop=\"true\"></vds-drawer>"
+                        }],
+                    "text": "When `true`, renders a semi-transparent backdrop overlay behind the drawer panel.\nRecommended when using `mode=\"over\"` to visually separate the drawer from page content.\nThe backdrop color can be customized via the `--vds-drawer-backdrop-background-color` CSS custom property."
                 },
                 "getter": false,
                 "setter": false,
@@ -171,20 +633,30 @@ export class VdsDrawer {
                 "mutable": true,
                 "complexType": {
                     "original": "Spacing",
-                    "resolved": "\"spacing-00\" | \"spacing-01\" | \"spacing-02\" | \"spacing-03\" | \"spacing-04\" | \"spacing-05\" | \"spacing-06\" | \"spacing-07\" | \"spacing-08\" | \"spacing-09\" | \"spacing-10\" | \"spacing-11\" | \"spacing-12\" | \"spacing-13\" | \"spacing-14\" | \"spacing-15\" | \"spacing-16\" | \"spacing-17\" | \"spacing-18\" | \"spacing-19\" | \"spacing-20\"",
+                    "resolved": "\"spacing-00\" | \"spacing-01\" | \"spacing-02\" | \"spacing-03\" | \"spacing-04\" | \"spacing-05\" | \"spacing-06\" | \"spacing-07\" | \"spacing-08\" | \"spacing-09\" | \"spacing-10\" | \"spacing-11\" | \"spacing-12\" | \"spacing-13\" | \"spacing-14\" | \"spacing-15\" | \"spacing-16\" | \"spacing-17\" | \"spacing-18\" | \"spacing-19\" | \"spacing-20\" | \"spacing-21\"",
                     "references": {
                         "Spacing": {
                             "location": "import",
                             "path": "../../definitions/spacing",
-                            "id": "src/definitions/spacing.ts::Spacing"
+                            "id": "src/definitions/spacing.ts::Spacing",
+                            "referenceLocation": "Spacing"
                         }
                     }
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Adds the padding to the drawer"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{Spacing}"
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer padding=\"spacing-06\"></vds-drawer>"
+                        }],
+                    "text": "Applies internal padding to the drawer panel body using a design-token spacing value.\nAccepted values follow the Volt spacing scale: `\"spacing-00\"` through `\"spacing-21\"`."
                 },
                 "getter": false,
                 "setter": false,
@@ -202,8 +674,20 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Mode of the drawer; one of 'over' or 'side'."
+                    "tags": [{
+                            "name": "type",
+                            "text": "{\"over\" | \"side\"}"
+                        }, {
+                            "name": "default",
+                            "text": "\"over\""
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer mode=\"side\"></vds-drawer>"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer mode=\"over\" backdrop=\"true\"></vds-drawer>"
+                        }],
+                    "text": "Controls how the drawer interacts with the page layout:\n- `\"side\"` \u2014 the drawer sits alongside the container content; the container content is pushed\n  horizontally to make room for the open drawer.\n- `\"over\"` \u2014 the drawer floats on top of the container content; the layout underneath does\n  not reflow. Combine with `backdrop=\"true\"` for best visual results."
                 },
                 "getter": false,
                 "setter": false,
@@ -222,8 +706,17 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Allow the vds-drawer to fit inside another html element"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<!-- Parent must be relatively positioned -->\n<div style=\"position: relative; width: 400px; height: 300px; overflow: hidden;\">\n  <vds-drawer is-adaptable=\"true\" mode=\"side\" position=\"left\" opened=\"false\">\n    <div slot=\"drawer\"><p>Scoped drawer</p></div>\n    <div slot=\"container\"><p>Container content</p></div>\n  </vds-drawer>\n</div>"
+                        }],
+                    "text": "When `true`, the drawer is scoped to its nearest positioned ancestor instead of the viewport.\nThe parent element **must** have `position: relative` and an explicit height/width for the\ndrawer to render correctly within it."
                 },
                 "getter": false,
                 "setter": false,
@@ -242,8 +735,17 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Allow show or hide the shadow of the drawer"
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer show-shadow=\"false\"></vds-drawer>"
+                        }],
+                    "text": "When `true` (default), the drawer panel casts a directional box-shadow to create depth.\nSet to `false` to remove the shadow \u2014 useful when `show-border` is already providing\nvisual separation, or when using a flat design aesthetic."
                 },
                 "getter": false,
                 "setter": false,
@@ -262,14 +764,55 @@ export class VdsDrawer {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": ""
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer show-border=\"true\" show-shadow=\"false\"></vds-drawer>"
+                        }, {
+                            "name": "example",
+                            "text": "<!-- Override border color via CSS custom property -->\n<style>\n  vds-drawer { --vds-drawer-border-color: var(--color-border-danger); }\n</style>\n<vds-drawer show-border=\"true\"></vds-drawer>"
+                        }],
+                    "text": "When `true`, displays a border on the edge of the drawer that faces the content area.\nThe border color is controlled by the `--vds-drawer-border-color` CSS custom property.\nCan be combined with `show-shadow=\"false\"` for a clean, flat separator."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "show-border",
                 "defaultValue": "false"
+            },
+            "drawerOnly": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "type",
+                            "text": "{boolean}"
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }, {
+                            "name": "example",
+                            "text": "<vds-drawer drawer-only=\"true\"></vds-drawer>"
+                        }],
+                    "text": "When `true`, only renders the drawer slotted content \u2014 the container slot is ignored and backdrop (if enabled)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "drawer-only",
+                "defaultValue": "false"
             }
         };
     }
@@ -286,8 +829,17 @@ export class VdsDrawer {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when drawer is closed"
+                    "tags": [{
+                            "name": "event",
+                            "text": "drawerClosed"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }, {
+                            "name": "example",
+                            "text": "const drawer = document.querySelector('vds-drawer');\ndrawer.addEventListener('drawerClosed', () => {\n  console.log('Drawer was closed \u2014 restore focus or update state here');\n});"
+                        }],
+                    "text": "Fired every time the drawer transitions from open to closed \u2014 i.e. when `opened` changes to\n`false` (whether by user interaction, the built-in close button, or a call to `close()`).\nListen to this event to run cleanup logic, update application state, or restore focus."
                 },
                 "complexType": {
                     "original": "void",
@@ -301,8 +853,17 @@ export class VdsDrawer {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emits event when drawer is opened"
+                    "tags": [{
+                            "name": "event",
+                            "text": "drawerOpened"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<void>}"
+                        }, {
+                            "name": "example",
+                            "text": "const drawer = document.querySelector('vds-drawer');\ndrawer.addEventListener('drawerOpened', () => {\n  console.log('Drawer opened \u2014 fetch or render deferred content here');\n});"
+                        }],
+                    "text": "Fired every time the drawer transitions from closed to open \u2014 i.e. when `opened` changes to\n`true` (whether set declaratively on the attribute or via `open()`).\nListen to this event to load deferred content, trigger animations, or log analytics."
                 },
                 "complexType": {
                     "original": "void",
@@ -326,8 +887,23 @@ export class VdsDrawer {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Programmatically opens the drawer by setting `opened` to `true`.\nThis is equivalent to setting `drawer.opened = true` but returns a Promise, making it\neasier to chain with `await` in async flows.\nEmits the `drawerOpened` event after the state change.",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "Resolves once the opened state has been set."
+                        }, {
+                            "name": "example",
+                            "text": "const drawer = document.querySelector('vds-drawer');\nawait drawer.open();\nconsole.log('Drawer is now open');"
+                        }, {
+                            "name": "example",
+                            "text": "// Open on button click\ndocument.getElementById('openBtn').addEventListener('click', () => {\n  document.querySelector('vds-drawer').open();\n});"
+                        }]
                 }
             },
             "close": {
@@ -343,8 +919,23 @@ export class VdsDrawer {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
-                    "tags": []
+                    "text": "Programmatically closes the drawer by setting `opened` to `false`.\nThe call is silently ignored when `disable-close` is `true` \u2014 the drawer remains open.\nTo force-close a locked drawer, set `disableClose = false` first, then call `close()`.\nEmits the `drawerClosed` event after the state change (only when the close is not blocked).",
+                    "tags": [{
+                            "name": "method",
+                            "text": undefined
+                        }, {
+                            "name": "public",
+                            "text": undefined
+                        }, {
+                            "name": "returns",
+                            "text": "Resolves once the closed state has been set (or the call was blocked)."
+                        }, {
+                            "name": "example",
+                            "text": "const drawer = document.querySelector('vds-drawer');\nawait drawer.close();\nconsole.log('Drawer is now closed');"
+                        }, {
+                            "name": "example",
+                            "text": "// Force-close a locked drawer\nconst drawer = document.querySelector('vds-drawer');\ndrawer.disableClose = false;\nawait drawer.close();"
+                        }]
                 }
             }
         };
@@ -371,4 +962,3 @@ export class VdsDrawer {
             }];
     }
 }
-//# sourceMappingURL=vds-drawer.js.map