First attempt at drawer

2026-01-12 20:19:13 +00:00 · 2020-06-24 06:54:58 -04:00
parent 8cc5d05da6
commit a071332026
7 changed files with 508 additions and 5 deletions
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -22,6 +22,7 @@
  - [Color Picker](/components/color-picker.md)
  - [Details](/components/details.md)
  - [Dialog](/components/dialog.md)
+  - [Drawer](/components/drawer.md)
  - [Dropdown](/components/dropdown.md)
  - [Icon](/components/icon.md)
  - [Input](/components/input.md)
--- a/docs/components/drawer.md
+++ b/docs/components/drawer.md
@@ -0,0 +1,83 @@
+# Drawer
+
+[component-header:sl-drawer]
+
+Drawers...
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+```html preview
+<sl-drawer label="Title" class="drawer-overview">
+
+  <div style="border: dashed 2px var(--sl-color-gray-90); height: calc(100% - 4px);"></div>
+  
+  <sl-button slot="footer" type="primary">Apply Changes</sl-button>
+  <sl-button slot="footer" type="default">Cancel</sl-button>
+</sl-drawer>
+
+<sl-button>Open Drawer</sl-button>
+
+<script>
+  (() => {
+    const drawer = document.querySelector('.drawer-overview');
+    const openButton = drawer.nextElementSibling;
+
+    const cancelButton = drawer.querySelector('sl-button[type="default"]');
+    const applyButton = drawer.querySelector('sl-button[type="primary"]');
+
+    openButton.addEventListener('click', () => drawer.show());
+    cancelButton.addEventListener('click', () => drawer.hide());
+    applyButton.addEventListener('click', () => drawer.hide());
+  })();
+</script>
+```
+
+[component-metadata:sl-drawer]
+
+## Examples
+
+### Absolute
+
+To make the drawer slide out of a parent container, set `position: relative` and `overflow: hidden` on the parent container and set `position` to `absolute` on the drawer.
+
+```html preview
+<div class="drawer-in-container" style="position: relative; overflow: hidden; height: 250px; border: solid 2px var(--sl-color-gray-90); margin-bottom: 1rem;">
+  <sl-drawer label="Title" position="absolute" style="--width: 50%;">
+    I'm attached to a parent container
+  </sl-drawer>
+</div>
+<sl-button>Open Drawer</sl-button>
+
+<script>
+  (() => {
+    const drawer = document.querySelector('.drawer-in-container > sl-drawer');
+    const openButton = document.querySelector('.drawer-in-container').nextElementSibling;
+  
+    openButton.addEventListener('click', () => drawer.show());
+  })();
+</script>
+```
+
+### Pinned
+
+By default, drawers are closed when the user interacts outside of it (e.g. clicks outside). The `pinned` prop keeps the drawer open until the user explicitly closes it. When using this, consider providing a visual indicator to the user so it's obvious that the drawer can't be dismissed in the usual way.
+
+```html preview
+<sl-drawer label="Title" pinned class="drawer-pinned">
+  <div style="border: dashed 2px var(--sl-color-gray-90); height: calc(100% - 4px);"></div>
+  <sl-button slot="footer" type="primary">Close</sl-button>
+</sl-drawer>
+
+<sl-button>Toggle Drawer</sl-button>
+
+<script>
+  (() => {
+    const drawer = document.querySelector('.drawer-pinned');
+    const toggleButton = drawer.nextElementSibling;
+    const closeButton = drawer.querySelector('sl-button[type="primary"]');
+
+    toggleButton.addEventListener('click', () => drawer.open = !drawer.open);
+    closeButton.addEventListener('click', () => drawer.hide());
+  })();
+</script>
+```
--- a/docs/overview/roadmap.md
+++ b/docs/overview/roadmap.md
@@ -11,6 +11,7 @@ The roadmap tracks the status of components and features that are planned, in de
 - [x] Color Picker
 - [x] Details
 - [x] Dialog
+- [ ] Drawer
 - [x] Dropdown
 - [ ] Form
 - [x] Icon
@@ -19,7 +20,6 @@ The roadmap tracks the status of components and features that are planned, in de
 - [x] Menu Divider
 - [x] Menu Item
 - [x] Menu Label
- [ ] Panel
 - [x] Progress Bar
 - [x] Progress Ring
 - [x] Radio
--- a/src/components.d.ts
+++ b/src/components.d.ts
@@ -182,9 +182,35 @@ export namespace Components {
         */
        "hide": () => Promise<boolean>;
        /**
-          * When true, the dialog will not be dismissed when the user clicks on the overlay.
+          * The dialog's label as displayed in the header. You should always include a relevant label even when using `no-header`, as it is required for proper accessibility.
         */
-        "ignoreOverlayClicks": boolean;
+        "label": string;
+        /**
+          * Set to true to disable the footer.
+         */
+        "noFooter": boolean;
+        /**
+          * Set to true to disable the header. This will also remove the default close button, so please ensure you provide an easy, accessible way for users to dismiss the dialog.
+         */
+        "noHeader": boolean;
+        /**
+          * Indicates whether or not the dialog is open. You can use this in lieu of the show/hide methods.
+         */
+        "open": boolean;
+        /**
+          * When true, the dialog will not be dismissed when the user clicks outside of it.
+         */
+        "pinned": boolean;
+        /**
+          * Shows the dialog
+         */
+        "show": () => Promise<boolean>;
+    }
+    interface SlDrawer {
+        /**
+          * Hides the dialog
+         */
+        "hide": () => Promise<boolean>;
        /**
          * The dialog's label as displayed in the header. You should always include a relevant label even when using `no-header`, as it is required for proper accessibility.
         */
@@ -201,6 +227,18 @@ export namespace Components {
          * Indicates whether or not the dialog is open. You can use this in lieu of the show/hide methods.
         */
        "open": boolean;
+        /**
+          * Prevents the drawer from closing automatically when the user interacts outside of it (e.g. clicks something outside of it).
+         */
+        "pinned": boolean;
+        /**
+          * The location from which the drawer will slide out.
+         */
+        "placement": 'left' | 'right';
+        /**
+          * The drawer's position. Use `fixed` to make the drawer slide out from the viewport. To make the drawer slide out of an arbitrary element, use `absolute` and place the drawer inside a `position: relative` container and set `overflow: hidden` on it.
+         */
+        "position": 'absolute' | 'fixed';
        /**
          * Shows the dialog
         */
@@ -794,6 +832,12 @@ declare global {
        prototype: HTMLSlDialogElement;
        new (): HTMLSlDialogElement;
    };
+    interface HTMLSlDrawerElement extends Components.SlDrawer, HTMLStencilElement {
+    }
+    var HTMLSlDrawerElement: {
+        prototype: HTMLSlDrawerElement;
+        new (): HTMLSlDrawerElement;
+    };
    interface HTMLSlDropdownElement extends Components.SlDropdown, HTMLStencilElement {
    }
    var HTMLSlDropdownElement: {
@@ -923,6 +967,7 @@ declare global {
        "sl-color-picker": HTMLSlColorPickerElement;
        "sl-details": HTMLSlDetailsElement;
        "sl-dialog": HTMLSlDialogElement;
+        "sl-drawer": HTMLSlDrawerElement;
        "sl-dropdown": HTMLSlDropdownElement;
        "sl-icon": HTMLSlIconElement;
        "sl-input": HTMLSlInputElement;
@@ -1158,9 +1203,43 @@ declare namespace LocalJSX {
    }
    interface SlDialog {
        /**
-          * When true, the dialog will not be dismissed when the user clicks on the overlay.
+          * The dialog's label as displayed in the header. You should always include a relevant label even when using `no-header`, as it is required for proper accessibility.
         */
-        "ignoreOverlayClicks"?: boolean;
+        "label"?: string;
+        /**
+          * Set to true to disable the footer.
+         */
+        "noFooter"?: boolean;
+        /**
+          * Set to true to disable the header. This will also remove the default close button, so please ensure you provide an easy, accessible way for users to dismiss the dialog.
+         */
+        "noHeader"?: boolean;
+        /**
+          * Emitted after the dialog closes and all transitions are complete.
+         */
+        "onSlAfterHide"?: (event: CustomEvent<any>) => void;
+        /**
+          * Emitted after the dialog opens and all transitions are complete.
+         */
+        "onSlAfterShow"?: (event: CustomEvent<any>) => void;
+        /**
+          * Emitted when the dialog closes. Calling `event.preventDefault()` will prevent it from being closed.
+         */
+        "onSlHide"?: (event: CustomEvent<any>) => void;
+        /**
+          * Emitted when the dialog opens. Calling `event.preventDefault()` will prevent it from being opened.
+         */
+        "onSlShow"?: (event: CustomEvent<any>) => void;
+        /**
+          * Indicates whether or not the dialog is open. You can use this in lieu of the show/hide methods.
+         */
+        "open"?: boolean;
+        /**
+          * When true, the dialog will not be dismissed when the user clicks outside of it.
+         */
+        "pinned"?: boolean;
+    }
+    interface SlDrawer {
        /**
          * The dialog's label as displayed in the header. You should always include a relevant label even when using `no-header`, as it is required for proper accessibility.
         */
@@ -1193,6 +1272,18 @@ declare namespace LocalJSX {
          * Indicates whether or not the dialog is open. You can use this in lieu of the show/hide methods.
         */
        "open"?: boolean;
+        /**
+          * Prevents the drawer from closing automatically when the user interacts outside of it (e.g. clicks something outside of it).
+         */
+        "pinned"?: boolean;
+        /**
+          * The location from which the drawer will slide out.
+         */
+        "placement"?: 'left' | 'right';
+        /**
+          * The drawer's position. Use `fixed` to make the drawer slide out from the viewport. To make the drawer slide out of an arbitrary element, use `absolute` and place the drawer inside a `position: relative` container and set `overflow: hidden` on it.
+         */
+        "position"?: 'absolute' | 'fixed';
    }
    interface SlDropdown {
        /**
@@ -1785,6 +1876,7 @@ declare namespace LocalJSX {
        "sl-color-picker": SlColorPicker;
        "sl-details": SlDetails;
        "sl-dialog": SlDialog;
+        "sl-drawer": SlDrawer;
        "sl-dropdown": SlDropdown;
        "sl-icon": SlIcon;
        "sl-input": SlInput;
@@ -1819,6 +1911,7 @@ declare module "@stencil/core" {
            "sl-color-picker": LocalJSX.SlColorPicker & JSXBase.HTMLAttributes<HTMLSlColorPickerElement>;
            "sl-details": LocalJSX.SlDetails & JSXBase.HTMLAttributes<HTMLSlDetailsElement>;
            "sl-dialog": LocalJSX.SlDialog & JSXBase.HTMLAttributes<HTMLSlDialogElement>;
+            "sl-drawer": LocalJSX.SlDrawer & JSXBase.HTMLAttributes<HTMLSlDrawerElement>;
            "sl-dropdown": LocalJSX.SlDropdown & JSXBase.HTMLAttributes<HTMLSlDropdownElement>;
            "sl-icon": LocalJSX.SlIcon & JSXBase.HTMLAttributes<HTMLSlIconElement>;
            "sl-input": LocalJSX.SlInput & JSXBase.HTMLAttributes<HTMLSlInputElement>;
--- a/src/components/drawer/drawer.scss
+++ b/src/components/drawer/drawer.scss
@@ -0,0 +1,131 @@
+/**
+  * @prop --width: The width of the drawer.
+  */
+:host {
+  display: block;
+
+  --width: 400px;
+}
+
+.drawer {
+  display: flex;
+  flex-direction: column;
+  top: 0;
+  bottom: 0;
+  z-index: var(--sl-z-index-drawer);
+  width: var(--width);
+  background-color: var(--sl-color-white);
+  transition: var(--sl-transition-medium) transform;
+  overflow: auto;
+}
+
+.drawer--fixed {
+  position: fixed;
+}
+
+.drawer--absolute {
+  position: absolute;
+}
+
+.drawer--left {
+  right: auto;
+  left: 0;
+  border-right: solid 1px var(--sl-color-gray-95);
+  transform: translateX(-100%);
+}
+
+.drawer--right {
+  right: 0;
+  left: auto;
+  border-left: solid 1px var(--sl-color-gray-95);
+  transform: translateX(100%);
+}
+
+.drawer--open {
+  box-shadow: var(--sl-shadow-x-large);
+  transform: translateX(0);
+}
+
+.drawer__overlay {
+  position: fixed;
+  z-index: 1;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  background-color: rgba(0, 0, 0, 0.5);
+  opacity: 0;
+  transition: var(--sl-transition-medium) opacity;
+}
+
+.drawer--open .drawer__overlay {
+  opacity: 1;
+}
+
+.drawer__header {
+  flex: 0 0 auto;
+  display: flex;
+}
+
+.drawer__title {
+  flex: 1 1 auto;
+  font-size: var(--sl-font-size-large);
+  line-height: var(--sl-line-height-dense);
+  padding: var(--sl-spacing-medium);
+}
+
+.drawer__close {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  background: none;
+  border: none;
+  border-radius: var(--sl-border-radius-small);
+  font-family: inherit;
+  font-size: var(--sl-font-size-large);
+  font-weight: inherit;
+  color: var(--sl-color-gray-50);
+  padding: 0 var(--sl-spacing-large);
+  cursor: pointer;
+  transition: var(--sl-transition-fast) color;
+  -webkit-appearance: none;
+
+  &:hover,
+  &:focus,
+  &:active {
+    color: var(--sl-color-primary-50);
+  }
+
+  &:focus {
+    outline: none;
+  }
+}
+
+.focus-visible .drawer__close:focus {
+  box-shadow: var(--sl-focus-ring-box-shadow);
+}
+
+.drawer__body {
+  flex: 1 1 auto;
+  position: relative;
+  overflow: auto;
+  overscroll-behavior: none;
+  padding: var(--sl-spacing-medium);
+}
+
+.drawer__footer {
+  flex: 0 0 auto;
+  padding: var(--sl-spacing-medium);
+
+  ::slotted(sl-button:not(:first-of-type)) {
+    margin-left: var(--sl-spacing-x-small);
+  }
+}
+
+.drawer--right .drawer__footer {
+  text-align: left;
+}
+
+.drawer--left .drawer__footer {
+  text-align: right;
+}
--- a/src/components/drawer/drawer.tsx
+++ b/src/components/drawer/drawer.tsx
@@ -0,0 +1,194 @@
+import { Component, Element, Event, EventEmitter, Method, Prop, Watch, h } from '@stencil/core';
+import { focusVisible } from '../../utilities/focus-visible';
+
+/**
+ * @since 1.0.0
+ * @status ready
+ */
+
+@Component({
+  tag: 'sl-drawer',
+  styleUrl: 'drawer.scss',
+  shadow: true
+})
+export class Drawer {
+  drawer: HTMLElement;
+
+  constructor() {
+    this.handleCloseClick = this.handleCloseClick.bind(this);
+    this.handleDocumentKeyDown = this.handleDocumentKeyDown.bind(this);
+    this.handleDocumentMouseDown = this.handleDocumentMouseDown.bind(this);
+    this.handleTransitionEnd = this.handleTransitionEnd.bind(this);
+  }
+
+  @Element() host: HTMLSlDrawerElement;
+
+  /** The location from which the drawer will slide out. */
+  @Prop() placement: 'left' | 'right' = 'right';
+
+  /**
+   * The drawer's position. Use `fixed` to make the drawer slide out from the viewport. To make the drawer slide out
+   * of an arbitrary element, use `absolute` and place the drawer inside a `position: relative` container and set
+   * `overflow: hidden` on it.
+   */
+  @Prop() position: 'absolute' | 'fixed' = 'fixed';
+
+  /**
+   * The dialog's label as displayed in the header. You should always include a relevant label even when using
+   * `no-header`, as it is required for proper accessibility.
+   */
+  @Prop() label = '';
+
+  /**
+   * Prevents the drawer from closing automatically when the user interacts outside of it (e.g. clicks something outside
+   * of it).
+   */
+  @Prop() pinned = false;
+
+  /**
+   * Set to true to disable the header. This will also remove the default close button, so please ensure you provide an
+   * easy, accessible way for users to dismiss the dialog.
+   */
+  @Prop() noHeader = false;
+
+  /** Set to true to disable the footer. */
+  @Prop() noFooter = false;
+
+  /** Indicates whether or not the dialog is open. You can use this in lieu of the show/hide methods. */
+  @Prop({ mutable: true, reflect: true }) open = false;
+
+  @Watch('open')
+  handleOpenChange() {
+    this.open ? this.show() : this.hide();
+  }
+
+  /** Emitted when the dialog opens. Calling `event.preventDefault()` will prevent it from being opened. */
+  @Event() slShow: EventEmitter;
+
+  /** Emitted after the dialog opens and all transitions are complete. */
+  @Event() slAfterShow: EventEmitter;
+
+  /** Emitted when the dialog closes. Calling `event.preventDefault()` will prevent it from being closed. */
+  @Event() slHide: EventEmitter;
+
+  /** Emitted after the dialog closes and all transitions are complete. */
+  @Event() slAfterHide: EventEmitter;
+
+  componentDidLoad() {
+    focusVisible.observe(this.drawer);
+
+    // Show on init if open
+    if (this.open) {
+      this.show();
+    }
+  }
+
+  componentDidUnload() {
+    focusVisible.unobserve(this.drawer);
+  }
+
+  /** Shows the dialog */
+  @Method()
+  async show() {
+    const slShow = this.slShow.emit();
+
+    if (slShow.defaultPrevented) {
+      return false;
+    }
+
+    this.host.hidden = false;
+    this.host.clientWidth; // force a reflow
+    this.open = true;
+
+    document.addEventListener('keydown', this.handleDocumentKeyDown);
+    document.addEventListener('mousedown', this.handleDocumentMouseDown);
+  }
+
+  /** Hides the dialog */
+  @Method()
+  async hide() {
+    const slHide = this.slHide.emit();
+
+    if (slHide.defaultPrevented) {
+      return false;
+    }
+
+    this.open = false;
+
+    document.removeEventListener('keydown', this.handleDocumentKeyDown);
+    document.addEventListener('mousedown', this.handleDocumentMouseDown);
+  }
+
+  handleCloseClick() {
+    this.hide();
+  }
+
+  handleDocumentKeyDown(event: KeyboardEvent) {
+    if (event.key === 'Escape') {
+      this.hide();
+    }
+  }
+
+  handleDocumentMouseDown(event: MouseEvent) {
+    const target = event.target as HTMLElement;
+
+    // Close when clicking outside of the drawer
+    if (!this.pinned && target.closest('sl-drawer') !== this.host) {
+      this.hide();
+    }
+  }
+
+  handleTransitionEnd(event: TransitionEvent) {
+    const target = event.target as HTMLElement;
+
+    // Ensure we only handle one transition event on the target element
+    if (event.propertyName === 'transform' && target.classList.contains('drawer')) {
+      this.host.hidden = !this.open;
+      this.open ? this.slAfterShow.emit() : this.slAfterHide.emit();
+    }
+  }
+
+  render() {
+    return (
+      <div
+        ref={el => (this.drawer = el)}
+        class={{
+          drawer: true,
+          'drawer--open': this.open,
+
+          // Position
+          'drawer--absolute': this.position === 'absolute',
+          'drawer--fixed': this.position === 'fixed',
+
+          // Placement
+          'drawer--left': this.placement === 'left',
+          'drawer--right': this.placement === 'right'
+        }}
+        aria-hidden={!this.open}
+        onTransitionEnd={this.handleTransitionEnd}
+      >
+        {!this.noHeader && (
+          <header class="drawer__header">
+            <span class="drawer__title">
+              {/* If there's no label, use an invisible character to prevent the heading from collapsing */}
+              {this.label || String.fromCharCode(65279)}
+            </span>
+            <button class="drawer__close" type="button" onClick={this.handleCloseClick}>
+              <sl-icon name="x"></sl-icon>
+            </button>
+          </header>
+        )}
+
+        <div class="drawer__body">
+          <slot />
+        </div>
+
+        {!this.noFooter && (
+          <footer class="drawer__footer">
+            <slot name="footer" />
+          </footer>
+        )}
+      </div>
+    );
+  }
+}
--- a/src/styles/shoelace.scss
+++ b/src/styles/shoelace.scss
@@ -211,6 +211,7 @@
  --sl-z-index-panel: 80;
  --sl-z-index-notification: 90;
  --sl-z-index-overlay: 100;
+  --sl-z-index-drawer: 500;
  --sl-z-index-dialog: 600;
  --sl-z-index-dropdown: 800;
  --sl-z-index-tooltip: 1000;