@propelinc/citrus-ui 0.6.0 → 1.0.0

package/src/components/CBottomSheet.vue

@@ -0,0 +1,430 @@
+<!-- eslint-disable vue/no-deprecated-slot-attribute -->
+<template>
+  <!--
+   For no-header prop below:
+   See https://vuejs.org/guide/extras/web-components#passing-dom-properties
+   Shoelace does not seem to properly specify the no-header prop; otherwise
+   a false value resolves to no-header="false" which is actually truthy
+  -->
+  <sl-drawer
+    ref="sheet"
+    class="c-bottom-sheet"
+    :class="{
+      'c-bottom-sheet--hide-overlay': !overlay,
+      'c-bottom-sheet--hide-title': hideTitle,
+      'c-bottom-sheet--with-footer': footerHasContent,
+      'c-bottom-sheet--with-dismiss': isDismissVisible,
+    }"
+    :style="{
+      '--panel-transform': panelTransform,
+      '--background-color-hex-code': backgroundCssColor,
+      '--overlay-opacity': overlayOpacity,
+      '--size': fixedSize || undefined,
+    }"
+    :data-test="getDataTestAttr()"
+    :open="animatedValue || undefined"
+    :no-header="hideTitle || undefined"
+    :label="ariaLabel"
+    placement="bottom"
+    :contained="contained || undefined"
+    :divided="divided || undefined"
+    @sl-request-close="onRequestClose"
+    @sl-hide="handleDismiss"
+    @sl-after-hide="onAfterClose"
+    @sl-after-show="$emit('opened')"
+  >
+    <div slot="label" :data-test="value ? `${dataTest}-title` : null">
+      <slot name="header">{{ title }}</slot>
+    </div>
+
+    <slot name="image" />
+
+    <div class="c-bottom-sheet__body" :data-test="getDataTestAttr('body')">
+      <slot name="body" />
+    </div>
+
+    <!-- NOTE(andrew): This renders in the body when the title is hidden because the header-actions
+     slot is not rendered when the title is hidden. Previously this only rendered in the body but
+     this caused issues on iOS where a scrollable body renders in a separate layer and the button
+     got rendered invisibly underneath the header. This is intentionally placed after the body so
+     it renders on top. -->
+    <div
+      v-if="isDismissVisible"
+      :slot="hideTitle ? undefined : 'header-actions'"
+      class="c-bottom-sheet__actions"
+    >
+      <c-close-button
+        :data-test="getDataTestAttr('dismiss')"
+        :disabled="disableDismiss"
+        @click="internalValue = false"
+      />
+    </div>
+
+    <CButtonStack v-if="footerHasContent" slot="footer" :data-test="getDataTestAttr('footer')">
+      <slot name="footer" />
+    </CButtonStack>
+  </sl-drawer>
+</template>
+
+<script lang="ts">
+import { faXmark } from '@fortawesome/pro-regular-svg-icons';
+import '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
+import type SlDrawer from '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
+import type { ElementAnimation } from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
+import { setAnimation } from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
+import type { Ref } from 'vue';
+import { computed, defineComponent, nextTick, onMounted, ref, toRefs } from 'vue';
+
+import CButtonStack from '@propelinc/citrus-ui/src/components/CButtonStack.vue';
+import CCloseButton from '@propelinc/citrus-ui/src/components/internal/CCloseButton.vue';
+import { useInternalValue } from '@propelinc/citrus-ui/src/composables/binding';
+import { useCssColor } from '@propelinc/citrus-ui/src/composables/colors';
+import { useShoelaceShadowParts } from '@propelinc/citrus-ui/src/composables/elements';
+import {
+  useDragListener,
+  useElasticClamp,
+  useScrollBoundary,
+} from '@propelinc/citrus-ui/src/composables/gestures';
+import { useSlotHasContent } from '@propelinc/citrus-ui/src/composables/slots';
+import { fadeIn, fadeOut, slideDown, slideUp } from '@propelinc/citrus-ui/src/services/animation';
+
+/** Minimum distance, in pixels, the user has to drag for it to be considered a
+ * successful swipe. */
+const MIN_SWIPE_DISTANCE = 100;
+/** The minimum speed, in pixels per millisecond, the user has to drag down for
+ * it to be considered a successful swipe. */
+const MIN_SWIPE_VELOCITY = 0.75;
+/** The minimum speed, in pixels per millisecond, to animate the sheet sliding
+ * down after a successful swipe. */
+const MIN_DISMISS_VELOCITY = 1.5;
+/** Minimum duration, in milliseconds, for the slide down animation after a
+ * successful drag. */
+const MIN_DISMISS_DURATION = 100;
+/** Maximum distance the sheet can move in a direction it can't be dragged. */
+const DRAG_CLAMP_DISTANCE = 240;
+/** Fallback height for the sheet if the actual height is unknown. */
+const SHEET_HEIGHT_FALLBACK = 300;
+
+/**
+ * Was having issues with the useShoelaceAnimation composable not updating the animation quickly
+ * enough using the `watch` or `watchEffect` hooks, so we're just going to set the animations
+ * directly whenever we need to change the animation.
+ */
+function setCustomAnimation(
+  el: Ref<Element | null>,
+  name: string,
+  animation: ElementAnimation
+): void {
+  if (!el.value) {
+    return;
+  }
+
+  setAnimation(el.value, name, animation);
+}
+
+export default defineComponent({
+  components: { CButtonStack, CCloseButton },
+  props: {
+    /** Aria label for the bottom sheet. This is required if title is hidden */
+    ariaLabel: { type: String, default: '' },
+    /** Background color of the bottom sheet */
+    backgroundColor: { type: String, default: '' },
+    /** Prefix for test selectors */
+    dataTest: { type: String, default: 'bottom-sheet' },
+    /** Disables the dismiss button */
+    disableDismiss: { type: Boolean, default: false },
+    /** Divided into header, body, and footer slots */
+    divided: { type: Boolean, default: false },
+    /** Fixed size, in CSS units. By default the drawer sizes itself to its contents. */
+    fixedSize: { type: String, default: '' },
+    /** Hides the dismiss 'x' button */
+    hideDismiss: { type: Boolean, default: false },
+    /** Allows for hiding the entire title bar, both the title and the dismiss 'x' button */
+    hideTitle: { type: Boolean, default: false },
+    /** Toggles the background behind the sheet. If there's no overlay, the sheet
+     * stays open as the user interacts with background content.' */
+    overlay: { type: Boolean, default: true },
+    /** Prevents the sheet from being dismissed when tapping on the overlay. If
+     * there is no overlay then this property is ignored, as the sheet always
+     * stays open. */
+    persistent: { type: Boolean, default: false },
+    /** If true, the bottom sheet will be contained within the viewport. */
+    contained: { type: Boolean, default: false },
+    /** Do not animate in the bottom sheet if it starts open. */
+    skipInitialAnimation: { type: Boolean, default: false },
+    /** The title of the bottom sheet */
+    title: { type: String, default: '' },
+    /** Controls whether or not the bottom sheet is showing */
+    value: { type: Boolean, default: false },
+  },
+  emits: ['input', 'opened', 'closed'],
+  setup(props, { emit }) {
+    // NOTE(slanden): Temporarily disabling because it's causing a lot of errors
+    // in the console - uses from CMS aren't specifying aria-label.
+    // watchEffect(() => {
+    //   if (props.hideTitle && !props.ariaLabel) {
+    //     console.error('CBottomSheet: aria-label is required when title is hidden');
+    //   }
+    // });
+
+    // value: Value provided using props which can open/close the bottom sheet.
+    // internalValue: Tracks the open/closed state and lets the bottom sheet open and close even if
+    //                the external value doesn't change.
+    // animatedValue: Same as internalValue but starts at false so the bottom sheet animates if it
+    //                starts in an open state.
+    const { value } = toRefs(props);
+    const internalValue = useInternalValue(value, { onChange: (value) => emit('input', value) });
+    const mounted = ref(false);
+    const animatedValue = computed(() => {
+      // To animate in the bottom sheet we mount the component with the sheet closed.
+      if (!props.skipInitialAnimation && !mounted.value) {
+        return false;
+      }
+      return internalValue.value;
+    });
+    const { cssColor: backgroundCssColor } = useCssColor(() => props.backgroundColor);
+    onMounted(async () => {
+      // The bottom sheet does not animate unless we wait a tick. We don't know exactly why this
+      // is necessary.
+      await nextTick();
+      mounted.value = true;
+    });
+
+    const sheet = ref<SlDrawer | null>(null);
+    const { panel, overlay, body } = useShoelaceShadowParts(sheet, ['panel', 'overlay', 'body']);
+    useScrollBoundary(body);
+
+    // NOTE(mohan): There are three parts to the bottom sheet animation:
+    // 1. CSS variables. These are used when we want to set the exact height and
+    //    opacity, i.e. when the user is actively moving the sheet.
+    // 2. The built-in Shoelace show and hide animations. If a user has swiped
+    //    the sheet away, we calculate the exact animation that will smoothly
+    //    continue the swipe and then dismiss the shoelace drawer.
+    // 3. Manually-called web animations. These are used when the sheet is being
+    //    restored to its original position after a drag that was not fast or
+    //    long enough to count as a swipe.
+    setCustomAnimation(sheet, 'drawer.showBottom', slideUp());
+    setCustomAnimation(sheet, 'drawer.overlay.show', fadeIn());
+    setCustomAnimation(sheet, 'drawer.hideBottom', slideDown());
+    setCustomAnimation(sheet, 'drawer.overlay.hide', fadeOut());
+
+    const handleDismiss = (): void => {
+      internalValue.value = false;
+    };
+
+    const onRequestClose = (event: Event): void => {
+      if (props.persistent) {
+        event.preventDefault();
+      }
+    };
+
+    const onAfterClose = (): void => {
+      // Reset the exit animations in case they were changed in a drag event
+      setCustomAnimation(sheet, 'drawer.hideBottom', slideDown());
+      setCustomAnimation(sheet, 'drawer.overlay.hide', fadeOut());
+      emit('closed');
+    };
+
+    /**
+     * Helper function to calculate the distance ratio of the sheet's transform.
+     */
+    const getTransformDistanceRatio = (distance: number): number => {
+      return distance / (panel.value?.clientHeight ?? SHEET_HEIGHT_FALLBACK);
+    };
+
+    const { dragDistance } = useDragListener(panel, {
+      onDragEnd: async ({ distance, velocity }) => {
+        const shouldDismiss =
+          !props.persistent && (distance.y > MIN_SWIPE_DISTANCE || velocity.y > MIN_SWIPE_VELOCITY);
+
+        if (shouldDismiss) {
+          const remainingDismissDistance = panel.value!.clientHeight - dragDistance.value!.y;
+          const dismissDuration = Math.max(
+            remainingDismissDistance / Math.max(velocity.y, MIN_DISMISS_VELOCITY),
+            MIN_DISMISS_DURATION
+          );
+          const dismissStart = getTransformDistanceRatio(distance.y);
+
+          // Here we set the custom animations to complete the dismissal animation smoothly
+          // from the point where the user ended their drag event.
+          setCustomAnimation(
+            sheet,
+            'drawer.hideBottom',
+            slideDown({ start: dismissStart, duration: dismissDuration })
+          );
+          setCustomAnimation(
+            sheet,
+            'drawer.overlay.hide',
+            fadeOut({ start: dismissStart, duration: dismissDuration })
+          );
+          handleDismiss();
+        } else {
+          /**
+           * This is when the user's drag event fails to trigger a dismissal
+           * We need to restore the sheet to its original position
+           */
+          const start = 1 - getTransformDistanceRatio(dragDistance.value!.y);
+          const slideUpAnimation = slideUp({ start });
+          const fadeInAnimation = fadeIn({ start });
+
+          // Here we imperatively animate the sheet and overlay back to their original positions
+          panel.value?.animate(slideUpAnimation.keyframes, slideUpAnimation.options);
+          overlay.value?.animate(fadeInAnimation.keyframes, fadeInAnimation.options);
+        }
+      },
+    });
+
+    /**
+     * The distance that the sheet has been currently dragged
+     */
+    const transformDistance = useElasticClamp(
+      computed(() => dragDistance.value?.y ?? 0),
+      computed(() => ({
+        min: -DRAG_CLAMP_DISTANCE,
+        max: props.persistent ? DRAG_CLAMP_DISTANCE : undefined,
+      }))
+    );
+
+    const transformDistanceRatio = computed(() =>
+      getTransformDistanceRatio(transformDistance.value)
+    );
+
+    const panelTransform = computed(() => `translateY(${transformDistance.value}px)`);
+
+    const overlayOpacity = computed(() => {
+      const result = 1 - transformDistanceRatio.value;
+
+      if (isNaN(result)) {
+        return 1;
+      }
+
+      return result;
+    });
+
+    // NOTE(mohan): We show data-test attributes only when the sheet is open.
+    // This helps simplify testing assertions.
+    const getDataTestAttr = (suffix?: string): string | null => {
+      const dataTest = suffix ? `${props.dataTest}-${suffix}` : props.dataTest;
+      return internalValue.value ? dataTest : null;
+    };
+
+    const footerHasContent = useSlotHasContent('footer');
+
+    const isDismissVisible = computed(
+      () => (!props.persistent && !props.hideDismiss) || props.disableDismiss
+    );
+
+    return {
+      backgroundCssColor,
+      animatedValue,
+      dragDistance,
+      faXmark,
+      footerHasContent,
+      getDataTestAttr,
+      handleDismiss,
+      internalValue,
+      isDismissVisible,
+      onRequestClose,
+      overlayOpacity,
+      panelTransform,
+      onAfterClose,
+      sheet,
+      transformDistance,
+    };
+  },
+});
+</script>
+
+<style lang="scss" scoped>
+@import '@propelinc/citrus-ui/src/styles/core';
+@import '@propelinc/citrus-ui/src/styles/utils/a11y';
+
+.c-bottom-sheet {
+  --size: auto;
+  --header-spacing: 24px;
+  --body-spacing: 0;
+  --bottom-padding: max(env(safe-area-inset-bottom, 0px), 16px);
+  --footer-spacing: 12px 24px var(--bottom-padding);
+
+  &::part(header-actions) {
+    padding: 0;
+  }
+
+  &::part(close-button) {
+    @include sr-only;
+  }
+
+  &::part(panel) {
+    background: var(--background-color-hex-code, $color-white);
+    border-radius: 12px 12px 0 0;
+    max-height: 90%;
+    overflow: visible;
+    transform: var(--panel-transform, none);
+
+    &::after {
+      background: var(--background-color-hex-code, $color-white);
+      bottom: -100px;
+      content: '';
+      height: 101px;
+      left: 0;
+      position: absolute;
+      right: 0;
+    }
+  }
+
+  &::part(body) {
+    border-radius: 12px 12px 0 0;
+
+    /**
+     * NOTE (kyleshevlin) adding position: relative here fixed an issue where certain actions (like
+     * clicking a checkbox) would hijack the bottom sheet body up and off the screen.
+     */
+    position: relative;
+  }
+
+  &::part(title) {
+    @include large-headline;
+
+    padding-bottom: 16px;
+  }
+
+  // Note(kayliegh): Add space to prevent long titles from colliding with dismiss button
+  &--with-dismiss::part(title) {
+    margin-right: 28px;
+  }
+
+  &::part(overlay) {
+    opacity: var(--overlay-opacity, 1);
+  }
+}
+
+.c-bottom-sheet__actions {
+  position: absolute;
+  right: 16px;
+  top: 16px;
+}
+
+.c-bottom-sheet__body {
+  padding: 0 24px var(--bottom-padding);
+
+  // NOTE(andrew): When there is a footer the bottom inset is handled by the footer and we just add
+  // spacing above the footer.
+  .c-bottom-sheet--with-footer & {
+    padding-bottom: 12px;
+  }
+}
+
+.c-bottom-sheet--hide-title {
+  // NOTE(mohan): When there is no title, we need to add some spacing to the top
+  // of the body so it doesn't touch the top of the panel.
+  .c-bottom-sheet__body {
+    padding-top: 16px;
+  }
+}
+
+.c-bottom-sheet--hide-overlay {
+  &::part(overlay) {
+    display: none;
+  }
+}
+</style>