Appearance
useTouch · useVelocity
The swipe-to-open/close gesture of an edge-anchored panel, and the sliding velocity history it uses to detect a fling.
useTouch
ts
function useTouch (options: {
isActive: Ref<boolean>
isTemporary: Ref<boolean>
width: Ref<number>
touchless: Ref<boolean>
position: Ref<'left' | 'right' | 'top' | 'bottom'>
}): {
isDragging: ShallowRef<boolean>
dragProgress: ShallowRef<number>
dragStyles: ComputedRef<{ transform: string, transition: string } | undefined>
}Everything arrives as refs — there is no props object, and no ADR-005 exposure. isActive is written by the hook at the end of a gesture.
The gesture, step by step
touchstart— ignored outright whentouchless.value. The gesture only arms when the finger starts in the edge zone (TOUCH_EDGE_ZONE_PXfrom the anchored side), inside the already-open panel, or when the panel is both active and temporary. It then records the start point and seedsoffset/dragProgress.touchmove— the drag direction is decided at the first crossing ofTOUCH_DRAG_THRESHOLD_PX: the movement must exceed the threshold on the panel's own axis and dominate the other one, otherwise the gesture is abandoned to the page. A non-cancelable move also abandons it.touchend— the panel settles by velocity first: a fling aboveTOUCH_FLING_VELOCITY_X/…_Yon the dominant axis setsisActivefrom the fling direction (TOUCH_OPEN_DIRECTION_BY_POSITION). Otherwise it settles ondragProgress > TOUCH_SETTLE_PROGRESS.
dragStyles
While dragging, it emits a transform: translate(…) tied directly to dragProgress, plus transition: 'none' so the panel tracks the finger without lag. It is undefined when not dragging — it is the consuming component's job to restore its normal transition once isDragging falls back to false.
touchless does not remove the listeners
It is checked at the top of handleTouchstart only. The three window listeners stay attached for the component's whole life; a touchless panel simply never arms a gesture. touchmove and touchend are not gated by it at all — they are inert because maybeDragging and isDragging never became true.
Lifecycle
onMounted attaches touchstart / touchmove / touchend on window (passive: true for start and end, passive: false for move, which needs preventDefault), and onBeforeUnmount removes all three. Since registration happens in onMounted, nothing touches window during SSR.
Usage
vue
<script setup lang="ts">
import { computed, ref, toRef } from 'vue'
import { useTouch } from 'origam/composables'
const props = withDefaults(defineProps<{
modelValue?: boolean
touchless?: boolean
position?: 'left' | 'right' | 'top' | 'bottom'
}>(), { modelValue: false, touchless: false, position: 'left' })
const isActive = ref(props.modelValue)
const { isDragging, dragStyles } = useTouch({
isActive,
isTemporary: ref(true),
width: ref(256),
touchless: toRef(props, 'touchless'),
position: computed(() => props.position)
})
</script>
<template>
<aside class="origam-drawer" :style="dragStyles" :data-dragging="isDragging">
<slot />
</aside>
</template>Consumers
1 component, verified by import: OrigamDrawer.
Source
packages/ds/src/composables/Commons/touch.composable.ts
useVelocity
ts
function useVelocity (): {
addMovement: (e: TouchEvent) => void
endTouch: (e: TouchEvent) => void
getVelocity: (id: number) => {
x: number
y: number
readonly direction: 'left' | 'right' | 'up' | 'down'
}
}Keeps a sliding history of positions per touch identifier in a CircularBuffer of size HISTORY, and computes an impulse velocity from the samples inside the most recent HORIZON window only.
⛔ getVelocity throws when the id has no samples
ts
throw new Error(`No samples for touch id ${id}`)Measured verbatim: useVelocity().getVelocity(42) on a fresh instance throws No samples for touch id 42. A caller must have called addMovement at least once for that touch, and must never call getVelocity after endTouch, which deletes the history for that identifier.
direction is a getter
It is recomputed on every read, never cached, from whichever axis has the larger absolute velocity. When both are equal it calls oops() — the DS's "unreachable" helper.
Usage
ts
import { useVelocity } from 'origam/composables'
const { addMovement, endTouch, getVelocity } = useVelocity()
const onTouchMove = (e: TouchEvent) => addMovement(e)
const onTouchEnd = (e: TouchEvent) => {
const id = e.changedTouches[0].identifier
const { x, direction } = getVelocity(id) // before endTouch, never after
if (Math.abs(x) > 400) {
// eslint-disable-next-line no-console
console.log('fling', direction)
}
endTouch(e)
}Note the ordering: useTouch calls addMovement(e) on touchend before reading the velocity, so the release point is part of the impulse.
Consumers
1 importer in packages/ds/src, verified by import: composables/Commons/touch.composable.ts.
Source
packages/ds/src/composables/Commons/velocity.composable.tspackages/ds/src/utils/Commons/velocity.util.ts—calculateImpulseVelocity.packages/ds/src/classes/Commons/circular-buffer.class.ts.