@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/gestures/GestureMath.d.ts

@@ -0,0 +1,182 @@
+import { GestureAxis } from './GestureAxis';
+import { SwipeDirection } from './SwipeDirection';
+/** A point in screen coordinates — `clientX` / `clientY` as reported by a pointer event. */
+export interface GesturePoint {
+    /** Horizontal position in CSS pixels, growing rightward. */
+    readonly x: number;
+    /** Vertical position in CSS pixels, growing DOWNWARD. */
+    readonly y: number;
+}
+/** A point plus the moment it was observed — one entry in a gesture's trailing movement history. */
+export interface GestureSample extends GesturePoint {
+    /** Timestamp in milliseconds, from the source event's `timeStamp`. Only differences are ever used. */
+    readonly t: number;
+}
+/**
+ * Speed along one axis, in CSS pixels per millisecond.
+ *
+ * Returns `0` for a non-positive or non-finite interval — two pointer events can share a timestamp, and a gesture
+ * must not report infinite speed because the clock did not tick.
+ *
+ * @param delta Distance travelled on the axis, in CSS pixels. Sign is preserved, so the result is signed too.
+ * @param elapsedMs Time the movement took, in milliseconds.
+ * @returns Signed velocity in px/ms; `0` when `elapsedMs <= 0`.
+ */
+export declare function gestureVelocity(delta: number, elapsedMs: number): number;
+/**
+ * Velocity over the tail of a movement history, which is what "was that a flick" actually asks.
+ *
+ * Neither naive reading works. Measuring across the WHOLE gesture reports a fast release that followed a long
+ * slow drag as slow. Measuring the LAST PAIR of samples is worse: `pointerup` repeats the final `pointermove`
+ * coordinates a few milliseconds later, so a genuine flick would end at exactly zero — the single most common
+ * way a swipe recognizer silently stops working. Two rules together fix both:
+ *
+ *  1. A TRAILING RUN OF STATIONARY SAMPLES IS TRIMMED. A sample at the same position as its predecessor carries
+ *     no speed information, so measurement ends at the last point the pointer actually moved.
+ *  2. UNLESS THE POINTER REALLY STOPPED. If that last moving sample is further back than the window, the trim is
+ *     abandoned and the answer is zero: pressing, flicking, HOLDING, then releasing is not a flick, and rule 1
+ *     alone would report the stale speed from before the hold.
+ *
+ * Between those, the base is the oldest sample still inside the window; when everything earlier has aged out, the
+ * immediately-preceding sample is used instead, so a slow drag still reports its real (small) speed.
+ *
+ * @param samples Chronological history, oldest first; the last entry is treated as "now".
+ * @param windowMs How far back to reach, in milliseconds.
+ * @returns Signed px/ms on each axis; both `0` when fewer than two samples exist or the pointer had come to rest.
+ */
+export declare function windowedVelocity(samples: readonly GestureSample[], windowMs: number): {
+    readonly velocityX: number;
+    readonly velocityY: number;
+};
+/**
+ * Resolves a two-axis displacement to the single direction a swipe reads as.
+ *
+ * The dominant axis wins. An exact diagonal (`|dx| === |dy|`, both non-zero) is broken toward the HORIZONTAL axis
+ * — an arbitrary but fixed choice, made so the answer is deterministic rather than dependent on argument order;
+ * a caller that needs the other bias should compare the deltas itself.
+ *
+ * @param dx Horizontal displacement in CSS pixels; negative is leftward.
+ * @param dy Vertical displacement in CSS pixels; negative is upward.
+ * @returns The dominant {@link SwipeDirection}, or `null` when there was no movement at all.
+ */
+export declare function swipeDirection(dx: number, dy: number): SwipeDirection | null;
+/**
+ * Straight-line distance between two points, in CSS pixels.
+ *
+ * @param a First point.
+ * @param b Second point.
+ * @returns The non-negative distance; `0` if either coordinate is non-finite.
+ */
+export declare function pointerDistance(a: GesturePoint, b: GesturePoint): number;
+/**
+ * Angle of the line from `a` to `b`, in degrees.
+ *
+ * Measured from the positive x-axis and rotating CLOCKWISE, because `y` grows downward on screen: `0` points
+ * right, `90` points down, `-90` points up.
+ *
+ * @param a Origin point.
+ * @param b Target point.
+ * @returns The angle in degrees, within `[-180, 180]`.
+ */
+export declare function pointerAngle(a: GesturePoint, b: GesturePoint): number;
+/**
+ * Midpoint of two points — the anchor a pinch should scale and rotate about.
+ *
+ * @param a First point.
+ * @param b Second point.
+ * @returns The midpoint in the same screen coordinates.
+ */
+export declare function pointerCenter(a: GesturePoint, b: GesturePoint): GesturePoint;
+/**
+ * Scale factor of a pinch — how far apart the two pointers are now, relative to where they started.
+ *
+ * `1` means unchanged, `2` means the fingers doubled their separation, `0.5` means they halved it.
+ *
+ * Returns `1` for a non-positive starting distance: two pointers that went down on the same pixel define no
+ * baseline to scale against, and dividing by it would hand a consumer `Infinity` to write into a transform.
+ *
+ * @param startDistance Separation when the pinch began, in CSS pixels.
+ * @param currentDistance Separation now, in CSS pixels.
+ * @returns The multiplicative scale factor; `1` when no valid baseline exists.
+ */
+export declare function pinchScale(startDistance: number, currentDistance: number): number;
+/**
+ * Signed rotation of a pinch, in degrees, taking the shortest way round.
+ *
+ * Crossing the ±180° seam is the whole reason this is not a subtraction: a pointer pair rotating from 170° to
+ * -170° turned 20° clockwise, not 340° counter-clockwise.
+ *
+ * @param startAngle Angle between the pointers when the pinch began, in degrees.
+ * @param currentAngle Angle between them now, in degrees.
+ * @returns The rotation in degrees within `[-180, 180)`; positive is clockwise on screen.
+ */
+export declare function pinchRotation(startAngle: number, currentAngle: number): number;
+/**
+ * Wraps an arbitrary angle into a single turn.
+ *
+ * @param degrees Any angle, including multiples of a full turn.
+ * @returns The equivalent angle within `[-180, 180)` — note `180` normalizes to `-180`.
+ */
+export declare function normalizeAngle(degrees: number): number;
+/**
+ * Zeroes the component a constrained gesture must not report, so a consumer can bind the payload straight to a
+ * transform without re-clamping it.
+ *
+ * @param dx Horizontal displacement in CSS pixels.
+ * @param dy Vertical displacement in CSS pixels.
+ * @param axis The axis the gesture is locked to.
+ * @returns The displacement with the off-axis component set to `0`.
+ */
+export declare function constrainToAxis(dx: number, dy: number, axis: GestureAxis): {
+    readonly dx: number;
+    readonly dy: number;
+};
+/**
+ * Whether a displacement has travelled far enough to count, measured along the gesture's own axis.
+ *
+ * This is the gate that stops a drag from stealing a click: below the threshold the pointer is still "pressing",
+ * not "dragging". An unconstrained gesture measures straight-line distance; a constrained one measures only its
+ * axis, so a vertical scroll never trips an `axis: 'x'` drag.
+ *
+ * A threshold of `0` always passes — that is the documented way to recognize on pointer-down.
+ *
+ * @param dx Horizontal displacement in CSS pixels.
+ * @param dy Vertical displacement in CSS pixels.
+ * @param threshold Distance in CSS pixels that must be met or exceeded. Non-finite is treated as `0`.
+ * @param axis The axis the gesture is locked to.
+ * @returns `true` once the displacement reaches the threshold.
+ */
+export declare function exceedsThreshold(dx: number, dy: number, threshold: number, axis: GestureAxis): boolean;
+/**
+ * Whether a pointer has stayed still enough for a hold to survive — the inverse gate to {@link exceedsThreshold},
+ * and always measured as straight-line distance because a hold is not directional.
+ *
+ * @param dx Horizontal displacement in CSS pixels since the press began.
+ * @param dy Vertical displacement in CSS pixels since the press began.
+ * @param tolerance Slack in CSS pixels, to absorb the finger tremor every real touch carries. Non-finite is `0`.
+ * @returns `true` while the pointer remains within tolerance.
+ */
+export declare function withinTolerance(dx: number, dy: number, tolerance: number): boolean;
+/**
+ * Applies a `pointerTypes` allowlist to one pointer.
+ *
+ * `undefined` means no filter — every input device is accepted. An EMPTY array is read literally as "accept
+ * nothing" rather than being quietly upgraded to "accept everything": an allowlist that arrived empty from a
+ * caller's own filtering should visibly disable the gesture, not silently widen it.
+ *
+ * @param pointerType The event's `pointerType` — conventionally `'mouse'`, `'touch'`, or `'pen'`.
+ * @param allowed The allowlist, or `undefined` for no filtering.
+ * @returns `true` when this pointer may drive the gesture.
+ */
+export declare function acceptsPointerType(pointerType: string, allowed: readonly string[] | undefined): boolean;
+/**
+ * Clamps a long-press delay into the shared `PressExtensions.longPressDelay` bounds.
+ *
+ * The bounds are NOT redefined here — they are the same `min` / `max` / `default` every other press-driven
+ * component in the library already honours, so a hold configured on a `Button` and a hold configured through
+ * `useLongPress` can never disagree about what counts as "too fast to be deliberate".
+ *
+ * @param delayMs The requested delay in milliseconds; `undefined` or non-finite falls back to the shared default.
+ * @returns A delay within `[min, max]`.
+ */
+export declare function clampLongPressDelay(delayMs: number | undefined): number;

package/dist/foundation/gestures/SwipeDirection.d.ts

@@ -0,0 +1,13 @@
+/** Which way a swipe travelled, in screen coordinates. */
+export declare const SwipeDirection: {
+    /** Toward smaller `clientX` — the pointer moved left across the screen. */
+    readonly Left: "left";
+    /** Toward larger `clientX` — the pointer moved right across the screen. */
+    readonly Right: "right";
+    /** Toward smaller `clientY` — the pointer moved up the screen. */
+    readonly Up: "up";
+    /** Toward larger `clientY` — the pointer moved down the screen. */
+    readonly Down: "down";
+};
+/** One of the {@link SwipeDirection} values. */
+export type SwipeDirection = (typeof SwipeDirection)[keyof typeof SwipeDirection];

package/dist/foundation/gestures/UseDrag.d.ts

@@ -0,0 +1,75 @@
+import { MaybeRefOrGetter } from 'vue';
+import { GestureAxis } from './GestureAxis';
+/** What a drag handler receives — the full state of the gesture at the moment of the call. */
+export interface DragPayload {
+    /** Horizontal distance from the press origin, in CSS pixels. Zeroed when `axis` is `'y'`. */
+    readonly dx: number;
+    /** Vertical distance from the press origin, in CSS pixels. Zeroed when `axis` is `'x'`. */
+    readonly dy: number;
+    /** Current pointer position — the event's `clientX`, viewport-relative and never axis-constrained. */
+    readonly x: number;
+    /** Current pointer position — the event's `clientY`, viewport-relative and never axis-constrained. */
+    readonly y: number;
+    /** Horizontal speed in px/ms over the recent movement window, NOT over the whole drag. Signed. */
+    readonly velocityX: number;
+    /** Vertical speed in px/ms over the recent movement window, NOT over the whole drag. Signed. */
+    readonly velocityY: number;
+    /** Milliseconds since the pointer went down — the whole gesture, unlike the velocity fields. */
+    readonly elapsedMs: number;
+    /** The DOM pointer event that produced this payload, for `preventDefault`, modifier keys, or `pointerType`. */
+    readonly event: PointerEvent;
+}
+/** The callbacks a drag can fire. Every one is optional. */
+export interface DragHandlers {
+    /**
+     * Fired once the drag is recognized — immediately on pointer-down when `threshold` is `0`, otherwise on the
+     * first move that clears it.
+     */
+    readonly onDragStart?: (payload: DragPayload) => void;
+    /** Fired on each subsequent pointer move while the drag is active. */
+    readonly onDragMove?: (payload: DragPayload) => void;
+    /**
+     * Fired on pointer-up or pointer-cancel, but ONLY if the drag was recognized — a press that never cleared the
+     * threshold produces no start and therefore no end. Read `event.type` to tell a completion from a cancellation.
+     */
+    readonly onDragEnd?: (payload: DragPayload) => void;
+}
+/** Tunes how a drag is recognized. */
+export interface DragOptions {
+    /**
+     * CSS pixels the pointer must travel before the drag is recognized. Defaults to `0` — recognized on
+     * pointer-down.
+     *
+     * Raise it to a few pixels whenever the same element is also clickable: below the threshold the interaction
+     * stays a press, so a click survives the hand tremor that accompanies every real tap.
+     */
+    readonly threshold?: number;
+    /** Axis the drag is locked to — gates recognition AND zeroes the off-axis delta. Defaults to `'both'`. */
+    readonly axis?: GestureAxis;
+    /**
+     * Whether the drag is inert. Checked when the pointer goes DOWN; a gesture already in flight completes normally
+     * rather than stranding a consumer mid-drag with no `onDragEnd`.
+     */
+    readonly disabled?: boolean;
+    /**
+     * Input devices allowed to drive the drag — conventionally `'mouse'`, `'touch'`, `'pen'`. Omit for no filter.
+     * An empty array accepts nothing, which is the literal reading and makes an accidentally-empty list obvious.
+     */
+    readonly pointerTypes?: readonly string[];
+}
+/**
+ * Tracks a single-pointer drag on `target`, reporting distance, position, and recent velocity.
+ *
+ * Takes the element as a ref or getter rather than handing one back, so the caller keeps ownership of its
+ * `useTemplateRef`. Options are read through `toValue` at call time, so a reactive `disabled` or `axis` takes
+ * effect without re-attaching the listener; only the element identity re-binds. When the scope is disposed every
+ * listener is detached and any held pointer capture released.
+ *
+ * Nothing throws: a missing element, an unavailable `setPointerCapture`, or a pointer that vanishes without an
+ * up event all resolve quietly.
+ *
+ * @param target The element to watch. A `null` value simply binds nothing.
+ * @param handlers Drag lifecycle callbacks.
+ * @param options Recognition tuning — threshold, axis, disabled, pointer-type filter.
+ */
+export declare function useDrag(target: MaybeRefOrGetter<HTMLElement | null | undefined>, handlers: DragHandlers, options?: MaybeRefOrGetter<DragOptions | undefined>): void;

package/dist/foundation/gestures/UseLongPress.d.ts

@@ -0,0 +1,42 @@
+import { MaybeRefOrGetter } from 'vue';
+/** What the long-press handler receives when the hold completes. */
+export interface LongPressPayload {
+    /** Where the press began — `clientX` of the pointer-down, not of the moment the timer elapsed. */
+    readonly x: number;
+    /** Where the press began — `clientY` of the pointer-down. */
+    readonly y: number;
+    /**
+     * The `pointerdown` event that opened the hold. There is no event for the completion itself: a timer fired, and
+     * inventing a synthetic one would misreport `timeStamp` and `target`.
+     */
+    readonly event: PointerEvent;
+}
+/** Tunes how a hold is recognized. */
+export interface LongPressOptions {
+    /**
+     * Hold duration in milliseconds before the handler fires. Defaults to `PressExtensions.longPressDelay.default`
+     * and is clamped into that same shared `[min, max]` range — this composable defines no bounds of its own.
+     */
+    readonly delayMs?: number;
+    /** CSS pixels the pointer may drift before the hold is abandoned. Defaults to `10`. */
+    readonly moveTolerance?: number;
+    /** Whether the gesture is inert. Checked when the pointer goes down. */
+    readonly disabled?: boolean;
+    /** Input devices allowed to drive the hold. Omit for no filter; an empty array accepts nothing. */
+    readonly pointerTypes?: readonly string[];
+}
+/**
+ * Fires `handler` after the pointer has been held on `target` for `delayMs` without drifting beyond
+ * `moveTolerance`.
+ *
+ * Cancels on pointer-up, on pointer-cancel, and on any move past the tolerance. The pending timer is cleared when
+ * the scope is disposed, so a component that disappears mid-hold can never fire into a dead tree.
+ *
+ * Takes the element as a ref or getter rather than handing one back. Options are read through `toValue` at call
+ * time, so a reactive `disabled` or `delayMs` takes effect without re-attaching. Nothing throws.
+ *
+ * @param target The element to watch.
+ * @param handler Called once when the hold completes.
+ * @param options Delay, move tolerance, disabled, pointer-type filter.
+ */
+export declare function useLongPress(target: MaybeRefOrGetter<HTMLElement | null | undefined>, handler: (payload: LongPressPayload) => void, options?: MaybeRefOrGetter<LongPressOptions | undefined>): void;

package/dist/foundation/gestures/UsePinch.d.ts

@@ -0,0 +1,47 @@
+import { MaybeRefOrGetter } from 'vue';
+import { GesturePoint } from './GestureMath';
+/** What a pinch handler receives — the gesture's state relative to where the pinch began. */
+export interface PinchPayload {
+    /** Separation now, over separation at pinch-start: `1` unchanged, `2` doubled, `0.5` halved. */
+    readonly scale: number;
+    /** Degrees turned since pinch-start, within `[-180, 180)`. Positive is clockwise on screen. */
+    readonly rotation: number;
+    /** Midpoint of the two active pointers, in viewport coordinates — the anchor to transform about. */
+    readonly center: GesturePoint;
+    /** The pointer event that produced this payload. */
+    readonly event: PointerEvent;
+}
+/** The callbacks a pinch can fire. All optional. */
+export interface PinchHandlers {
+    /** Fired when a second pointer goes down, with `scale: 1` and `rotation: 0` — the gesture's own origin. */
+    readonly onPinchStart?: (payload: PinchPayload) => void;
+    /** Fired when either pointer of the active pair moves. */
+    readonly onPinchMove?: (payload: PinchPayload) => void;
+    /** Fired when either pointer of the active pair lifts or cancels, carrying the last computed values. */
+    readonly onPinchEnd?: (payload: PinchPayload) => void;
+}
+/** Tunes how a pinch is recognized. */
+export interface PinchOptions {
+    /** Whether the gesture is inert. Checked when each pointer goes down. */
+    readonly disabled?: boolean;
+    /**
+     * Input devices allowed to drive the pinch — in practice `'touch'` or `'pen'`, since a mouse has one pointer.
+     * Omit for no filter; an empty array accepts nothing.
+     */
+    readonly pointerTypes?: readonly string[];
+}
+/**
+ * Tracks a two-pointer pinch on `target`, reporting scale, rotation, and the pinch centre.
+ *
+ * Ignored entirely while fewer than two pointers are down. Takes the element as a ref or getter rather than
+ * handing one back; options are read through `toValue` at call time. When the scope is disposed every listener is
+ * detached and every held pointer capture released. Nothing throws.
+ *
+ * Touch pinches need `touch-action: none` on the element, or the browser claims the pointers for page zoom and
+ * fires `pointercancel` mid-gesture.
+ *
+ * @param target The element to watch.
+ * @param handlers Pinch lifecycle callbacks.
+ * @param options Disabled flag and pointer-type filter.
+ */
+export declare function usePinch(target: MaybeRefOrGetter<HTMLElement | null | undefined>, handlers: PinchHandlers, options?: MaybeRefOrGetter<PinchOptions | undefined>): void;

package/dist/foundation/gestures/UseSwipe.d.ts

@@ -0,0 +1,46 @@
+import { MaybeRefOrGetter } from 'vue';
+import { GestureAxis } from './GestureAxis';
+import { SwipeDirection } from './SwipeDirection';
+/** What `onSwipe` receives once a flick is recognized. */
+export interface SwipePayload {
+    /** Which way the flick went, from the total displacement between press and release. */
+    readonly direction: SwipeDirection;
+    /** How far it travelled ALONG that direction's axis, in CSS pixels. Always positive. */
+    readonly distance: number;
+    /** Release speed along that same axis, in px/ms, over the recent movement window. Always positive. */
+    readonly velocity: number;
+    /** The pointer event that ended the gesture — `pointerup`, or `pointercancel` if the browser took the pointer. */
+    readonly event: PointerEvent;
+}
+/** The callbacks a swipe can fire. */
+export interface SwipeHandlers {
+    /** Fired once per gesture, at release, only when both the distance and velocity thresholds are met. */
+    readonly onSwipe?: (payload: SwipePayload) => void;
+}
+/** Tunes how a flick is recognized. */
+export interface SwipeOptions {
+    /** CSS pixels the pointer must travel along the swipe axis. Defaults to `50`. */
+    readonly threshold?: number;
+    /** Speed in px/ms the pointer must still carry at release. Defaults to `0.3` (300 px/s). */
+    readonly velocityThreshold?: number;
+    /**
+     * Axis to restrict recognition to. `'x'` reports only `'left'` / `'right'`, `'y'` only `'up'` / `'down'`.
+     * Defaults to `'both'`.
+     */
+    readonly axis?: GestureAxis;
+    /** Whether the gesture is inert. Checked when the pointer goes down. */
+    readonly disabled?: boolean;
+    /** Input devices allowed to drive the swipe. Omit for no filter; see {@link useDrag} for the empty-array rule. */
+    readonly pointerTypes?: readonly string[];
+}
+/**
+ * Recognizes a directional flick on `target`.
+ *
+ * Built on {@link useDrag}, so it inherits pointer capture, the pointer-type filter, and the same cleanup
+ * guarantees: on scope disposal every listener is detached and any capture released. Nothing throws.
+ *
+ * @param target The element to watch, as a ref or getter.
+ * @param handlers Swipe callbacks.
+ * @param options Distance / velocity thresholds, axis, disabled, pointer-type filter.
+ */
+export declare function useSwipe(target: MaybeRefOrGetter<HTMLElement | null | undefined>, handlers: SwipeHandlers, options?: MaybeRefOrGetter<SwipeOptions | undefined>): void;

package/dist/foundation/gestures/index.d.ts

@@ -0,0 +1,7 @@
+export { SwipeDirection } from './SwipeDirection';
+export { GestureAxis } from './GestureAxis';
+export { type GesturePoint, type GestureSample, gestureVelocity, windowedVelocity, swipeDirection, pointerDistance, pointerAngle, pointerCenter, pinchScale, pinchRotation, normalizeAngle, constrainToAxis, exceedsThreshold, withinTolerance, acceptsPointerType, clampLongPressDelay, } from './GestureMath';
+export { useDrag, type DragPayload, type DragHandlers, type DragOptions } from './UseDrag';
+export { useSwipe, type SwipePayload, type SwipeHandlers, type SwipeOptions } from './UseSwipe';
+export { useLongPress, type LongPressPayload, type LongPressOptions } from './UseLongPress';
+export { usePinch, type PinchPayload, type PinchHandlers, type PinchOptions } from './UsePinch';