@propelinc/citrus-ui 0.6.0 → 1.0.0

package/src/components/index.ts

@@ -1,25 +1,66 @@
-export { default as CAccordion } from '@/components/CAccordion.vue';
-export { default as CAccordionItem } from '@/components/CAccordionItem.vue';
-export { default as CAlert } from '@/components/CAlert.vue';
-export { default as CBanner } from '@/components/CBanner.vue';
-export { default as CButton } from '@/components/CButton.vue';
-export { default as CCard } from '@/components/CCard.vue';
-export { default as CCardFooter } from '@/components/CCardFooter.vue';
-export { default as CCardHeader } from '@/components/CCardHeader.vue';
-export { default as CCardSection } from '@/components/CCardSection.vue';
-export { default as CCheckbox } from '@/components/CCheckbox.vue';
-export { default as CIconButton } from '@/components/CIconButton.vue';
-export { default as CListItem } from '@/components/CListItem.vue';
-export { default as CListItemAction } from '@/components/CListItemAction.vue';
-export { default as CListItemIcon } from '@/components/CListItemIcon.vue';
-export { default as CModal } from '@/components/CModal.vue';
-export { default as CModalLoading } from '@/components/CModalLoading.vue';
-export { default as CNotification } from '@/components/CNotification.vue';
-export { default as CSegmentedButton } from '@/components/CSegmentedButton.vue';
-export { default as CSegmentedButtonOption } from '@/components/CSegmentedButtonOption.vue';
-export { default as CSelect } from '@/components/CSelect.vue';
-export { default as CSkeletonLoaderCircle } from '@/components/CSkeletonLoaderCircle.vue';
-export { default as CSkeletonLoaderText } from '@/components/CSkeletonLoaderText.vue';
-export { default as CTextArea } from '@/components/CTextArea.vue';
-export { default as CTextField } from '@/components/CTextField.vue';
-export { default as CTextLink } from '@/components/CTextLink.vue';
+export { default as CAccordion } from '@propelinc/citrus-ui/src/components/CAccordion.vue';
+export { default as CAccordionItem } from '@propelinc/citrus-ui/src/components/CAccordionItem.vue';
+export { default as CAppBar } from '@propelinc/citrus-ui/src/components/CAppBar.vue';
+export { default as CBadge } from '@propelinc/citrus-ui/src/components/CBadge.vue';
+export { default as CBottomSheet } from '@propelinc/citrus-ui/src/components/CBottomSheet.vue';
+export { default as CButton } from '@propelinc/citrus-ui/src/components/CButton/CButton.vue';
+export { default as CCard } from '@propelinc/citrus-ui/src/components/CCard.vue';
+export { default as CCardFooter } from '@propelinc/citrus-ui/src/components/CCardFooter.vue';
+export { default as CCardHeader } from '@propelinc/citrus-ui/src/components/CCardHeader.vue';
+export { default as CCardSection } from '@propelinc/citrus-ui/src/components/CCardSection.vue';
+export { default as CCheckbox } from '@propelinc/citrus-ui/src/components/CCheckbox.vue';
+export { default as CCol } from '@propelinc/citrus-ui/src/components/CCol.vue';
+export { default as CDivider } from '@propelinc/citrus-ui/src/components/CDivider.vue';
+export { default as CDobField } from '@propelinc/citrus-ui/src/components/CDobField.vue';
+export { default as CDobSelect } from '@propelinc/citrus-ui/src/components/CDobSelect.vue';
+export { default as CEmailField } from '@propelinc/citrus-ui/src/components/CEmailField.vue';
+export { default as CExpandTransition } from '@propelinc/citrus-ui/src/components/CExpandTransition.vue';
+export { default as CFadeTransition } from '@propelinc/citrus-ui/src/components/CFadeTransition.vue';
+export { default as CFileInput } from '@propelinc/citrus-ui/src/components/CFileInput.vue';
+export { default as CFixedPageFooter } from '@propelinc/citrus-ui/src/components/CFixedPageFooter.vue';
+export { default as CForm } from '@propelinc/citrus-ui/src/components/CForm.vue';
+export { default as CIconButton } from '@propelinc/citrus-ui/src/components/CIconButton.vue';
+export { default as CLabel } from '@propelinc/citrus-ui/src/components/CLabel.vue';
+export { default as CListItem } from '@propelinc/citrus-ui/src/components/CListItem.vue';
+export { default as CListItemIcon } from '@propelinc/citrus-ui/src/components/CListItemIcon.vue';
+export { default as CLoader } from '@propelinc/citrus-ui/src/components/CLoader.vue';
+export { default as CLogo } from '@propelinc/citrus-ui/src/components/CLogo.vue';
+export { default as CMaskedTextField } from '@propelinc/citrus-ui/src/components/CMaskedTextField.vue';
+export { default as CMenu } from '@propelinc/citrus-ui/src/components/CMenu.vue';
+export { default as CMenuItem } from '@propelinc/citrus-ui/src/components/CMenuItem.vue';
+export { default as CMenuLabel } from '@propelinc/citrus-ui/src/components/CMenuLabel.vue';
+export { default as CModal } from '@propelinc/citrus-ui/src/components/CModal.vue';
+export { default as CModalLoading } from '@propelinc/citrus-ui/src/components/CModalLoading.vue';
+export { default as CNotification } from '@propelinc/citrus-ui/src/components/CNotification.vue';
+export { default as CPhoneField } from '@propelinc/citrus-ui/src/components/CPhoneField.vue';
+export { default as CPill } from '@propelinc/citrus-ui/src/components/CPill.vue';
+export { default as CPillGroup } from '@propelinc/citrus-ui/src/components/CPillGroup.vue';
+export { default as CPopup } from '@propelinc/citrus-ui/src/components/CPopup.vue';
+export { default as CProgressLinear } from '@propelinc/citrus-ui/src/components/CProgressLinear.vue';
+export { default as CProgressRing } from '@propelinc/citrus-ui/src/components/CProgressRing.vue';
+export { default as CRadio } from '@propelinc/citrus-ui/src/components/CRadio.vue';
+export { default as CRadioGroup } from '@propelinc/citrus-ui/src/components/CRadioGroup.vue';
+export { default as CRebrand } from '@propelinc/citrus-ui/src/components/CRebrand.vue';
+export { default as CRow } from '@propelinc/citrus-ui/src/components/CRow.vue';
+export { default as CSafeArea } from '@propelinc/citrus-ui/src/components/CSafeArea.vue';
+export { default as CSectionHeader } from '@propelinc/citrus-ui/src/components/CSectionHeader.vue';
+export { default as CSelect } from '@propelinc/citrus-ui/src/components/CSelect.vue';
+export { default as CSkeleton } from '@propelinc/citrus-ui/src/components/CSkeleton.vue';
+export { default as CSkeletonLoaderCard } from '@propelinc/citrus-ui/src/components/CSkeletonLoaderCard.vue';
+export { default as CSkeletonLoaderCircle } from '@propelinc/citrus-ui/src/components/CSkeletonLoaderCircle.vue';
+export { default as CSkeletonLoaderText } from '@propelinc/citrus-ui/src/components/CSkeletonLoaderText.vue';
+export { default as CSlideFadeTransition } from '@propelinc/citrus-ui/src/components/CSlideFadeTransition.vue';
+export { default as CSplitInput } from '@propelinc/citrus-ui/src/components/CSplitInput.vue';
+export { default as CSquaredIcon } from '@propelinc/citrus-ui/src/components/CSquaredIcon.vue';
+export { default as CSsnField } from '@propelinc/citrus-ui/src/components/CSsnField.vue';
+export { default as CStatusDot } from '@propelinc/citrus-ui/src/components/CStatusDot.vue';
+export { default as CSwitch } from '@propelinc/citrus-ui/src/components/CSwitch.vue';
+export { default as CSwitchListItem } from '@propelinc/citrus-ui/src/components/CSwitchListItem.vue';
+export { default as CTextArea } from '@propelinc/citrus-ui/src/components/CTextArea.vue';
+export { default as CTextField } from '@propelinc/citrus-ui/src/components/CTextField.vue';
+export { default as CTextLink } from '@propelinc/citrus-ui/src/components/CTextLink.vue';
+export { default as CThirdPartyLogo } from '@propelinc/citrus-ui/src/components/CThirdPartyLogo.vue';
+export { default as CTimeago } from '@propelinc/citrus-ui/src/components/CTimeago.vue';
+export { default as CToast } from '@propelinc/citrus-ui/src/components/CToast.vue';
+export { default as CToastsList } from '@propelinc/citrus-ui/src/components/CToastsList.vue';
+export { default as CZipcodeField } from '@propelinc/citrus-ui/src/components/CZipcodeField.vue';

package/src/components/internal/CCloseButton.vue

@@ -0,0 +1,57 @@
+<template>
+  <button
+    v-tap-animation
+    class="c-close-button"
+    data-test="c-close-button"
+    :aria-label="$t('Close')"
+    :disabled="disabled"
+    @click="onClick"
+  >
+    <font-awesome-icon :icon="faXmark" />
+  </button>
+</template>
+
+<script setup lang="ts">
+import { faXmark } from '@fortawesome/pro-regular-svg-icons';
+import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome';
+
+import { tapAnimation as vTapAnimation } from '@propelinc/citrus-ui/src/services/directives';
+
+defineProps<{
+  disabled?: boolean;
+}>();
+
+const emit = defineEmits(['click', 'focus', 'blur']);
+
+const onClick = (): void => {
+  emit('click');
+};
+</script>
+
+<style lang="scss" scoped>
+@import '@propelinc/citrus-ui/src/styles/core';
+@import '@propelinc/citrus-ui/src/styles/button';
+
+.c-close-button {
+  align-items: center;
+  border-radius: 50%;
+  cursor: pointer;
+  display: flex;
+  font-size: $font-size-icon-medium;
+  height: 36px;
+  justify-content: center;
+  padding: 8px;
+  width: 36px;
+
+  @include button-theme-close;
+
+  &:focus {
+    /**
+     * This is a workaround to get the focus ring to work with the button. Since we're not using Shoelace,
+     * we need to use the focus ring styles from Shoelace. Long term, we should create a custom focus ring styles.
+     */
+    outline: var(--sl-focus-ring-width) solid var(--sl-focus-ring-color);
+    outline-offset: var(--sl-focus-ring-offset);
+  }
+}
+</style>

package/src/composables/accessibility.ts

@@ -0,0 +1,29 @@
+import { onMounted, useAttrs } from 'vue';
+
+export function useA11yLabelCheck(componentName: string, props?: Record<string, unknown>): void {
+  const attrs = useAttrs();
+
+  onMounted(() => {
+    const enableCheck = process.env.VUE_APP_DEBUG === 'yes' || process.env.NODE_ENV === 'test';
+    if (!enableCheck) {
+      return;
+    }
+
+    if (
+      attrs.title ||
+      props?.title ||
+      attrs['aria-label'] ||
+      props?.ariaLabel ||
+      attrs['aria-labelledby'] ||
+      props?.ariaLabelledby ||
+      attrs['aria-hidden'] ||
+      props?.ariaHidden
+    ) {
+      return;
+    }
+
+    console.error(
+      `Missing ${componentName} label. This component won't be intelligible to screen readers. Typically, this is resolved by providing an aria-label.`
+    );
+  });
+}

package/src/composables/animation.ts

@@ -0,0 +1,95 @@
+import type { ElementAnimation } from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
+import {
+  getAnimation,
+  setAnimation,
+} from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
+import type { Ref } from 'vue';
+import { isRef, onMounted, ref, unref, watch } from 'vue';
+
+type MaybeRef<T> = T | Ref<T>;
+
+export function useShoelaceAnimation(
+  el: Ref<Element | null>,
+  animationName: string,
+  animation: MaybeRef<ElementAnimation | 'default' | null>
+): void {
+  let defaultAnimation: ElementAnimation | null = null;
+
+  onMounted(() => {
+    if (el.value) {
+      defaultAnimation = getAnimation(el.value, animationName, { dir: 'ltr' });
+
+      const animationValue = unref(animation);
+      if (animationValue !== 'default') {
+        setAnimation(el.value, animationName, animationValue);
+      }
+    }
+  });
+
+  if (isRef(animation)) {
+    watch(animation, () => {
+      if (el.value) {
+        const nextAnimation = animation.value === 'default' ? defaultAnimation : animation.value;
+        setAnimation(el.value, animationName, nextAnimation);
+      }
+    });
+  }
+}
+
+const TAP_ANIMATION_DURATION_MS = 100;
+
+export function useTapAnimation({
+  el,
+  keyframes,
+}: {
+  el: Ref<Element | null>;
+  keyframes: { default: Keyframe; pressed: Keyframe };
+}): Record<string, () => void> {
+  const downAnimation = ref<Animation | null>(null);
+  const upAnimation = ref<Animation | null>(null);
+
+  function onPointerDown(): void {
+    if (!el.value) {
+      return;
+    }
+
+    upAnimation.value?.cancel();
+    upAnimation.value = null;
+
+    downAnimation.value?.cancel();
+    downAnimation.value = el.value.animate([keyframes.default, keyframes.pressed], {
+      duration: TAP_ANIMATION_DURATION_MS,
+      fill: 'forwards',
+    });
+  }
+
+  async function onPointerUp(): Promise<void> {
+    if (!downAnimation.value || upAnimation.value || !el.value) {
+      return;
+    }
+
+    // NOTE(mohan): Cancelling the animation will cause the finished promise to
+    // throw an error.
+    await downAnimation.value.finished.catch(() => {});
+    if (!el.value) {
+      // NOTE(slanden): This can happen if the element is removed from the DOM
+      // while the down animation is running.
+      return;
+    }
+    upAnimation.value = el.value.animate([keyframes.pressed, keyframes.default], {
+      duration: TAP_ANIMATION_DURATION_MS,
+      fill: 'forwards',
+    });
+
+    await upAnimation.value.finished.catch(() => {});
+    upAnimation.value = null;
+    downAnimation.value = null;
+  }
+
+  return {
+    pointerdown: onPointerDown,
+    pointerup: onPointerUp,
+    pointerleave: onPointerUp,
+    pointercancel: onPointerUp,
+  };
+}

package/src/composables/binding.ts

@@ -0,0 +1,34 @@
+import type { Ref } from 'vue';
+import { ref, watch } from 'vue';
+
+/**
+ * A composable that creates a ref that tracks the value of the provided ref.
+ *
+ * Whenever the provided ref changes, the returned ref updates, but not the
+ * other way around. When the returned ref changes, the `onChange` callback is
+ * called (if provided).
+ *
+ * Useful for components that need to respond both to user input and to
+ * programmatic changes.
+ *
+ * @param value - The value to bind to the internal value.
+ * @param options.onChange - A callback function that is called when the
+ * internal value changes.
+ * @returns A ref to the internal value.
+ */
+export function useInternalValue<T>(
+  value: Ref<T>,
+  options: { onChange?: (value: T) => void } = {}
+): Ref<T> {
+  const internalValue = ref(value.value) as Ref<T>;
+  watch(value, (value) => {
+    internalValue.value = value;
+  });
+  watch(internalValue, (newInternalValue) => {
+    if (newInternalValue !== value.value) {
+      options.onChange?.(newInternalValue);
+    }
+  });
+
+  return internalValue;
+}

package/src/composables/colors.ts

@@ -0,0 +1,59 @@
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import { computed, toValue } from 'vue';
+
+import Colors, {
+  type CssColor,
+  isColorKey,
+  isCssColor,
+} from '@propelinc/citrus-ui/src/colors/colors';
+
+/**
+ * Maps from a color name or hex code to its corresponding CSS color value.
+ * Gray neutrals resolve to rgba(); other palette colors are hex.
+ *
+ * @param name - The color to resolve. Can be in kebab case, SCREAMING_SNAKE_CASE, or a hex code from the palette.
+ * @returns The CSS color value (hex or rgba) and whether the color is valid.
+ */
+export function useCssColor(name: MaybeRefOrGetter<string | undefined>): {
+  cssColor: Ref<CssColor | undefined>;
+  isValidColor: Ref<boolean>;
+} {
+  const normalizedColor = computed(() =>
+    isCssColor(toValue(name)) ? (toValue(name)?.toLowerCase() as CssColor) : undefined
+  );
+  const normalizedName = computed(() => {
+    if (!toValue(name)) {
+      return undefined;
+    }
+
+    // If it is a CSS color already, we don't need to know its name
+    if (isCssColor(toValue(name))) {
+      return undefined;
+    }
+
+    return toValue(name)?.replace(/-/g, '_').toUpperCase();
+  });
+
+  const cssColor = computed(() => {
+    // If we're given a color key, return the palette value (hex or rgba)
+    if (normalizedName.value && isColorKey(normalizedName.value)) {
+      return Colors[normalizedName.value];
+    }
+
+    // If we're given a CSS color AND it's in the palette, return it
+    if (
+      isCssColor(normalizedColor.value) &&
+      Object.values(Colors).includes(normalizedColor.value)
+    ) {
+      return normalizedColor.value;
+    }
+
+    return undefined;
+  });
+
+  const isValidColor = computed(() => {
+    return cssColor.value !== undefined;
+  });
+
+  return { cssColor, isValidColor };
+}

package/src/composables/elements.ts

@@ -0,0 +1,72 @@
+import type { Ref } from 'vue';
+import { onBeforeUnmount, onMounted, ref, watch } from 'vue';
+
+// NOTE(mohan): A simplified port of vueuse/core's useResizeObserver.
+// vueuse has type errors because our version of vue is so old.
+export function useResizeObserver(
+  element: Ref<HTMLElement | null>,
+  callback: (entries: ResizeObserverEntry[]) => void
+): void {
+  if (!('ResizeObserver' in window)) {
+    return;
+  }
+
+  let observer: ResizeObserver | null = null;
+
+  watch(
+    element,
+    (value) => {
+      if (value) {
+        observer = new ResizeObserver(callback);
+        observer.observe(value);
+      }
+    },
+    { immediate: true }
+  );
+
+  onBeforeUnmount(() => {
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+  });
+}
+
+export function useShoelaceShadowParts<T extends string>(
+  shoelaceComponent: Ref<HTMLElement | null>,
+  parts: T[]
+): Record<T, Ref<HTMLElement | null>> {
+  const shadowParts = parts.reduce<Record<T, Ref<HTMLElement | null>>>(
+    (acc, part) => {
+      return { ...acc, [part]: ref<HTMLElement | null>(null) };
+    },
+    {} as Record<T, Ref<HTMLElement | null>>
+  );
+
+  onMounted(async () => {
+    if (!shoelaceComponent.value) {
+      return;
+    }
+
+    try {
+      await customElements.whenDefined(shoelaceComponent.value.tagName.toLowerCase());
+    } catch {
+      // TODO: (kyleshevlin) we had to stub out Shoelace component in tests, which causes this to fail
+      // because there is no tagName for the stubbed component
+      // Silently handle error
+      return;
+    }
+
+    // Make sure the component hasn't been destroyed at this point.
+    const shadowRoot = shoelaceComponent.value?.shadowRoot;
+    if (!shadowRoot) {
+      return;
+    }
+
+    for (const part of parts) {
+      shadowParts[part].value = shadowRoot.querySelector(`[part="${part}"]`);
+    }
+  });
+
+  return shadowParts;
+}

package/src/composables/fields.ts

@@ -0,0 +1,19 @@
+import { type Ref, type SetupContext, computed, ref } from 'vue';
+
+export interface Field {
+  input: HTMLInputElement | null;
+}
+
+interface FocusableField {
+  field: Ref<Field | null>;
+}
+
+export function useFocusableField(expose: SetupContext['expose']): FocusableField {
+  const field = ref<Field | null>(null);
+  const input = computed(() => field.value?.input as HTMLInputElement);
+  function focus(): void {
+    input?.value.focus();
+  }
+  expose({ focus });
+  return { field };
+}

package/src/composables/gestures.ts

@@ -0,0 +1,197 @@
+import type { Ref } from 'vue';
+import { computed, onMounted, ref, watch } from 'vue';
+
+export interface Coordinate {
+  x: number;
+  y: number;
+}
+
+interface SimplifiedPointerEvent {
+  position: Coordinate;
+  timestamp: number;
+}
+
+type DragCallback = (dragDetails: {
+  /** How far the user has dragged in pixels */
+  distance: Coordinate;
+  /** Velocity of drag in pixels/ms */
+  velocity: Coordinate;
+}) => void;
+
+/**
+ * Listens for drag events on the provided element and tracks the distance and
+ * velocity of the drag.
+ *
+ * @param element - The element to listen for drag events on.
+ * @param options.onDragEnd - A callback that is called when the drag ends.
+ * @returns An object containing the drag distance and velocity.
+ */
+export const useDragListener = (
+  element: Ref<HTMLElement | null>,
+  options?: {
+    onDragEnd?: DragCallback;
+  }
+): {
+  dragDistance: Ref<Coordinate | null>;
+  dragVelocity: Ref<Coordinate | null>;
+} => {
+  const startDragTouch = ref<SimplifiedPointerEvent | null>(null);
+  const lastDragTouch = ref<SimplifiedPointerEvent | null>(null);
+
+  const dragVelocity = ref<Coordinate | null>(null);
+  const dragDistance = computed(() => {
+    if (!startDragTouch.value || !lastDragTouch.value) {
+      return { x: 0, y: 0 };
+    }
+    return {
+      x: lastDragTouch.value.position.x - startDragTouch.value.position.x,
+      y: lastDragTouch.value.position.y - startDragTouch.value.position.y,
+    };
+  });
+
+  const simplifyEvent = (event: TouchEvent): SimplifiedPointerEvent => {
+    const { clientX: x, clientY: y } = event.touches[0];
+    return { position: { x, y }, timestamp: event.timeStamp };
+  };
+
+  const touchStartListener = (event: TouchEvent): void => {
+    startDragTouch.value = simplifyEvent(event);
+    lastDragTouch.value = startDragTouch.value;
+  };
+
+  const touchMoveListener = (event: TouchEvent): void => {
+    const newEvent = simplifyEvent(event);
+    if (lastDragTouch.value) {
+      const timeDelta = newEvent.timestamp - lastDragTouch.value.timestamp;
+      dragVelocity.value = {
+        x: (newEvent.position.x - lastDragTouch.value.position.x) / timeDelta,
+        y: (newEvent.position.y - lastDragTouch.value.position.y) / timeDelta,
+      };
+    }
+    lastDragTouch.value = newEvent;
+  };
+
+  const touchEndListener = (): void => {
+    options?.onDragEnd?.({
+      distance: dragDistance.value,
+      velocity: dragVelocity.value ?? { x: 0, y: 0 },
+    });
+    startDragTouch.value = null;
+    lastDragTouch.value = null;
+    dragVelocity.value = null;
+  };
+
+  const addListeners = (element: HTMLElement | null): void => {
+    if (element) {
+      element.addEventListener('touchstart', touchStartListener);
+      element.addEventListener('touchmove', touchMoveListener);
+      element.addEventListener('touchend', touchEndListener);
+    }
+  };
+
+  const removeListeners = (element: HTMLElement | null): void => {
+    if (element) {
+      element.removeEventListener('touchstart', touchStartListener);
+      element.removeEventListener('touchmove', touchMoveListener);
+      element.removeEventListener('touchend', touchEndListener);
+    }
+  };
+
+  onMounted(async () => {
+    addListeners(element.value);
+  });
+
+  watch(element, (newElement, oldElement) => {
+    removeListeners(oldElement);
+    addListeners(newElement);
+  });
+
+  return { dragDistance, dragVelocity };
+};
+
+/**
+ * Adds listeners to the provided element to prevent it from emitting touch
+ * events when it is scrolling.
+ *
+ * @param element - A scrollable element inside a draggable component.
+ */
+export const useScrollBoundary = (element: Ref<HTMLElement | null>): void => {
+  const isScrolling = ref(false);
+  const onScroll = (): void => {
+    isScrolling.value = true;
+  };
+
+  const onTouchEvent = (event: TouchEvent): void => {
+    if (isScrolling.value) {
+      event.stopPropagation();
+    }
+  };
+  const onTouchEnd = (event: TouchEvent): void => {
+    onTouchEvent(event);
+    isScrolling.value = false;
+  };
+
+  const addListeners = (element: HTMLElement | null): void => {
+    if (element) {
+      element.addEventListener('scroll', onScroll);
+      element.addEventListener('touchstart', onTouchEvent);
+      element.addEventListener('touchmove', onTouchEvent);
+      element.addEventListener('touchend', onTouchEnd);
+    }
+  };
+
+  const removeListeners = (element: HTMLElement | null): void => {
+    if (element) {
+      element.removeEventListener('scroll', onScroll);
+      element.removeEventListener('touchstart', onTouchEvent);
+      element.removeEventListener('touchmove', onTouchEvent);
+      element.removeEventListener('touchend', onTouchEnd);
+    }
+  };
+
+  onMounted(() => {
+    addListeners(element.value);
+  });
+
+  watch(element, (newElement, oldElement) => {
+    removeListeners(oldElement);
+    addListeners(newElement);
+  });
+};
+
+/**
+ * Clamps a value in between the provided min and max values. As the value
+ * increases above 0, it will approach the max, but will never reach it (and
+ * vice versa for the min).
+ *
+ * This can be used to create a "springy" effect where as a user pulls further
+ * on an element, it will move less and less.
+ *
+ * @param value - The value to clamp.
+ * @param options.min - The minimum value to keep the value above.
+ * @param options.max - The maximum value to keep the value below.
+ * @param options.resistance - The resistance value which determines how quickly
+ * the value approaches the min or max.
+ * @returns The clamped value.
+ */
+export const useElasticClamp = (
+  value: Ref<number | null>,
+  options?: Ref<{ min?: number; max?: number; resistance?: number }>
+): Ref<number> => {
+  return computed(() => {
+    if (value.value === null) {
+      return 0;
+    }
+
+    const resistance = options?.value?.resistance ?? 7;
+    const { min, max } = options?.value ?? {};
+    const absValue = Math.abs(value.value);
+    if (min && value.value < 0) {
+      return (min * absValue) / (absValue - min * resistance);
+    } else if (max && value.value > 0) {
+      return (max * absValue) / (absValue + max * resistance);
+    } else {
+      return value.value;
+    }
+  });
+};

package/src/composables/i18n.ts

@@ -0,0 +1,13 @@
+import { getCurrentInstance } from 'vue';
+
+export function useTranslation(): {
+  t: (key: string, interpolations?: Record<string, string | number>) => string;
+} {
+  const currentInstance = getCurrentInstance();
+
+  if (!currentInstance || !currentInstance.proxy) {
+    throw new Error('useTranslation must be called within a Vue component');
+  }
+
+  return { t: currentInstance.proxy.$t };
+}