Allow toggling sidebar navigator on/off, for large breakpoints (#99)

closes rdar://89564104

* feat: allow toggling the navigator on desktop resolutions
* feat: allow dragging to close entirely
* fix: make sure hidden item is hidden, even for Screen Readers and tab index
* fix: add separator to sidebar toggle icon
* fix: navigator toggle focus area
* fix: navigator closing overflow issues
* feat: track container size on screen or sidebar resize
* refactor: improve the toggle icon animation
* refactor: improvements to the large navigator toggling
* fix: issues with body height and weirdly wrapping text
* refactor: allow navigator toggle to be shown on small only
* refactor: properly add `.sidebar-transitioning` class to the AdjustableSidebarWidth, when in transition.
* fix: NavigatorCard.vue close icon focus area
* refactor: minor cleanup of constants
* fix: quirk in chrome

Author: Dobromir Hristov

src/components/AdjustableSidebarWidth.vue

@@ -9,7 +9,13 @@
 -->
 
 <template>
-  <div class="adjustable-sidebar-width">
+  <div
+    class="adjustable-sidebar-width"
+    :class="{
+      dragging: isDragging,
+      'sidebar-hidden': hiddenOnLarge
+    }"
+  >
     <div
       ref="sidebar"
       class="sidebar"
@@ -19,8 +25,9 @@
         :style="asideStyles"
         class="aside"
         ref="aside"
-        @transitionstart="isTransitioning = true"
-        @transitionend="isTransitioning = false"
+        :aria-hidden="hiddenOnLarge ? 'true': null"
+        @transitionstart="trackTransitionStart"
+        @transitionend="trackTransitionEnd"
       >
         <slot
           name="aside"
@@ -35,7 +42,7 @@
         @touchstart.prevent="startDrag"
       />
     </div>
-    <div class="content">
+    <div class="content" ref="content">
       <slot />
     </div>
     <BreakpointEmitter :scope="BreakpointScopes.nav" @change="breakpoint = $event" />
@@ -96,8 +103,13 @@ export default {
   components: {
     BreakpointEmitter,
   },
+  inject: ['store'],
   props: {
-    openExternally: {
+    shownOnMobile: {
+      type: Boolean,
+      default: false,
+    },
+    hiddenOnLarge: {
       type: Boolean,
       default: false,
     },
@@ -149,12 +161,13 @@ export default {
       '--app-height': `${windowHeight}px`,
     }),
     asideClasses: ({
-      isDragging, openExternally, noTransition, isTransitioning, mobileTopOffset,
+      isDragging, shownOnMobile, noTransition, isTransitioning, hiddenOnLarge, mobileTopOffset,
     }) => ({
       dragging: isDragging,
-      'force-open': openExternally,
+      'show-on-mobile': shownOnMobile,
+      'hide-on-large': hiddenOnLarge,
       'no-transition': noTransition,
-      animating: isTransitioning,
+      'sidebar-transitioning': isTransitioning,
       'has-mobile-top-offset': mobileTopOffset,
     }),
     scrollLockID: () => SCROLL_LOCK_ID,
@@ -175,7 +188,7 @@ export default {
       window.removeEventListener('resize', this.storeWindowSize);
       window.removeEventListener('orientationchange', this.storeWindowSize);
       window.removeEventListener('scroll', this.storeTopOffset);
-      if (this.openExternally) {
+      if (this.shownOnMobile) {
         this.toggleScrollLock(false);
       }
       if (this.focusTrapInstance) this.focusTrapInstance.destroy();
@@ -208,7 +221,13 @@ export default {
       // re-apply transitions
       this.noTransition = false;
     },
-    openExternally: 'handleExternalOpen',
+    shownOnMobile: 'handleExternalOpen',
+    isTransitioning(value) {
+      if (!value) this.updateContentWidthInStore();
+    },
+    hiddenOnLarge() {
+      this.isTransitioning = true;
+    },
   },
   methods: {
     getWidthInCheck: debounce(function getWidthInCheck() {
@@ -226,10 +245,11 @@ export default {
       await this.$nextTick();
       this.windowWidth = window.innerWidth;
       this.windowHeight = window.innerHeight;
+      this.updateContentWidthInStore();
     }, 100),
     closeMobileSidebar() {
-      if (!this.openExternally) return;
-      this.$emit('update:openExternally', false);
+      if (!this.shownOnMobile) return;
+      this.$emit('update:shownOnMobile', false);
     },
     startDrag({ type }) {
       this.isTouch = type === 'touchstart';
@@ -254,8 +274,18 @@ export default {
       if (newWidth > this.maxWidth) {
         newWidth = this.maxWidth;
       }
+      // calculate the forceClose cutoff point
+      const forceCloseCutoff = this.minWidth / 2;
+      // if we are going beyond the cutoff point and we are closed, open the navigator
+      if (this.hiddenOnLarge && newWidth >= forceCloseCutoff) {
+        this.$emit('update:hiddenOnLarge', false);
+      }
       // prevent from shrinking too much
       this.width = Math.max(newWidth, this.minWidth);
+      // if the new width is smaller than the cutoff point, force close the nav
+      if (newWidth <= forceCloseCutoff) {
+        this.$emit('update:hiddenOnLarge', true);
+      }
     },
     /**
      * Stop the dragging upon mouse up
@@ -273,6 +303,7 @@ export default {
     },
     emitEventChange(width) {
       this.$emit('width-change', width);
+      this.updateContentWidthInStore();
     },
     getTopOffset() {
       const stickyNavAnchor = document.getElementById(baseNavStickyAnchorId);
@@ -286,6 +317,10 @@ export default {
       }
       this.toggleScrollLock(isOpen);
     },
+    async updateContentWidthInStore() {
+      await this.$nextTick();
+      this.store.setContentWidth(this.$refs.content.offsetWidth);
+    },
     /**
      * Toggles the scroll lock on/off
      */
@@ -307,6 +342,16 @@ export default {
     storeTopOffset: throttle(function storeTopOffset() {
       this.topOffset = this.getTopOffset();
     }, 60),
+    trackTransitionStart({ propertyName }) {
+      if (propertyName === 'width' || propertyName === 'transform') {
+        this.isTransitioning = true;
+      }
+    },
+    trackTransitionEnd({ propertyName }) {
+      if (propertyName === 'width' || propertyName === 'transform') {
+        this.isTransitioning = false;
+      }
+    },
   },
 };
 </script>
@@ -320,6 +365,14 @@ export default {
     display: block;
     position: relative;
   }
+
+  &.dragging /deep/ * {
+    cursor: col-resize !important;
+  }
+
+  &.sidebar-hidden.dragging /deep/ * {
+    cursor: e-resize !important;
+  }
 }
 
 .sidebar {
@@ -339,6 +392,22 @@ export default {
     transition: none !important;
   }
 
+  @include breakpoints-from(large, nav) {
+
+    &:not(.dragging) {
+      transition: width $adjustable-sidebar-hide-transition-duration ease-in,
+      visibility 0s linear 0s;
+    }
+
+    &.hide-on-large {
+      width: 0 !important;
+      visibility: hidden;
+      pointer-events: none;
+      transition: width $adjustable-sidebar-hide-transition-duration ease-in,
+      visibility 0s linear $adjustable-sidebar-hide-transition-duration;
+    }
+  }
+
   @include breakpoint(medium, nav) {
     width: 100% !important;
     overflow: hidden;
@@ -348,15 +417,15 @@ export default {
     position: fixed;
     top: var(--top-offset-mobile);
     bottom: 0;
-    z-index: $nav-z-index;
+    z-index: $nav-z-index + 1;
     transform: translateX(-100%);
     transition: transform 0.15s ease-in;
 
     /deep/ .aside-animated-child {
       opacity: 0;
     }
 
-    &.force-open {
+    &.show-on-mobile {
       transform: translateX(0);
 
       /deep/ .aside-animated-child {

src/components/DocumentationTopic.vue

@@ -391,12 +391,6 @@ export default {
   outline-style: none;
   height: 100%;
 
-  @include with-adjustable-sidebar {
-    @include breakpoints-from(xlarge) {
-      border-right: 1px solid var(--color-grid);
-    }
-  }
-
   @include inTargetIde {
     min-height: 100vh;
     display: flex;