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

package/dist/types/components/drawer/vds-drawer.d.ts

@@ -1,35 +1,512 @@
 import { HTMLStencilElement, EventEmitter } from '../../stencil-public-runtime';
 import { Spacing } from '../../definitions/spacing';
+/**
+ * @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 declare class VdsDrawer {
-    /** Opens/closes the drawer */
+    /**
+     * Controls whether the drawer panel is visible.
+     * Can be toggled declaratively via the attribute or programmatically via the `open()` / `close()` methods.
+     * When the value changes, the `drawerOpened` or `drawerClosed` event is emitted accordingly.
+     * @type {boolean}
+     * @default false
+     * @example <vds-drawer opened="true"></vds-drawer>
+     * @example
+     * // Toggle from JavaScript
+     * const drawer = document.querySelector('vds-drawer');
+     * drawer.opened = !drawer.opened;
+     */
     opened: boolean;
-    /** Toggles close button in the drawer */
+    /**
+     * When `true`, renders an `×` icon button in the top-right corner of the drawer header.
+     * Clicking it calls `close()` internally. The button is disabled while `disable-close` is `true`.
+     * @type {boolean}
+     * @default false
+     * @example <vds-drawer show-close-button="true"></vds-drawer>
+     */
     showCloseButton: boolean;
-    /** Disables the close button in the drawer */
+    /**
+     * When `true`, prevents the user from closing the drawer — both the built-in close button
+     * and programmatic calls to `close()` are ignored. Use this to lock the drawer open during
+     * mandatory flows (e.g. onboarding, unsaved-changes warnings).
+     * Unlock by setting `disableClose = false` before calling `close()`.
+     * @type {boolean}
+     * @default false
+     * @example <vds-drawer opened="true" show-close-button="true" disable-close="true"></vds-drawer>
+     * @example
+     * // Unlock and close programmatically
+     * const drawer = document.querySelector('vds-drawer');
+     * drawer.disableClose = false;
+     * drawer.close();
+     */
     disableClose: boolean;
-    /** 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>
+     */
     position: 'left' | 'right';
-    /** Toggles backdrop behind the drawer in the screen */
+    /**
+     * When `true`, renders a semi-transparent backdrop overlay behind the drawer panel.
+     * Recommended when using `mode="over"` to visually separate the drawer from page content.
+     * The backdrop color can be customized via the `--vds-drawer-backdrop-background-color` CSS custom property.
+     * @type {boolean}
+     * @default false
+     * @example <vds-drawer mode="over" backdrop="true"></vds-drawer>
+     */
     backdrop: boolean;
-    /** Adds the padding to the drawer */
+    /**
+     * Applies internal padding to the drawer panel body using a design-token spacing value.
+     * Accepted values follow the Volt spacing scale: `"spacing-00"` through `"spacing-21"`.
+     * @type {Spacing}
+     * @default undefined
+     * @example <vds-drawer padding="spacing-06"></vds-drawer>
+     */
     padding: Spacing;
-    /** 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>
+     */
     mode: 'over' | 'side';
-    /** 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>
+     */
     isAdaptable: boolean;
-    /** 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>
+     */
     showShadow: boolean;
+    /**
+     * 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>
+     */
     showBorder: boolean;
-    /** Emits event when drawer is closed */
+    /**
+     * 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>
+     */
+    drawerOnly: boolean;
+    /**
+     * Fired every time the drawer transitions from open to closed — i.e. when `opened` changes to
+     * `false` (whether by user interaction, the built-in close button, or a call to `close()`).
+     * Listen to this event to run cleanup logic, update application state, or restore focus.
+     * @event drawerClosed
+     * @type {EventEmitter<void>}
+     * @example
+     * const drawer = document.querySelector('vds-drawer');
+     * drawer.addEventListener('drawerClosed', () => {
+     *   console.log('Drawer was closed — restore focus or update state here');
+     * });
+     */
     drawerClosed: EventEmitter<void>;
-    /** Emits event when drawer is opened */
+    /**
+     * Fired every time the drawer transitions from closed to open — i.e. when `opened` changes to
+     * `true` (whether set declaratively on the attribute or via `open()`).
+     * Listen to this event to load deferred content, trigger animations, or log analytics.
+     * @event drawerOpened
+     * @type {EventEmitter<void>}
+     * @example
+     * const drawer = document.querySelector('vds-drawer');
+     * drawer.addEventListener('drawerOpened', () => {
+     *   console.log('Drawer opened — fetch or render deferred content here');
+     * });
+     */
     drawerOpened: EventEmitter<void>;
+    /**
+     * Internal state tracking whether a dropdown inside the drawer is opened
+     * @type {boolean}
+     */
     dropdownIsOpened: boolean;
+    /**
+     * Emits the appropriate event when opened state changes
+     * @returns {void}
+     */
     emitValue(): void;
+    /**
+     * 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: CustomEvent<boolean>): void;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * Renders the backdrop element based on adaptable mode
+     * @private
+     * @returns {HTMLStencilElement} The rendered backdrop element
+     */
     private renderBackdrop;
+    /**
+     * Renders the close icon button
+     * @private
+     * @returns {HTMLStencilElement} The rendered close button element
+     */
     private renderCloseIcon;
+    /**
+     * Renders the drawer component
+     * @returns {HTMLStencilElement} The rendered drawer element
+     */
     render(): HTMLStencilElement;
 }

package/dist/types/components/dropdown-group-header/vds-dropdown-group-header.d.ts

@@ -1,6 +1,19 @@
 import { GroupHeaderSize } from '../base-group-header/base-group-header';
+/**
+ * @component vds-dropdown-group-header
+ * @description A group header component for dropdown items that provides visual separation and categorization. Uses the base group header generator for consistent styling.
+ * @slot - The default slot for group header content
+ */
 export declare class VdsDropdownGroupHeader {
-    /** Size of the group header */
+    /**
+     * Size of the group header
+     * @type {GroupHeaderSize}
+     * @default "medium"
+     */
     size: GroupHeaderSize;
+    /**
+     * Renders the dropdown group header component
+     * @returns {JSX.Element} The rendered dropdown group header element
+     */
     render(): any;
 }

package/dist/types/components/dropdown-item/vds-basic-dropdown-item.stories.d.ts

@@ -40,3 +40,4 @@ export default _default;
 export declare const BasicUsage: any;
 export declare const BasicCheckboxUsage: any;
 export declare const LinkUsage: any;
+export declare const CustomContentUsage: any;