@citizenplane/pimp 18.13.4 → 18.14.0

package/src/composables/useBottomSheetDrag.ts

@@ -0,0 +1,221 @@
+import { useResizeObserver, useWindowSize } from '@vueuse/core'
+import type { FullGestureState } from '@vueuse/gesture'
+import { rubberbandIfOutOfBounds } from '@vueuse/gesture'
+import type { ShallowRef } from 'vue'
+import { computed, ref, watch } from 'vue'
+
+type SnapPoint = number | `${number}%`
+
+type ElementRef = Readonly<ShallowRef<HTMLElement | null>>
+
+interface Options {
+  canSwipeClose: boolean
+  expandOnContentDrag: boolean
+  halfAndExpand: boolean
+  preventClose: boolean
+  snapPoints: SnapPoint[]
+  swipeCloseThreshold: string
+}
+
+interface Context {
+  contentRef: ElementRef
+  footerRef: ElementRef
+  headerRef: ElementRef
+  onDismiss: () => void
+  scrollRef: ElementRef
+}
+
+const RUBBERBAND_TENSION = 0.25
+const FLICK_CLOSE_TOLERANCE = 10
+
+export const useBottomSheetDrag = (options: Options, context: Context) => {
+  const { contentRef, footerRef, headerRef, onDismiss, scrollRef } = context
+
+  const { height: windowHeight } = useWindowSize()
+
+  const height = ref<number | null>(null)
+  const translateY = ref(0)
+  const isDragging = ref(false)
+  const naturalHeight = ref(0)
+  const currentSnapPointIndex = ref(0)
+
+  let dragStartHeight = 0
+  let contentDragOffset = 0
+  let isContentDragActive = false
+
+  const measureNaturalHeight = () => {
+    const parts = [headerRef, contentRef, footerRef]
+    const total = parts.reduce((sum, part) => sum + (part.value?.getBoundingClientRect().height ?? 0), 0)
+
+    naturalHeight.value = Math.ceil(total)
+  }
+
+  const resolvedSnapPoints = computed<SnapPoint[]>(() => {
+    if (options.snapPoints.length) return options.snapPoints
+    if (options.halfAndExpand) return ['50%', '100%']
+
+    return [naturalHeight.value]
+  })
+
+  const snapPointHeights = computed(() =>
+    resolvedSnapPoints.value.map((snapPoint) =>
+      typeof snapPoint === 'number'
+        ? Math.min(snapPoint, windowHeight.value)
+        : (windowHeight.value * Number.parseFloat(snapPoint)) / 100,
+    ),
+  )
+
+  const minSnapPointHeight = computed(() => Math.min(...snapPointHeights.value))
+  const maxSnapPointHeight = computed(() => Math.max(...snapPointHeights.value))
+
+  const closestSnapPointIndex = computed(() => {
+    const distances = snapPointHeights.value.map((snapPointHeight) => Math.abs(snapPointHeight - (height.value ?? 0)))
+
+    return distances.indexOf(Math.min(...distances))
+  })
+
+  const swipeCloseDistance = computed(() => {
+    const sheetHeight = height.value ?? minSnapPointHeight.value
+    const threshold = Number.parseFloat(options.swipeCloseThreshold)
+
+    if (Number.isNaN(threshold)) return sheetHeight / 2
+    if (options.swipeCloseThreshold.includes('%')) return (sheetHeight * threshold) / 100
+
+    return threshold
+  })
+
+  const snapTo = (snapPointIndex: number) => {
+    const snapPointHeight = snapPointHeights.value[snapPointIndex]
+    if (snapPointHeight === undefined) return
+
+    currentSnapPointIndex.value = snapPointIndex
+    height.value = snapPointHeight
+    translateY.value = 0
+  }
+
+  const snapToSmallest = () => snapTo(snapPointHeights.value.indexOf(minSnapPointHeight.value))
+
+  const reset = () => {
+    height.value = null
+    translateY.value = 0
+    isDragging.value = false
+  }
+
+  const startDrag = () => {
+    isDragging.value = true
+    dragStartHeight = height.value ?? minSnapPointHeight.value
+  }
+
+  const applyDragOffset = (offsetY: number) => {
+    const targetHeight = dragStartHeight - offsetY
+    const minHeight = minSnapPointHeight.value
+
+    if (targetHeight >= minHeight) {
+      height.value = rubberbandIfOutOfBounds(targetHeight, 0, maxSnapPointHeight.value, RUBBERBAND_TENSION)
+      translateY.value = 0
+      return
+    }
+
+    const overshoot = minHeight - targetHeight
+
+    height.value = minHeight
+    translateY.value = options.canSwipeClose
+      ? overshoot
+      : rubberbandIfOutOfBounds(overshoot, -minHeight, 0, RUBBERBAND_TENSION)
+  }
+
+  const shouldCloseAfterDrag = (swipeY: number) => {
+    if (!options.canSwipeClose || options.preventClose) return false
+
+    const isFlickedDown = swipeY > 0 && (height.value ?? 0) <= minSnapPointHeight.value + FLICK_CLOSE_TOLERANCE
+
+    return isFlickedDown || translateY.value > swipeCloseDistance.value
+  }
+
+  const snapPointIndexInSwipeDirection = (swipeY: number) => {
+    const currentHeight = height.value ?? 0
+    const isSwipingDown = swipeY > 0
+    const reachable = snapPointHeights.value.filter((snapPointHeight) =>
+      isSwipingDown ? snapPointHeight < currentHeight - 1 : snapPointHeight > currentHeight + 1,
+    )
+
+    if (!reachable.length) return closestSnapPointIndex.value
+
+    return snapPointHeights.value.indexOf(isSwipingDown ? Math.max(...reachable) : Math.min(...reachable))
+  }
+
+  const endDrag = (swipeY: number) => {
+    isDragging.value = false
+
+    if (shouldCloseAfterDrag(swipeY)) {
+      onDismiss()
+      return
+    }
+
+    const isSwipe = swipeY !== 0 && snapPointHeights.value.length > 1
+
+    snapTo(isSwipe ? snapPointIndexInSwipeDirection(swipeY) : closestSnapPointIndex.value)
+  }
+
+  const onHandleDrag = ({ first, last, movement, swipe }: FullGestureState<'drag'>) => {
+    if (first) startDrag()
+    else if (last) endDrag(swipe[1])
+    else applyDragOffset(movement[1])
+  }
+
+  const canStartContentDrag = (movementY: number) => {
+    if (!options.expandOnContentDrag) return false
+    if ((scrollRef.value?.scrollTop ?? 0) > 0) return false
+    if (movementY > 0) return true
+
+    return snapPointHeights.value.length > 1 && (height.value ?? 0) < maxSnapPointHeight.value
+  }
+
+  const onContentDrag = ({ first, last, movement, swipe }: FullGestureState<'drag'>) => {
+    if (first) {
+      isContentDragActive = false
+      return
+    }
+
+    if (last) {
+      if (isContentDragActive) endDrag(swipe[1])
+      isContentDragActive = false
+      return
+    }
+
+    if (!isContentDragActive) {
+      if (!canStartContentDrag(movement[1])) return
+
+      isContentDragActive = true
+      contentDragOffset = movement[1]
+      startDrag()
+    }
+
+    applyDragOffset(movement[1] - contentDragOffset)
+  }
+
+  const onScrollTouchMove = (event: TouchEvent) => {
+    if (!isContentDragActive || !event.cancelable) return
+    event.preventDefault()
+  }
+
+  useResizeObserver([headerRef, contentRef, footerRef], measureNaturalHeight)
+
+  watch(snapPointHeights, () => {
+    if (height.value === null || isDragging.value) return
+    snapTo(currentSnapPointIndex.value)
+  })
+
+  return {
+    height,
+    isDragging,
+    measureNaturalHeight,
+    onContentDrag,
+    onHandleDrag,
+    onScrollTouchMove,
+    reset,
+    snapToSmallest,
+    translateY,
+    windowHeight,
+  }
+}

package/src/stories/CpBottomSheet.stories.ts

@@ -15,7 +15,8 @@ const meta = {
   argTypes: {
     animationDuration: {
       control: 'number',
-      description: 'Animation duration in milliseconds',
+      description:
+        'Duration of the spring used to present the sheet, in milliseconds. Leaving reuses a third of it on a dry curve.',
     },
     canBackdropClose: {
       control: 'boolean',
@@ -25,14 +26,27 @@ const meta = {
       control: 'boolean',
       description: 'Enable swipe-to-close gesture',
     },
+    expandOnContentDrag: {
+      control: 'boolean',
+      description: 'Let a drag started on the body move the sheet instead of scrolling it',
+    },
     preventClose: {
       control: 'boolean',
       description: 'Prevent the sheet from emitting close when dismissed',
     },
+    snapPoints: {
+      control: 'object',
+      description: 'Heights the sheet snaps to, in pixels or in percentage of the viewport height',
+    },
     swipeCloseThreshold: {
       control: 'text',
       description: 'Translation threshold after which the sheet closes (px or %)',
     },
+    teleportTo: {
+      control: 'text',
+      description:
+        'Selector the sheet teleports to. Defaults to Nuxt SSR-safe `#teleports` container, falling back to `body` when the host does not provide it.',
+    },
     onClose: { action: 'close' },
     onOpen: { action: 'open' },
   },
@@ -47,7 +61,7 @@ type Story = StoryObj<typeof meta>
  */
 export const Default: Story = {
   args: {
-    animationDuration: 300,
+    animationDuration: 600,
     canBackdropClose: true,
     canSwipeClose: true,
     swipeCloseThreshold: '20%',
@@ -128,6 +142,176 @@ export const NoBackdropClose: Story = {
   }),
 }
 
+/**
+ * With `expandOnContentDrag`, a drag started on the body of the sheet moves the sheet
+ * itself instead of scrolling it. The sheet opens on its smallest snap point (50%):
+ * drag the list upwards to expand it to full height, then drag it back down — once the
+ * list is scrolled to the top — to collapse it and eventually close it. Anywhere else in
+ * the scroll, the body scrolls as usual.
+ *
+ * Turn the `expandOnContentDrag` control off to compare: the body then only ever scrolls,
+ * and the sheet can only be resized from its header or its footer.
+ */
+export const ExpandOnContentDrag: Story = {
+  args: {
+    expandOnContentDrag: true,
+    snapPoints: ['50%', '100%'],
+  },
+  render: (args) => ({
+    setup() {
+      const isVisible = ref(false)
+      const destinations = [
+        'Paris',
+        'London',
+        'Berlin',
+        'Madrid',
+        'Rome',
+        'Lisbon',
+        'Amsterdam',
+        'Vienna',
+        'Prague',
+        'Copenhagen',
+        'Stockholm',
+        'Oslo',
+        'Helsinki',
+        'Dublin',
+        'Brussels',
+        'Zurich',
+        'Warsaw',
+        'Budapest',
+        'Athens',
+        'Porto',
+        'Paris',
+        'London',
+        'Berlin',
+        'Madrid',
+        'Rome',
+        'Lisbon',
+        'Amsterdam',
+        'Vienna',
+        'Prague',
+        'Copenhagen',
+        'Stockholm',
+        'Oslo',
+        'Helsinki',
+        'Dublin',
+        'Brussels',
+        'Zurich',
+        'Warsaw',
+        'Budapest',
+        'Athens',
+        'Porto',
+        'Paris',
+        'London',
+        'Berlin',
+        'Madrid',
+        'Rome',
+        'Lisbon',
+        'Amsterdam',
+        'Vienna',
+        'Prague',
+        'Copenhagen',
+        'Stockholm',
+        'Oslo',
+        'Helsinki',
+        'Dublin',
+        'Brussels',
+        'Zurich',
+        'Warsaw',
+        'Budapest',
+        'Athens',
+        'Porto',
+      ]
+      return { args, isVisible, destinations }
+    },
+    template: `
+      <CpButton @click="isVisible = true">Open Bottom Sheet</CpButton>
+      <CpBottomSheet
+        v-bind="args"
+        v-model="isVisible"
+        @close="isVisible = false"
+      >
+        <template #header><strong>Drag the list to resize the sheet</strong></template>
+        <p v-for="destination in destinations" :key="destination">{{ destination }}</p>
+        <template #footer>
+          <CpButton @click="isVisible = false">Close</CpButton>
+        </template>
+      </CpBottomSheet>
+    `,
+  }),
+}
+
+/**
+ * Sheets can be nested by declaring one inside the slots of another. Every sheet teleports
+ * to the same container, so the child is inserted after its parent and stacks on top of it
+ * with its own backdrop — no `z-index` juggling required.
+ *
+ * Each level keeps its own props, height and gestures: dismiss the child by tapping its
+ * backdrop, swiping it down or using its actions, and the parent is revealed untouched.
+ * Closing the parent unmounts the whole chain.
+ *
+ * The nested levels declare no snap points, so each one measures its own header, body and
+ * footer and shows them in full. Only the parent is given a height, wide enough to stay
+ * visible above its children.
+ */
+export const Nested: Story = {
+  args: {
+    canBackdropClose: true,
+    canSwipeClose: true,
+    snapPoints: ['70%'],
+  },
+  render: (args) => ({
+    setup() {
+      const isVisible = ref(false)
+      const isPassengerVisible = ref(false)
+      const isSeatVisible = ref(false)
+      const passengers = ['Ada Lovelace', 'Grace Hopper', 'Alan Turing']
+      const selectedPassenger = ref(passengers[0])
+      return { args, isVisible, isPassengerVisible, isSeatVisible, passengers, selectedPassenger }
+    },
+    template: `
+      <CpButton @click="isVisible = true">Open Bottom Sheet</CpButton>
+      <CpBottomSheet
+        v-bind="args"
+        v-model="isVisible"
+        @close="isVisible = false"
+      >
+        <template #header><strong>Level 1 — Booking</strong></template>
+        <p>This is the parent sheet. Open the next level to stack a second sheet on top of it.</p>
+        <p>Traveller: <strong>{{ selectedPassenger }}</strong></p>
+
+        <CpBottomSheet v-model="isPassengerVisible" @close="isPassengerVisible = false">
+          <template #header><strong>Level 2 — Passengers</strong></template>
+          <p>Pick a traveller, or go one level deeper.</p>
+          <CpMenuItem
+            v-for="passenger in passengers"
+            :key="passenger"
+            :is-selected="passenger === selectedPassenger"
+            :label="passenger"
+            @click="selectedPassenger = passenger"
+          />
+
+          <CpBottomSheet v-model="isSeatVisible" @close="isSeatVisible = false">
+            <template #header><strong>Level 3 — Seat</strong></template>
+            <p>Third level. Dismiss it to fall back on level 2, still open underneath.</p>
+            <template #footer>
+              <CpButton @click="isSeatVisible = false">Confirm seat</CpButton>
+            </template>
+          </CpBottomSheet>
+
+          <template #footer>
+            <CpButton @click="isSeatVisible = true">Choose a seat</CpButton>
+          </template>
+        </CpBottomSheet>
+
+        <template #footer>
+          <CpButton @click="isPassengerVisible = true">Select passenger</CpButton>
+        </template>
+      </CpBottomSheet>
+    `,
+  }),
+}
+
 /**
  * Disable swipe-to-close — the sheet can only be dismissed
  * by tapping the backdrop or using a close action.

package/src/stories/Easings.stories.ts

@@ -16,10 +16,6 @@ export default meta
 
 type Story = StoryObj
 
-/**
- * Cubic-bezier curves used for the design-system transitions. Hover (or
- * focus) any track to play the animation and compare curves side by side.
- */
 export const Curves: Story = {
   render: () => ({
     setup() {