npm - @wow-two-beta/ui-vue - Versions diffs - 0.0.5 → 0.0.6 - Mend

@wow-two-beta/ui-vue 0.0.5 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2101) hide show

package/dist/foundation/geolocation/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sources":["../../../src/foundation/geolocation/Coordinates.ts","../../../src/foundation/geolocation/CanLocate.ts","../../../src/foundation/geolocation/PositionResult.ts","../../../src/foundation/geolocation/GetCurrentPosition.ts","../../../src/foundation/geolocation/WatchPosition.ts","../../../src/foundation/geolocation/GeolocationPermission.ts","../../../src/foundation/geolocation/DistanceBetween.ts","../../../src/foundation/geolocation/GeolocationReading.ts","../../../src/foundation/geolocation/UseGeolocation.ts","../../../src/foundation/geolocation/UseWatchPosition.ts"],"sourcesContent":["// The boundary type of the geolocation vector: a flat, plain, structurally-cloneable snapshot of one fix.\n//\n// WHY NOT PASS `GeolocationPosition` THROUGH. The object the platform hands the success callback is a HOST\n// object, and every awkward property of one applies:\n// - it is not structurally cloneable in a useful way and does not survive `JSON.stringify` — its data sits on\n// accessors on the prototype, so a naive clone or serialize yields `{}`. Storing it in reactive state and then\n// persisting that state (localStorage, an IndexedDB cache, a `postMessage` to a worker) silently loses the\n// coordinates;\n// - it is LIVE in some engines — the same `coords` object mutated in place on the next fix — so a consumer\n// holding two \"different\" readings can find they compare equal;\n// - nesting (`position.coords.latitude`) forces every consumer and every assertion through two hops for data\n// that has exactly one shape.\n// So the conversion happens once, here, at the boundary: the platform object never leaves this slice, and what\n// a consumer holds is an ordinary frozen-in-time record of numbers.\n//\n// FLAT, NOT NESTED. `Position` is `Coordinates` plus `timestamp` rather than `{ coords, timestamp }`. There is\n// no second coordinate set to disambiguate, and flattening makes both the consumer's read and the test's\n// `toEqual` a single level.\n//\n// `number \| null`, NOT `number \| undefined`, for the optional channels. That is what the platform reports for a\n// device with no altimeter or no heading, `null` survives `structuredClone` and `JSON` round-trips unchanged\n// (an optional property carrying `undefined` does not — it disappears), and it keeps \"the platform answered,\n// with nothing\" distinct from \"the key was never set\".\n//\n// HOSTILE READS. Every property here is read off an object this module did not create, through guarded reads:\n// a host accessor can throw, and a test double or a polyfill can supply anything at all. An unreadable required\n// field yields `null` from {@link toPosition} — a defined answer the caller turns into a `failed` result —\n// rather than an exception escaping a platform callback, where nothing can catch it.\n\n/** The minimum a point needs to be positioned on a sphere — the input {@link distanceBetween} accepts. /\nexport interface LatLng {\n /* Degrees north of the equator, negative for south. /\n readonly latitude: number;\n\n /* Degrees east of the prime meridian, negative for west. /\n readonly longitude: number;\n}\n\n/* One fix's spatial data, flattened out of the platform's `GeolocationCoordinates`. /\nexport interface Coordinates extends LatLng {\n /* Radius of the 95%-confidence circle around the position, in metres. Always present; never negative. /\n readonly accuracy: number;\n\n /* Metres above the WGS-84 ellipsoid, or `null` where the device cannot measure altitude. /\n readonly altitude: number \| null;\n\n /* Confidence interval on {@link Coordinates.altitude}, in metres, or `null` when altitude is `null`. /\n readonly altitudeAccuracy: number \| null;\n\n /* Direction of travel in degrees clockwise from true north, or `null` when stationary or unmeasurable. /\n readonly heading: number \| null;\n\n /* Ground speed in metres per second, or `null` where the device cannot measure it. /\n readonly speed: number \| null;\n}\n\n/* A complete fix: where the device was, and when. The value every entry point in this slice hands back. /\nexport interface Position extends Coordinates {\n /* Milliseconds since the epoch at which the fix was taken — same base as `Date.now()`. /\n readonly timestamp: number;\n}\n\n/\n Reads one numeric field off an object of unknown provenance. Returns `null` for a missing field, a\n * non-numeric one, `NaN`/`Infinity`, or an accessor that throws — all of which mean the same thing to the\n * caller: no usable number here.\n /\nfunction readFiniteNumber(source: object, key: string): number \| null {\n try {\n const value: unknown = (source as Record<string, unknown>)[key];\n return typeof value === 'number' && Number.isFinite(value) ? value : null;\n } catch {\n return null;\n }\n}\n\n/* Reads a nested object field, guarded the same way. Returns `null` when it is absent or not an object. /\nfunction readObject(source: object, key: string): object \| null {\n try {\n const value: unknown = (source as Record<string, unknown>)[key];\n return typeof value === 'object' && value !== null ? value : null;\n } catch {\n return null;\n }\n}\n\n/\n Converts the platform's position object into a plain {@link Position}, or `null` when it carries no usable\n * fix. Exported for the sibling modules that own the platform callbacks; absent from the barrel, where a\n * consumer only ever meets the converted form.\n \n `latitude`, `longitude` and `accuracy` are load-bearing: without all three there is no position to report, so\n * an unreadable one collapses the whole reading to `null`. The optional channels degrade individually to\n * `null`. A missing or unreadable `timestamp` falls back to `Date.now()` — the read is happening now, and a fix\n * without a time is harder to use than one with an approximate one.\n \n Never throws.\n \n @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.\n * @returns The plain snapshot, or `null` if no fix could be read out of it.\n /\nexport function toPosition(raw: unknown): Position \| null {\n if (typeof raw !== 'object' \|\| raw === null) return null;\n\n const coords = readObject(raw, 'coords');\n if (coords === null) return null;\n\n const latitude = readFiniteNumber(coords, 'latitude');\n const longitude = readFiniteNumber(coords, 'longitude');\n const accuracy = readFiniteNumber(coords, 'accuracy');\n if (latitude === null \|\| longitude === null \|\| accuracy === null) return null;\n\n return {\n latitude,\n longitude,\n accuracy,\n altitude: readFiniteNumber(coords, 'altitude'),\n altitudeAccuracy: readFiniteNumber(coords, 'altitudeAccuracy'),\n heading: readFiniteNumber(coords, 'heading'),\n speed: readFiniteNumber(coords, 'speed'),\n timestamp: readFiniteNumber(raw, 'timestamp') ?? Date.now(),\n };\n}\n","// Capability detection for the Geolocation API — the one guard every other module in this slice runs first.\n//\n// Three absences collapse to the same answer, and all three are ordinary rather than exceptional:\n// - no `navigator` at all — SSR, or a worker without one;\n// - `navigator` present but no `geolocation` — a stripped embedded webview, a privacy build, a test double;\n// - `geolocation` present but not actually callable — a partial polyfill, a `Proxy` stand-in.\n// Each is checked by shape rather than by trusting the type declarations, because at runtime the DOM lib's\n// promise that `navigator.geolocation` exists is only a promise.\n//\n// The whole probe sits in a `try`: on a hardened page `navigator` can be a `Proxy` whose `get` trap throws, and\n// a capability probe that throws would defeat its own purpose.\n//\n// NOT DETECTED HERE: whether geolocation is permitted. A secure-context violation, a `Permissions-Policy` block\n// and a user denial all leave the API present and callable — they surface as a `denied` / `failed` RESULT from\n// the call, not as a missing capability. `canLocate()` answers \"is there an API to ask\", never \"will it work\".\n\n/\n Returns `navigator.geolocation` when it is present and callable, `undefined` otherwise. Exported for the\n * sibling modules, which need the object itself; absent from the barrel, where {@link canLocate} is the boolean\n * a consumer wants.\n \n Never throws.\n /\nexport function geolocationApi(): Geolocation \| undefined {\n try {\n if (typeof navigator === 'undefined') return undefined;\n\n const geolocation: unknown = navigator.geolocation;\n if (typeof geolocation !== 'object' \|\| geolocation === null) return undefined;\n if (typeof (geolocation as Geolocation).getCurrentPosition !== 'function') return undefined;\n\n return geolocation as Geolocation;\n } catch {\n return undefined;\n }\n}\n\n/\n Whether this environment exposes a usable Geolocation API.\n \n Use it to decide whether to render a \"Use my location\" affordance at all. It does NOT predict success: the\n * API can be present and still answer `denied` (user or policy) or `unavailable` (no fix). Treat a `false` as\n * \"hide the feature\" and the call's own result as \"what happened\".\n \n Never throws. Returns `false` under SSR.\n /\nexport function canLocate(): boolean {\n return geolocationApi() !== undefined;\n}\n","// The shared vocabulary of a position request: what goes in (options), what comes back (a discriminated\n// result), and the translation of the platform's error object into it. Both entry points — the one-shot\n// `getCurrentPosition` and the streaming `watchPosition` — speak exactly this, so a consumer writes ONE switch\n// and reuses it for both.\n//\n// THE CODE MAPPING IS THE POINT OF THIS MODULE. `GeolocationPositionError` reports failure as a bare integer,\n// and the three values mean things a UI must treat completely differently:\n// 1 PERMISSION_DENIED → the user (or a `Permissions-Policy` header) said no. Asking again does nothing\n// until they change it in browser settings — so the UI must stop asking and explain.\n// 2 POSITION_UNAVAILABLE → the request was allowed but no fix came back: indoors, no GPS, radio off. This one\n// IS worth retrying, and is the single most common failure in the wild.\n// 3 TIMEOUT → allowed, still trying, ran out of `timeout` ms. Retryable, and a hint that the\n// budget was too tight for a cold GPS fix.\n// Collapsing them into one \"location error\" is what the module exists to prevent: it produces UIs that tell a\n// user in a basement to check their browser permissions.\n//\n// The codes are compared as NUMERIC LITERALS, not as `GeolocationPositionError.PERMISSION_DENIED`. The named\n// constants live on the platform's own constructor, which does not exist under SSR and does not exist on the\n// plain `{ code: 1 }` object a test double or a Cordova-era polyfill throws. The integers are frozen by the W3C\n// spec and are the only part of the error that is reliably there.\n//\n// A code outside 1–3 (including a missing or unreadable one) is NOT silently bucketed into `unavailable`: it\n// becomes `failed` carrying a normalized `Error`, so a future spec addition or a broken polyfill surfaces as\n// something a consumer can log rather than as a plausible-looking lie.\n\nimport { toError } from '../errors';\n\nimport { toPosition, type Position } from './Coordinates';\n\n/* `GeolocationPositionError.PERMISSION_DENIED` — the user or a policy refused. /\nconst PermissionDeniedCode = 1;\n\n/* `GeolocationPositionError.POSITION_UNAVAILABLE` — allowed, but no fix could be acquired. /\nconst PositionUnavailableCode = 2;\n\n/* `GeolocationPositionError.TIMEOUT` — allowed, but the fix did not arrive inside the timeout budget. /\nconst TimeoutCode = 3;\n\n/* The message on the `Error` reported when the platform hands back a position nothing can be read out of. /\nexport const UnreadablePositionMessage = 'Geolocation reported a position with no readable coordinates.';\n\n/\n The outcome of a position request — one-shot or one emission of a watch.\n \n - `ok` — a fix, as a plain {@link Position} snapshot.\n * - `denied` — code 1. Permanent for this origin until the user changes it; do not re-prompt.\n * - `unavailable` — code 2. Transient; retry is reasonable.\n * - `timeout` — code 3. Transient; retry, possibly with a larger `timeout`.\n * - `unsupported` — no Geolocation API here (SSR, stripped webview). Not a failure; a capability answer.\n * - `failed` — anything else, carrying the normalized `Error`: an unrecognized code, an unreadable position, or\n * a platform call that threw.\n /\nexport type PositionResult =\n \| { readonly status: 'ok'; readonly position: Position }\n \| { readonly status: 'denied' }\n \| { readonly status: 'unavailable' }\n \| { readonly status: 'timeout' }\n \| { readonly status: 'unsupported' }\n \| { readonly status: 'failed'; readonly error: Error };\n\n/* The `status` discriminant of a {@link PositionResult} — for a consumer's own switch or status→copy map. /\nexport type PositionStatus = PositionResult['status'];\n\n/\n Tunes a position request. Mirrors the platform's `PositionOptions`, restated here so the public API of this\n * slice owns its own input type and can document what each field actually costs.\n /\nexport interface PositionRequestOptions {\n /\n Asks for the most accurate fix the device can give — GPS rather than wifi/cell triangulation. Slower to\n * acquire and materially more battery-hungry; leave it off unless the accuracy genuinely changes the UI.\n /\n readonly enableHighAccuracy?: boolean;\n\n /\n Milliseconds to wait for a fix before answering `timeout`. Unset means wait indefinitely — which is why a\n * request with no timeout can leave a UI spinning forever indoors. A cold GPS fix can need 10–30s.\n /\n readonly timeout?: number;\n\n /\n Milliseconds a cached fix may be old and still be handed back instantly. `0` (the platform default) forces\n * a fresh acquisition every time; a few seconds is usually a better trade for a UI that asks repeatedly.\n /\n readonly maximumAge?: number;\n}\n\n/\n Reads the numeric `code` off a value of unknown provenance. Returns `null` for a missing or non-numeric code\n * and for an accessor that throws — a platform error object is read inside a callback, where an exception\n * cannot be caught by the original caller.\n /\nfunction readErrorCode(raw: unknown): number \| null {\n if (typeof raw !== 'object' \|\| raw === null) return null;\n try {\n const code: unknown = (raw as Record<string, unknown>).code;\n return typeof code === 'number' ? code : null;\n } catch {\n return null;\n }\n}\n\n/\n Translates a value from a geolocation error callback into its {@link PositionResult}. Exported for the two\n * sibling entry points; absent from the barrel.\n \n Never throws — a hostile error object degrades to `failed`, never to an exception thrown inside a platform\n * callback.\n \n @param raw The value handed to a `getCurrentPosition` / `watchPosition` error callback.\n /\nexport function toPositionResult(raw: unknown): PositionResult {\n switch (readErrorCode(raw)) {\n case PermissionDeniedCode:\n return { status: 'denied' };\n case PositionUnavailableCode:\n return { status: 'unavailable' };\n case TimeoutCode:\n return { status: 'timeout' };\n default:\n return { status: 'failed', error: toError(raw) };\n }\n}\n\n/\n Translates a value from a geolocation success callback into its {@link PositionResult}, converting the host\n * object into a plain snapshot on the way. Exported for the two sibling entry points; absent from the barrel.\n \n A success callback that carries nothing readable becomes `failed` rather than `ok` with a hollow position —\n * a consumer must never receive a `status: 'ok'` it cannot plot.\n \n Never throws.\n \n @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.\n /\nexport function toPositionSuccess(raw: unknown): PositionResult {\n const position = toPosition(raw);\n if (position === null) return { status: 'failed', error: new Error(UnreadablePositionMessage) };\n return { status: 'ok', position };\n}\n","// The one-shot read: `navigator.geolocation.getCurrentPosition` turned from a two-callback platform call into\n// an awaitable that resolves to a typed result.\n//\n// DEFINING CONTRACT: NOTHING HERE THROWS, and the returned promise never rejects. This is called straight from\n// a click handler, where a rejection nobody caught is an unhandled error and the user sees nothing happen at\n// all. Missing API, denial, no fix, timeout, an unreadable position, even a platform call that throws\n// synchronously — every path resolves to a `PositionResult` the caller switches on.\n//\n// SETTLE-ONCE. A promise executor can only settle once, but the platform hands us two callbacks and there is no\n// contract we control that says exactly one of them fires. A partial polyfill firing both — or a watch-style\n// implementation calling success repeatedly — would make every call after the first a silent no-op that is\n// invisible in a debugger. The explicit `settled` flag makes \"first answer wins\" a stated rule rather than a\n// side effect of how promises happen to work.\n//\n// NO TIMEOUT IS ADDED HERE. With no `timeout` option the platform waits indefinitely, and this module does not\n// impose a default: silently answering `timeout` at some invented deadline while the real request is still\n// running would report a failure the platform never had. A caller that needs a bound passes one — see\n// `PositionRequestOptions.timeout`, which documents why it usually should.\n\nimport { toError } from '../errors';\n\nimport { geolocationApi } from './CanLocate';\nimport { toPositionResult, toPositionSuccess, type PositionRequestOptions, type PositionResult } from './PositionResult';\n\n/\n Reads the device's current position once.\n \n The first call from an origin triggers the browser's permission prompt, so call it from a user gesture: a\n * prompt with no visible cause is the one users reflexively dismiss, and a dismissal is a `denied` that sticks.\n \n Never throws, never rejects — every outcome, including the absence of the API, arrives as a\n * {@link PositionResult}.\n \n @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.\n * @returns The outcome: a fix, a typed refusal (`denied` / `unavailable` / `timeout`), `unsupported`, or `failed`.\n /\nexport function getCurrentPosition(options?: PositionRequestOptions): Promise<PositionResult> {\n const api = geolocationApi();\n if (api === undefined) return Promise.resolve({ status: 'unsupported' });\n\n return new Promise<PositionResult>((resolve) => {\n let settled = false;\n\n /* Resolves with the first answer and ignores every later one. See the header. /\n const settle = (result: PositionResult): void => {\n if (settled) return;\n settled = true;\n resolve(result);\n };\n\n try {\n api.getCurrentPosition(\n (raw) => settle(toPositionSuccess(raw)),\n (error) => settle(toPositionResult(error)),\n options,\n );\n } catch (error) {\n // A synchronous throw from the platform call itself — an insecure context on some engines, a stand-in\n // with the wrong arity. The API was present, so this is `failed`, not `unsupported`.\n settle({ status: 'failed', error: toError(error) });\n }\n });\n}\n","// The streaming read: a continuous subscription to the device's position, handed back as a disposer.\n//\n// A FORGOTTEN WATCH IS A BATTERY BUG, and the worst kind — invisible in every metric a web app has. `watchId`\n// registrations are owned by the browser, not by the page's component tree: they outlive the component that\n// started them, they are not garbage-collected when the last reference to the handler is dropped, and a\n// high-accuracy watch holds the GPS radio ACTIVE for as long as it lives. A single watch started in an effect\n// with no cleanup keeps draining after the user has navigated away from the screen that wanted it, and a\n// remount starts a second one on top. Hence the shape: this returns a disposer, not an id — there is no way to\n// call it and be handed something you can forget to clean up without noticing you were handed it.\n//\n// The disposer is IDEMPOTENT. Browsers recycle watch ids, so a second `clearWatch(id)` after the id has been\n// reissued would cancel an unrelated watch belonging to some other part of the app. The `disposed` flag makes\n// double-dispose (a watcher re-run that cleans up twice, a defensive `finally`) a no-op instead of sabotage.\n//\n// EMISSIONS AFTER DISPOSE ARE DROPPED. `clearWatch` stops future acquisitions but does not un-queue a callback\n// the platform has already scheduled, so a late fix can arrive after the consumer has torn down. The same flag\n// gates the handler.\n//\n// Every emission is the same `PositionResult` union `getCurrentPosition` resolves to — including `unsupported`,\n// emitted once and synchronously where there is no API, so a subscriber always hears exactly one answer rather\n// than waiting forever for a fix that cannot come. A throwing handler is swallowed: a consumer's broken render\n// must not kill the subscription or throw inside a platform callback.\n\nimport { toError } from '../errors';\n\nimport { geolocationApi } from './CanLocate';\nimport { toPositionResult, toPositionSuccess, type PositionRequestOptions, type PositionResult } from './PositionResult';\n\n/* Receives every emission of a watch — a new fix, or a failure. Called with the same union as a one-shot read. /\nexport type PositionHandler = (result: PositionResult) => void;\n\n/\n Subscribes to the device's position and calls `handler` on every fix and every failure.\n \n Unlike {@link getCurrentPosition}, a watch does not end: it keeps reporting until disposed, which is why the\n * return value is the disposer. Always call it — in a watcher's `onCleanup`, on route change, when the\n * feature is toggled off. A live watch holds the location hardware on.\n \n Emits `unsupported` once, synchronously, where there is no Geolocation API, then never again.\n \n Never throws — neither this call nor any emission.\n \n @param handler Called with each {@link PositionResult}. A throw from it is swallowed.\n * @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.\n * @returns The disposer. Idempotent; safe to call more than once and after emissions have stopped.\n /\nexport function watchPosition(handler: PositionHandler, options?: PositionRequestOptions): () => void {\n let disposed = false;\n let watchId: number \| undefined;\n\n /* Hands the subscriber a result, absorbing a throw from their own handler and ignoring post-dispose noise. /\n const emit = (result: PositionResult): void => {\n if (disposed) return;\n try {\n handler(result);\n } catch {\n // The subscriber's handler failed. Their problem, and not a reason to break the subscription or to let an\n // exception escape into a platform callback, where nothing can catch it.\n }\n };\n\n const api = geolocationApi();\n if (api === undefined \|\| typeof api.watchPosition !== 'function') {\n emit({ status: 'unsupported' });\n return () => {\n disposed = true;\n };\n }\n\n try {\n const id: unknown = api.watchPosition(\n (raw) => emit(toPositionSuccess(raw)),\n (error) => emit(toPositionResult(error)),\n options,\n );\n // A spec-conformant implementation returns a number. Anything else is kept out of `watchId` so the disposer\n // never hands `clearWatch` a value it cannot act on.\n if (typeof id === 'number') watchId = id;\n } catch (error) {\n emit({ status: 'failed', error: toError(error) });\n }\n\n return () => {\n if (disposed) return;\n disposed = true;\n\n if (watchId === undefined) return;\n const id = watchId;\n // Cleared before the call, so a throwing `clearWatch` cannot leave the disposer able to fire it twice.\n watchId = undefined;\n\n try {\n if (typeof api.clearWatch === 'function') api.clearWatch(id);\n } catch {\n // A stand-in without a working `clearWatch`. Nothing further to do — the flag already stopped emissions.\n }\n };\n}\n","// The permission read — deliberately a one-line delegation, not an implementation.\n//\n// `foundation/notifications` already owns the `navigator.permissions.query` wrapper, and it was written\n// generically precisely so this slice would not need a second one: it already handles the API being absent\n// (SSR, older Safari), Safari throwing synchronously for a name it does not implement, and an off-spec state\n// string — all collapsing to `unsupported`. Re-implementing that here would give the ecosystem two wrappers\n// that drift apart, and a `geolocation` permission read that behaves subtly differently from a `notifications`\n// one for no reason a consumer could predict.\n//\n// Its home in `notifications` is historical, not semantic: notifications are the one permission needing BOTH\n// the Permissions API and a second, notification-specific source, so the generic wrapper was written there\n// first. Nothing about it is notification-specific — its own header says so.\n//\n// THIS IS A READ, NOT A REQUEST. Geolocation has no `requestPermission()`; the only way to raise the prompt is\n// to ask for a position. So the flow is: `getGeolocationPermission()` to decide what to render (`prompt` → show\n// the button, `denied` → show the \"enable it in settings\" copy), then `getCurrentPosition()` to actually ask.\n//\n// `unsupported` is not `prompt`. Where the Permissions API is missing, the grant is simply unknown — and a\n// consumer must not read \"we could not tell\" as \"the user has not been asked yet\". Geolocation itself may well\n// be present and working there; `canLocate()` is the capability question, this is the grant question.\n\nimport { queryPermission, type PermissionQueryState } from '../notifications';\n\nexport type { PermissionQueryState };\n\n/\n Reads the current geolocation grant without prompting for it.\n \n A snapshot — the returned promise fires no event on a later change. Use `usePermissionState('geolocation')`\n * from `foundation/notifications` to follow changes (a revoke from site settings, a grant given in another tab).\n \n Never throws, never rejects.\n \n @returns `granted` / `denied` / `prompt`, or `unsupported` where the Permissions API cannot answer.\n /\nexport function getGeolocationPermission(): Promise<PermissionQueryState> {\n return queryPermission('geolocation');\n}\n","// Great-circle distance between two points — the one piece of this slice with no platform dependency at all.\n//\n// WHY HAVERSINE. It is the standard trade for UI distance: exact on a sphere, ~0.5% worst-case error against\n// the real ellipsoid (Vincenty's inverse formula closes that gap at maybe 40× the code and an iterative solve\n// that can fail to converge on near-antipodal pairs). For \"2.3 km away\" on a card, 0.5% is 11 metres. It is\n// also numerically well-behaved for SMALL separations, which is the case a UI actually hits — the older\n// spherical law of cosines is algebraically equivalent but loses catastrophic precision under ~1 km, where\n// `acos` of a value that has rounded to exactly 1 collapses to 0.\n//\n// THE ANTIMERIDIAN IS HANDLED BY THE FORMULA, NOT BY A SPECIAL CASE. The longitude term is `sin²(Δλ/2)`, and\n// sin² is periodic with period π in its argument — so a Δλ of 359° and one of −1° produce the identical term.\n// A pair straddling the 180th meridian therefore comes out as the ~111 km it really is, with no normalization,\n// no `Δλ > 180 → Δλ − 360` correction, and no branch to get wrong. Anything computed on raw degree deltas\n// (`Math.abs(b.longitude - a.longitude) 111_000`, the naive Euclidean version) reports ~39,900 km for that\n// same pair. This is the reason the module exists rather than a one-line helper per consumer.\n//\n// `atan2(√a, √(1−a))` rather than `asin(√a)`: identical for small `a`, but numerically stable for\n// near-antipodal points where `a` approaches 1 and `asin`'s derivative goes to infinity.\n//\n// RADIUS. 6,371,008.8 m — the IUGG mean radius (R₁) of the WGS-84 ellipsoid, the same constant every mapping\n// library uses. The Earth is not a sphere, so the choice of a single radius, not the formula, is the dominant\n// error term: 6,371,000 vs 6,378,137 (equatorial) shifts every result by ~0.1%.\n//\n// NEVER THROWS. Non-finite input yields `NaN` — a value that propagates visibly and compares false against\n// every threshold — rather than an exception or a plausible-looking wrong number.\n\nimport type { LatLng } from './Coordinates';\n\n/** IUGG mean Earth radius (R₁), in metres. The sphere the haversine result is measured on. /\nexport const EarthRadiusMetres = 6_371_008.8;\n\n/* Degrees → radians. /\nconst DegreesToRadians = Math.PI / 180;\n\n/* Whether all four coordinate components are real numbers this can compute on. /\nfunction isMeasurable(a: LatLng, b: LatLng): boolean {\n return (\n Number.isFinite(a.latitude) &&\n Number.isFinite(a.longitude) &&\n Number.isFinite(b.latitude) &&\n Number.isFinite(b.longitude)\n );\n}\n\n/\n Great-circle (\"as the crow flies\") distance between two points, in metres.\n \n Pure and symmetric — `distanceBetween(a, b) === distanceBetween(b, a)` — and exactly `0` for identical\n * points. Correct across the antimeridian and the poles without any special-casing by the caller. Accepts\n * anything with `latitude` / `longitude`, so a {@link Position} from this slice can be passed directly.\n \n Not road distance and not ellipsoidal: ~0.5% worst case against a geodesic solution, dominated by the\n * spherical-Earth assumption rather than by the formula. Fine for proximity, sorting, and radius filters; not\n * for surveying.\n \n Never throws. Returns `NaN` if any component is `NaN`, `Infinity`, or otherwise not a finite number.\n \n @param a One endpoint.\n * @param b The other endpoint.\n * @returns Metres along the great circle, or `NaN` for unmeasurable input.\n /\nexport function distanceBetween(a: LatLng, b: LatLng): number {\n if (!isMeasurable(a, b)) return Number.NaN;\n\n const latitudeA = a.latitude DegreesToRadians;\n const latitudeB = b.latitude * DegreesToRadians;\n const halfLatitudeDelta = ((b.latitude - a.latitude) * DegreesToRadians) / 2;\n const halfLongitudeDelta = ((b.longitude - a.longitude) * DegreesToRadians) / 2;\n\n const chord =\n Math.sin(halfLatitudeDelta) ** 2 +\n Math.cos(latitudeA) * Math.cos(latitudeB) * Math.sin(halfLongitudeDelta) ** 2;\n\n return 2 * EarthRadiusMetres * Math.atan2(Math.sqrt(chord), Math.sqrt(1 - chord));\n}\n","// The render-facing state shape of the vector, plus the pure reducer that folds a `PositionResult` into it.\n//\n// Kept OUT of the composable files, and free of Vue, for two reasons: both composables need exactly the same\n// fold (a one-shot request and a watch emission update state identically), and the interesting decisions below\n// are then testable without a renderer.\n//\n// TWO STATUSES THE PLATFORM DOES NOT HAVE. `idle` (never asked) and `locating` (asked, waiting) are states a UI\n// must render — an empty frame vs. a spinner — and neither is a `PositionResult`. Extending the result union\n// rather than adding a parallel `loading` boolean keeps the whole lifecycle in ONE switch, so no consumer can\n// render a \"no location\" empty state while a request is still in flight.\n//\n// A LATER FAILURE DOES NOT ERASE THE LAST FIX. `position` holds the most recent successful reading and survives\n// a subsequent `denied` / `timeout` / `unavailable`. A map that drops its pin the moment a watch misses one\n// update is worse than one showing a slightly stale position with a \"signal lost\" note — and the consumer can\n// always ignore `position` when `status !== 'ok'` if it wants the strict reading. `error` does the opposite: it\n// is cleared on every non-`failed` outcome, so a stale message can never outlive the failure it described.\n\nimport type { Position } from './Coordinates';\nimport type { PositionResult, PositionStatus } from './PositionResult';\n\n/*\n Where a geolocation consumer sits in its lifecycle: the platform's outcomes, plus the two states that exist\n * only in the UI — `idle` (nothing requested yet) and `locating` (a request is in flight).\n /\nexport type GeolocationState = 'idle' \| 'locating' \| PositionStatus;\n\n/* The state both {@link useGeolocation} and {@link useWatchPosition} expose. /\nexport interface GeolocationReading {\n /* The lifecycle state — drive the whole UI off this one switch. /\n readonly status: GeolocationState;\n\n /\n The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later\n * failure — check `status === 'ok'` when only a currently-valid reading will do.\n /\n readonly position: Position \| null;\n\n /* The error behind a `failed` status, or `null` for every other status. Never stale. /\n readonly error: Error \| null;\n}\n\n/* The starting state: nothing requested, nothing known. /\nexport const IdleGeolocationReading: GeolocationReading = {\n status: 'idle',\n position: null,\n error: null,\n};\n\n/\n Folds one {@link PositionResult} into the current reading. Pure; exported for the two composables and for tests,\n * absent from the barrel.\n \n @param previous The reading being updated — its `position` is what carries a past fix forward.\n * @param result The outcome to apply.\n * @returns The next reading.\n /\nexport function applyPositionResult(previous: GeolocationReading, result: PositionResult): GeolocationReading {\n return {\n status: result.status,\n position: result.status === 'ok' ? result.position : previous.position,\n error: result.status === 'failed' ? result.error : null,\n };\n}\n","// The Vue binding of the one-shot read — the position as reactive state, plus the one action that fetches it,\n// so a \"Use my location\" button is a `status` switch and a `request()` call rather than four refs re-declared\n// per consumer.\n//\n// NOTHING HAPPENS ON MOUNT, ON PURPOSE. This composable does not request a position when it mounts. The first\n// request raises the browser's permission prompt, and a prompt that appears on page load — with no visible\n// cause the user can connect it to — is the one users reflexively dismiss, which records a `denied` that sticks\n// for the origin and cannot be undone from script. So the request is always the consumer's explicit act,\n// ideally inside a click handler. Mount-time tracking is what `useWatchPosition` is for, and it is opt-in by\n// being a different composable. It is also why nothing here touches `navigator` at setup time: the SSR pass\n// runs this file, and only `request()` — which can only be called from the client — reaches the platform.\n//\n// STALE RESPONSES LOSE. A double-clicked button, or a re-request while a slow cold GPS fix is still resolving,\n// leaves two requests in flight. Without a guard the SLOWER one wins simply by finishing last, so a fresh\n// `denied` could be overwritten by a stale `ok` from before the user revoked. A monotonic token means only the\n// most recent request may write state; the earlier promise still resolves to its own result for whoever awaited\n// it, which keeps `request()`'s return value honest per call.\n//\n// Options are accepted as a ref or getter and read through `toValue` at call time, so a reactive source is\n// followed without the composable ever caching a stale copy — the Vue counterpart of the original's\n// options-in-a-ref indirection. A per-call argument overrides them, for the \"retry with a bigger timeout\" path.\n\nimport { computed, shallowRef, toValue, type ComputedRef, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport type { Position } from './Coordinates';\nimport { getCurrentPosition } from './GetCurrentPosition';\nimport {\n applyPositionResult,\n IdleGeolocationReading,\n type GeolocationReading,\n type GeolocationState,\n} from './GeolocationReading';\nimport type { PositionRequestOptions, PositionResult } from './PositionResult';\n\n/\n What {@link useGeolocation} returns — the reactive form of a {@link GeolocationReading} plus the action that\n * refreshes it.\n /\nexport interface GeolocationControls {\n /* The lifecycle state — drive the whole UI off this one switch. /\n readonly status: ComputedRef<GeolocationState>;\n\n /\n The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later\n * failure — check `status.value === 'ok'` when only a currently-valid reading will do.\n /\n readonly position: ComputedRef<Position \| null>;\n\n /* The error behind a `failed` status, or `null` for every other status. Never stale. /\n readonly error: ComputedRef<Error \| null>;\n\n /* Convenience for `status === 'locating'` — the flag a button's `disabled` / spinner wants. /\n readonly locating: ComputedRef<boolean>;\n\n /\n Requests a fix, writing the outcome to this composable's state and also resolving to it. Never throws,\n * never rejects. Call it from a user gesture — it is what raises the permission prompt.\n \n @param overrides Options for this call only, replacing the composable-level ones. Omit to use those.\n /\n readonly request: (overrides?: PositionRequestOptions) => Promise<PositionResult>;\n}\n\n/\n Exposes the device's position as reactive state, with a `request()` that fetches it on demand.\n \n Requests nothing on mount — see the header for why that is deliberate. Inherits the slice's never-throws\n * contract: `request` resolves to a {@link PositionResult}, never rejects.\n \n @param options Default tuning for every `request()` call. A ref or getter is read at call time, so the value\n * in effect is always the current one.\n /\nexport function useGeolocation(\n options?: MaybeRefOrGetter<PositionRequestOptions \| undefined>,\n): GeolocationControls {\n const reading: ShallowRef<GeolocationReading> = shallowRef(IdleGeolocationReading);\n\n /* Monotonic request token — only the newest request may write state. See the header. /\n let latestRequest = 0;\n\n const request = async (overrides?: PositionRequestOptions): Promise<PositionResult> => {\n latestRequest += 1;\n const token = latestRequest;\n\n reading.value = { ...reading.value, status: 'locating' };\n\n const result = await getCurrentPosition(overrides ?? toValue(options));\n\n if (token === latestRequest) reading.value = applyPositionResult(reading.value, result);\n return result;\n };\n\n return {\n status: computed(() => reading.value.status),\n position: computed(() => reading.value.position),\n error: computed(() => reading.value.error),\n locating: computed(() => reading.value.status === 'locating'),\n request,\n };\n}\n","// The Vue binding of the watch — position tracking bound to a scope's lifetime.\n//\n// THE CLEANUP IS THE WHOLE POINT. `watchPosition` returns a disposer precisely because a watch outlives the\n// code that started it, and this composable exists so that \"as long as this component is mounted\" is the\n// lifetime a consumer gets for free. The disposer is called from `onScopeDispose` and again before every\n// restart, so the watch is cleared on unmount and on every option change. A watch that survived unmount would\n// keep the GPS radio active for the rest of the session with nothing on screen referencing it — a battery\n// drain no page-level metric would ever attribute to this component.\n//\n// TRACKING STARTS ON MOUNT, unlike `useGeolocation`, which requests nothing until asked. That is the trade a\n// consumer makes by choosing this composable: mounting it may raise the permission prompt, so mount it on the\n// screen that actually shows a live position — behind the toggle, not above it.\n//\n// STARTED FROM `onMounted`, NEVER FROM AN IMMEDIATE WATCHER. `watchPosition` reads `navigator.geolocation`, and\n// an immediate watcher also runs during a server render, where that global does not exist. `onMounted` is\n// client-only by construction, so the SSR pass yields the idle reading and the watch begins at hydration.\n//\n// THE WATCHED SOURCE IS THE THREE OPTION VALUES, NOT THE OPTIONS OBJECT. Watching the object itself would\n// restart the watch on every change of identity for the overwhelmingly common `useWatchPosition({ timeout:\n// 5000 })` call site. Watching the primitives restarts only when a value genuinely changed, which is the\n// intended behaviour: a changed accuracy or timeout budget requires a new watch, since the platform has no way\n// to retune a live one.\n\nimport {\n onMounted,\n onScopeDispose,\n shallowRef,\n toValue,\n watch,\n type MaybeRefOrGetter,\n type ShallowRef,\n} from 'vue';\n\nimport { applyPositionResult, IdleGeolocationReading, type GeolocationReading } from './GeolocationReading';\nimport type { PositionRequestOptions } from './PositionResult';\nimport { watchPosition } from './WatchPosition';\n\n/\n Tracks the device's position for as long as the scope lives, clearing the watch when it is disposed.\n \n Starts on mount — see the header. Every fix and every failure arrives through the same\n * {@link GeolocationReading} shape `useGeolocation` exposes, minus the manual `request`; the last successful\n * fix survives a later failure, so a map keeps its pin when the signal drops.\n \n Inherits the slice's never-throws contract.\n \n @param options Accuracy / timeout / cache-age tuning. Changing any of the three values restarts the watch.\n * @returns The current reading. Holds {@link IdleGeolocationReading} during SSR and until mount.\n */\nexport function useWatchPosition(\n options?: MaybeRefOrGetter<PositionRequestOptions \| undefined>,\n): Readonly<ShallowRef<GeolocationReading>> {\n const reading: ShallowRef<GeolocationReading> = shallowRef(IdleGeolocationReading);\n\n let dispose: (() => void) \| undefined;\n\n function stop(): void {\n dispose?.();\n dispose = undefined;\n }\n\n function start(): void {\n stop();\n reading.value = { ...reading.value, status: 'locating' };\n\n const resolved = toValue(options);\n dispose = watchPosition(\n (result) => {\n reading.value = applyPositionResult(reading.value, result);\n },\n {\n enableHighAccuracy: resolved?.enableHighAccuracy,\n timeout: resolved?.timeout,\n maximumAge: resolved?.maximumAge,\n },\n );\n }\n\n onMounted(start);\n // Non-immediate on purpose: an immediate watcher runs on the server, where `navigator` is absent. Three\n // separate getters rather than one returning a tuple — Vue compares each source with `Object.is`, so an\n // options object of a fresh identity carrying the same three values does not restart the watch.\n watch(\n [\n () => toValue(options)?.enableHighAccuracy,\n () => toValue(options)?.timeout,\n () => toValue(options)?.maximumAge,\n ],\n start,\n );\n onScopeDispose(stop);\n\n return reading;\n}\n"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"index.js","sources":["../../../src/foundation/geolocation/models/Coordinates.ts","../../../src/foundation/geolocation/CanLocate.ts","../../../src/foundation/geolocation/PositionMapping.ts","../../../src/foundation/geolocation/GetCurrentPosition.ts","../../../src/foundation/geolocation/WatchPosition.ts","../../../src/foundation/geolocation/GeolocationPermission.ts","../../../src/foundation/geolocation/DistanceBetween.ts","../../../src/foundation/geolocation/models/GeolocationReading.ts","../../../src/foundation/geolocation/hooks/UseGeolocation.ts","../../../src/foundation/geolocation/hooks/UseWatchPosition.ts","../../../src/foundation/geolocation/PositionFailureCode.ts"],"sourcesContent":["/** The minimum a point needs to be positioned on a sphere — the input {@link distanceBetween} accepts. /\nexport interface LatLng {\n /* Degrees north of the equator, negative for south. /\n readonly latitude: number;\n\n /* Degrees east of the prime meridian, negative for west. /\n readonly longitude: number;\n}\n\n/* One fix's spatial data, flattened out of the platform's `GeolocationCoordinates`. /\nexport interface Coordinates extends LatLng {\n /* Radius of the 95%-confidence circle around the position, in metres. Always present; never negative. /\n readonly accuracy: number;\n\n /* Metres above the WGS-84 ellipsoid, or `null` where the device cannot measure altitude. /\n readonly altitude: number \| null;\n\n /* Confidence interval on {@link Coordinates.altitude}, in metres, or `null` when altitude is `null`. /\n readonly altitudeAccuracy: number \| null;\n\n /* Direction of travel in degrees clockwise from true north, or `null` when stationary or unmeasurable. /\n readonly heading: number \| null;\n\n /* Ground speed in metres per second, or `null` where the device cannot measure it. /\n readonly speed: number \| null;\n}\n\n/* A complete fix: where the device was, and when. The value every entry point in this slice hands back. /\nexport interface Position extends Coordinates {\n /* Milliseconds since the epoch at which the fix was taken — same base as `Date.now()`. /\n readonly timestamp: number;\n}\n\n/\n Reads one numeric field off an object of unknown provenance. Returns `null` for a missing field, a\n * non-numeric one, `NaN`/`Infinity`, or an accessor that throws — all of which mean the same thing to the\n * caller: no usable number here.\n /\nfunction readFiniteNumber(source: object, key: string): number \| null {\n try {\n const value: unknown = (source as Record<string, unknown>)[key];\n return typeof value === 'number' && Number.isFinite(value) ? value : null;\n } catch {\n return null;\n }\n}\n\n/* Reads a nested object field, guarded the same way. Returns `null` when it is absent or not an object. /\nfunction readObject(source: object, key: string): object \| null {\n try {\n const value: unknown = (source as Record<string, unknown>)[key];\n return typeof value === 'object' && value !== null ? value : null;\n } catch {\n return null;\n }\n}\n\n/\n Converts the platform's position object into a plain {@link Position}, or `null` when it carries no usable\n * fix. Exported for the sibling modules that own the platform callbacks; absent from the barrel, where a\n * consumer only ever meets the converted form.\n \n `latitude`, `longitude` and `accuracy` are load-bearing: without all three there is no position to report, so\n * an unreadable one collapses the whole reading to `null`. The optional channels degrade individually to\n * `null`. A missing or unreadable `timestamp` falls back to `Date.now()` — the read is happening now, and a fix\n * without a time is harder to use than one with an approximate one.\n \n Never throws.\n \n @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.\n * @returns The plain snapshot, or `null` if no fix could be read out of it.\n /\nexport function toPosition(raw: unknown): Position \| null {\n if (typeof raw !== 'object' \|\| raw === null) return null;\n\n const coords = readObject(raw, 'coords');\n if (coords === null) return null;\n\n const latitude = readFiniteNumber(coords, 'latitude');\n const longitude = readFiniteNumber(coords, 'longitude');\n const accuracy = readFiniteNumber(coords, 'accuracy');\n if (latitude === null \|\| longitude === null \|\| accuracy === null) return null;\n\n return {\n latitude,\n longitude,\n accuracy,\n altitude: readFiniteNumber(coords, 'altitude'),\n altitudeAccuracy: readFiniteNumber(coords, 'altitudeAccuracy'),\n heading: readFiniteNumber(coords, 'heading'),\n speed: readFiniteNumber(coords, 'speed'),\n timestamp: readFiniteNumber(raw, 'timestamp') ?? Date.now(),\n };\n}\n","/\n Returns `navigator.geolocation` when it is present and callable, `undefined` otherwise. Exported for the\n * sibling modules, which need the object itself; absent from the barrel, where {@link canLocate} is the boolean\n * a consumer wants.\n \n Never throws.\n /\nexport function geolocationApi(): Geolocation \| undefined {\n try {\n if (typeof navigator === 'undefined') return undefined;\n\n const geolocation: unknown = navigator.geolocation;\n if (typeof geolocation !== 'object' \|\| geolocation === null) return undefined;\n if (typeof (geolocation as Geolocation).getCurrentPosition !== 'function') return undefined;\n\n return geolocation as Geolocation;\n } catch {\n return undefined;\n }\n}\n\n/\n Whether this environment exposes a usable Geolocation API.\n \n Use it to decide whether to render a \"Use my location\" affordance at all. It does NOT predict success: the\n * API can be present and still answer `denied` (user or policy) or `unavailable` (no fix). Treat a `false` as\n * \"hide the feature\" and the call's own result as \"what happened\".\n \n Never throws. Returns `false` under SSR.\n /\nexport function canLocate(): boolean {\n return geolocationApi() !== undefined;\n}\n","import type { PositionReadResult } from './models/PositionReadResult';\nimport type { PositionFailure } from './models/PositionFailure';\n\nimport { toError } from '../errors';\n\nimport { toPosition } from './models/Coordinates';\n\n/* `GeolocationPositionError.PERMISSION_DENIED` — the user or a policy refused. /\nconst PermissionDeniedCode = 1;\n\n/* `GeolocationPositionError.POSITION_UNAVAILABLE` — allowed, but no fix could be acquired. /\nconst PositionUnavailableCode = 2;\n\n/* `GeolocationPositionError.TIMEOUT` — allowed, but the fix did not arrive inside the timeout budget. /\nconst TimeoutCode = 3;\n\n/* The message on the `Error` reported when the platform hands back a position nothing can be read out of. /\nexport const UnreadablePositionMessage = 'Geolocation reported a position with no readable coordinates.';\nexport type { PositionFailure } from './models/PositionFailure';\nexport type { PositionReadResult } from './models/PositionReadResult';\nexport type PositionStatus = 'ok' \| PositionFailure['status'];\n\n/\n Tunes a position request. Mirrors the platform's `PositionOptions`, restated here so the public API of this\n * slice owns its own input type and can document what each field actually costs.\n /\nexport interface PositionRequestOptions {\n /\n Asks for the most accurate fix the device can give — GPS rather than wifi/cell triangulation. Slower to\n * acquire and materially more battery-hungry; leave it off unless the accuracy genuinely changes the UI.\n /\n readonly enableHighAccuracy?: boolean;\n\n /\n Milliseconds to wait for a fix before answering `timeout`. Unset means wait indefinitely — which is why a\n * request with no timeout can leave a UI spinning forever indoors. A cold GPS fix can need 10–30s.\n /\n readonly timeout?: number;\n\n /\n Milliseconds a cached fix may be old and still be handed back instantly. `0` (the platform default) forces\n * a fresh acquisition every time; a few seconds is usually a better trade for a UI that asks repeatedly.\n /\n readonly maximumAge?: number;\n}\n\n/\n Reads the numeric `code` off a value of unknown provenance. Returns `null` for a missing or non-numeric code\n * and for an accessor that throws — a platform error object is read inside a callback, where an exception\n * cannot be caught by the original caller.\n /\nfunction readErrorCode(raw: unknown): number \| null {\n if (typeof raw !== 'object' \|\| raw === null) return null;\n try {\n const code: unknown = (raw as Record<string, unknown>).code;\n return typeof code === 'number' ? code : null;\n } catch {\n return null;\n }\n}\n\n/\n Translates a value from a geolocation error callback into its {@link PositionReadResult}. Exported for the two\n * sibling entry points; absent from the barrel.\n \n Never throws — a hostile error object degrades to `failed`, never to an exception thrown inside a platform\n * callback.\n \n @param raw The value handed to a `getCurrentPosition` / `watchPosition` error callback.\n /\nexport function toPositionResult(raw: unknown): PositionReadResult {\n switch (readErrorCode(raw)) {\n case PermissionDeniedCode:\n return { ok: false, failure: { status: 'denied' } };\n case PositionUnavailableCode:\n return { ok: false, failure: { status: 'unavailable' } };\n case TimeoutCode:\n return { ok: false, failure: { status: 'timeout' } };\n default:\n return { ok: false, failure: { status: 'failed', error: toError(raw) } };\n }\n}\n\n/\n Translates a value from a geolocation success callback into its {@link PositionReadResult}, converting the host\n * object into a plain snapshot on the way. Exported for the two sibling entry points; absent from the barrel.\n \n A success callback that carries nothing readable becomes `failed` rather than `ok` with a hollow position —\n * a consumer must never receive a `status: 'ok'` it cannot plot.\n \n Never throws.\n \n @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.\n /\nexport function toPositionSuccess(raw: unknown): PositionReadResult {\n const position = toPosition(raw);\n if (position === null)\n return { ok: false, failure: { status: 'failed', error: new Error(UnreadablePositionMessage) } };\n return { ok: true, value: position };\n}\n","import { toError } from '../errors';\n\nimport { geolocationApi } from './CanLocate';\nimport {\n toPositionResult,\n toPositionSuccess,\n type PositionRequestOptions,\n type PositionReadResult,\n} from './PositionMapping';\n\n/\n Reads the device's current position once.\n \n The first call from an origin triggers the browser's permission prompt, so call it from a user gesture: a\n * prompt with no visible cause is the one users reflexively dismiss, and a dismissal is a `denied` that sticks.\n \n Never throws, never rejects — every outcome, including the absence of the API, arrives as a\n * {@link PositionReadResult}.\n \n @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.\n * @returns The outcome: a fix, a typed refusal (`denied` / `unavailable` / `timeout`), `unsupported`, or `failed`.\n /\nexport function getCurrentPosition(options?: PositionRequestOptions): Promise<PositionReadResult> {\n const api = geolocationApi();\n if (api === undefined) return Promise.resolve({ ok: false, failure: { status: 'unsupported' } });\n\n return new Promise<PositionReadResult>((resolve) => {\n let settled = false;\n\n /* Resolves with the first answer and ignores every later one. See the header. /\n const settle = (result: PositionReadResult): void => {\n if (settled) return;\n settled = true;\n resolve(result);\n };\n\n try {\n api.getCurrentPosition(\n (raw) => settle(toPositionSuccess(raw)),\n (error) => settle(toPositionResult(error)),\n options,\n );\n } catch (error) {\n // A synchronous throw from the platform call itself — an insecure context on some engines, a stand-in\n // with the wrong arity. The API was present, so this is `failed`, not `unsupported`.\n settle({ ok: false, failure: { status: 'failed', error: toError(error) } });\n }\n });\n}\n","import { toError } from '../errors';\n\nimport { geolocationApi } from './CanLocate';\nimport {\n toPositionResult,\n toPositionSuccess,\n type PositionRequestOptions,\n type PositionReadResult,\n} from './PositionMapping';\n\n/* Receives every emission of a watch — a new fix, or a failure. Called with the same union as a one-shot read. /\nexport type PositionHandler = (result: PositionReadResult) => void;\n\n/\n Subscribes to the device's position and calls `handler` on every fix and every failure.\n \n Unlike {@link getCurrentPosition}, a watch does not end: it keeps reporting until disposed, which is why the\n * return value is the disposer. Always call it — in a watcher's `onCleanup`, on route change, when the\n * feature is toggled off. A live watch holds the location hardware on.\n \n Emits `unsupported` once, synchronously, where there is no Geolocation API, then never again.\n \n Never throws — neither this call nor any emission.\n \n @param handler Called with each {@link PositionReadResult}. A throw from it is swallowed.\n * @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.\n * @returns The disposer. Idempotent; safe to call more than once and after emissions have stopped.\n /\nexport function watchPosition(handler: PositionHandler, options?: PositionRequestOptions): () => void {\n let disposed = false;\n let watchId: number \| undefined;\n\n /* Hands the subscriber a result, absorbing a throw from their own handler and ignoring post-dispose noise. /\n const emit = (result: PositionReadResult): void => {\n if (disposed) return;\n try {\n handler(result);\n } catch {\n // The subscriber's handler failed. Their problem, and not a reason to break the subscription or to let an\n // exception escape into a platform callback, where nothing can catch it.\n }\n };\n\n const api = geolocationApi();\n if (api === undefined \|\| typeof api.watchPosition !== 'function') {\n emit({ ok: false, failure: { status: 'unsupported' } });\n return () => {\n disposed = true;\n };\n }\n\n try {\n const id: unknown = api.watchPosition(\n (raw) => emit(toPositionSuccess(raw)),\n (error) => emit(toPositionResult(error)),\n options,\n );\n // A spec-conformant implementation returns a number. Anything else is kept out of `watchId` so the disposer\n // never hands `clearWatch` a value it cannot act on.\n if (typeof id === 'number') watchId = id;\n } catch (error) {\n emit({ ok: false, failure: { status: 'failed', error: toError(error) } });\n }\n\n return () => {\n if (disposed) return;\n disposed = true;\n\n if (watchId === undefined) return;\n const id = watchId;\n // Cleared before the call, so a throwing `clearWatch` cannot leave the disposer able to fire it twice.\n watchId = undefined;\n\n try {\n if (typeof api.clearWatch === 'function') api.clearWatch(id);\n } catch {\n // A stand-in without a working `clearWatch`. Nothing further to do — the flag already stopped emissions.\n }\n };\n}\n","import { queryPermission, type PermissionQueryState } from '../notifications';\n\nexport type { PermissionQueryState };\n\n/\n Reads the current geolocation grant without prompting for it.\n \n A snapshot — the returned promise fires no event on a later change. Use `usePermissionState('geolocation')`\n * from `foundation/notifications` to follow changes (a revoke from site settings, a grant given in another tab).\n \n Never throws, never rejects.\n \n @returns `granted` / `denied` / `prompt`, or `unsupported` where the Permissions API cannot answer.\n /\nexport function getGeolocationPermission(): Promise<PermissionQueryState> {\n return queryPermission('geolocation');\n}\n","import type { LatLng } from './models/Coordinates';\n\n/* IUGG mean Earth radius (R₁), in metres. The sphere the haversine result is measured on. /\nexport const EarthRadiusMetres = 6_371_008.8;\n\n/* Degrees → radians. /\nconst DegreesToRadians = Math.PI / 180;\n\n/* Whether all four coordinate components are real numbers this can compute on. /\nfunction isMeasurable(a: LatLng, b: LatLng): boolean {\n return (\n Number.isFinite(a.latitude) &&\n Number.isFinite(a.longitude) &&\n Number.isFinite(b.latitude) &&\n Number.isFinite(b.longitude)\n );\n}\n\n/\n Great-circle (\"as the crow flies\") distance between two points, in metres.\n \n Pure and symmetric — `distanceBetween(a, b) === distanceBetween(b, a)` — and exactly `0` for identical\n * points. Correct across the antimeridian and the poles without any special-casing by the caller. Accepts\n * anything with `latitude` / `longitude`, so a {@link Position} from this slice can be passed directly.\n \n Not road distance and not ellipsoidal: ~0.5% worst case against a geodesic solution, dominated by the\n * spherical-Earth assumption rather than by the formula. Fine for proximity, sorting, and radius filters; not\n * for surveying.\n \n Never throws. Returns `NaN` if any component is `NaN`, `Infinity`, or otherwise not a finite number.\n \n @param a One endpoint.\n * @param b The other endpoint.\n * @returns Metres along the great circle, or `NaN` for unmeasurable input.\n /\nexport function distanceBetween(a: LatLng, b: LatLng): number {\n if (!isMeasurable(a, b)) return Number.NaN;\n\n const latitudeA = a.latitude DegreesToRadians;\n const latitudeB = b.latitude * DegreesToRadians;\n const halfLatitudeDelta = ((b.latitude - a.latitude) * DegreesToRadians) / 2;\n const halfLongitudeDelta = ((b.longitude - a.longitude) * DegreesToRadians) / 2;\n\n const chord =\n Math.sin(halfLatitudeDelta) ** 2 + Math.cos(latitudeA) * Math.cos(latitudeB) * Math.sin(halfLongitudeDelta) ** 2;\n\n const clamped = Math.min(1, Math.max(0, chord));\n return 2 * EarthRadiusMetres * Math.atan2(Math.sqrt(clamped), Math.sqrt(1 - clamped));\n}\n","import type { Position } from './Coordinates';\nimport type { PositionReadResult, PositionStatus } from '../PositionMapping';\n\n/*\n Where a geolocation consumer sits in its lifecycle: the platform's outcomes, plus the two states that exist\n * only in the UI — `idle` (nothing requested yet) and `locating` (a request is in flight).\n /\nexport const GeolocationState = {\n /* Nothing has been requested yet — the state before the first read and the one a reset returns to. /\n Idle: 'idle',\n\n /* A request is in flight; the permission prompt may be open. /\n Locating: 'locating',\n} as const;\n\n/* Where a geolocation consumer sits in its lifecycle — the UI-only states plus the platform's outcomes. /\nexport type GeolocationState = (typeof GeolocationState)[keyof typeof GeolocationState] \| PositionStatus;\n\n/* The state both {@link useGeolocation} and {@link useWatchPosition} expose. /\nexport interface GeolocationReading {\n /* The lifecycle state — drive the whole UI off this one switch. /\n readonly status: GeolocationState;\n\n /\n The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later\n * failure — check `status === 'ok'` when only a currently-valid reading will do.\n /\n readonly position: Position \| null;\n\n /* The error behind a `failed` status, or `null` for every other status. Never stale. /\n readonly error: Error \| null;\n}\n\n/* The starting state: nothing requested, nothing known. /\nexport const IdleGeolocationReading: GeolocationReading = {\n status: GeolocationState.Idle,\n position: null,\n error: null,\n};\n\n/\n Folds one {@link PositionReadResult} into the current reading. Pure; exported for the two composables and for tests,\n * absent from the barrel.\n \n @param previous The reading being updated — its `position` is what carries a past fix forward.\n * @param result The outcome to apply.\n * @returns The next reading.\n /\nexport function applyPositionResult(previous: GeolocationReading, result: PositionReadResult): GeolocationReading {\n return {\n status: result.ok ? 'ok' : result.failure.status,\n position: result.ok ? result.value : previous.position,\n error: !result.ok && result.failure.status === 'failed' ? result.failure.error : null,\n };\n}\n","import {\n computed,\n onScopeDispose,\n shallowRef,\n toValue,\n type ComputedRef,\n type MaybeRefOrGetter,\n type ShallowRef,\n} from 'vue';\n\nimport type { Position } from '../models/Coordinates';\nimport { getCurrentPosition } from '../GetCurrentPosition';\nimport {\n applyPositionResult,\n IdleGeolocationReading,\n type GeolocationReading,\n type GeolocationState,\n} from '../models/GeolocationReading';\nimport type { PositionRequestOptions, PositionReadResult } from '../PositionMapping';\n\n/\n What {@link useGeolocation} returns — the reactive form of a {@link GeolocationReading} plus the action that\n * refreshes it.\n /\nexport interface GeolocationControls {\n /* The lifecycle state — drive the whole UI off this one switch. /\n readonly status: ComputedRef<GeolocationState>;\n\n /\n The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later\n * failure — check `status.value === 'ok'` when only a currently-valid reading will do.\n /\n readonly position: ComputedRef<Position \| null>;\n\n /* The error behind a `failed` status, or `null` for every other status. Never stale. /\n readonly error: ComputedRef<Error \| null>;\n\n /* Convenience for `status === 'locating'` — the flag a button's `disabled` / spinner wants. /\n readonly locating: ComputedRef<boolean>;\n\n /\n Requests a fix, writing the outcome to this composable's state and also resolving to it. Never throws,\n * never rejects. Call it from a user gesture — it is what raises the permission prompt.\n \n @param overrides Options for this call only, replacing the composable-level ones. Omit to use those.\n /\n readonly request: (overrides?: PositionRequestOptions) => Promise<PositionReadResult>;\n}\n\n/\n Exposes the device's position as reactive state, with a `request()` that fetches it on demand.\n \n Requests nothing on mount — see the header for why that is deliberate. Inherits the slice's never-throws\n * contract: `request` resolves to a {@link PositionReadResult}, never rejects.\n \n @param options Default tuning for every `request()` call. A ref or getter is read at call time, so the value\n * in effect is always the current one.\n /\nexport function useGeolocation(options?: MaybeRefOrGetter<PositionRequestOptions \| undefined>): GeolocationControls {\n const reading: ShallowRef<GeolocationReading> = shallowRef(IdleGeolocationReading);\n\n /* Monotonic request token — only the newest request may write state. See the header. /\n let latestRequest = 0;\n let disposed = false;\n onScopeDispose(() => {\n disposed = true;\n latestRequest++;\n });\n\n const request = async (overrides?: PositionRequestOptions): Promise<PositionReadResult> => {\n if (disposed) return { ok: false, failure: { status: 'unsupported' } };\n latestRequest += 1;\n const token = latestRequest;\n\n reading.value = { ...reading.value, status: 'locating' };\n\n const result = await getCurrentPosition(overrides ?? toValue(options));\n\n if (token === latestRequest) reading.value = applyPositionResult(reading.value, result);\n return result;\n };\n\n return {\n status: computed(() => reading.value.status),\n position: computed(() => reading.value.position),\n error: computed(() => reading.value.error),\n locating: computed(() => reading.value.status === 'locating'),\n request,\n };\n}\n","import { onMounted, onScopeDispose, shallowRef, toValue, watch, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport { applyPositionResult, IdleGeolocationReading, type GeolocationReading } from '../models/GeolocationReading';\nimport type { PositionRequestOptions } from '../PositionMapping';\nimport { watchPosition } from '../WatchPosition';\n\n/\n Tracks the device's position for as long as the scope lives, clearing the watch when it is disposed.\n \n Starts on mount — see the header. Every fix and every failure arrives through the same\n * {@link GeolocationReading} shape `useGeolocation` exposes, minus the manual `request`; the last successful\n * fix survives a later failure, so a map keeps its pin when the signal drops.\n \n Inherits the slice's never-throws contract.\n \n @param options Accuracy / timeout / cache-age tuning. Changing any of the three values restarts the watch.\n * @returns The current reading. Holds {@link IdleGeolocationReading} during SSR and until mount.\n /\nexport function useWatchPosition(\n options?: MaybeRefOrGetter<PositionRequestOptions \| undefined>,\n): Readonly<ShallowRef<GeolocationReading>> {\n const reading: ShallowRef<GeolocationReading> = shallowRef(IdleGeolocationReading);\n\n let dispose: (() => void) \| undefined;\n\n function stop(): void {\n dispose?.();\n dispose = undefined;\n }\n\n function start(): void {\n stop();\n reading.value = { ...reading.value, status: 'locating' };\n\n const resolved = toValue(options);\n dispose = watchPosition(\n (result) => {\n reading.value = applyPositionResult(reading.value, result);\n },\n {\n enableHighAccuracy: resolved?.enableHighAccuracy,\n timeout: resolved?.timeout,\n maximumAge: resolved?.maximumAge,\n },\n );\n }\n\n onMounted(start);\n // Non-immediate on purpose: an immediate watcher runs on the server, where `navigator` is absent. Three\n // separate getters rather than one returning a tuple — Vue compares each source with `Object.is`, so an\n // options object of a fresh identity carrying the same three values does not restart the watch.\n watch(\n [() => toValue(options)?.enableHighAccuracy, () => toValue(options)?.timeout, () => toValue(options)?.maximumAge],\n start,\n );\n onScopeDispose(stop);\n\n return reading;\n}\n","/* Closed failure vocabulary for PositionFailure. */\nexport const PositionFailureCode = {\n Denied: 'denied',\n Unavailable: 'unavailable',\n Timeout: 'timeout',\n Unsupported: 'unsupported',\n Failed: 'failed',\n} as const;\n\nexport type PositionFailureCode = (typeof PositionFailureCode)[keyof typeof PositionFailureCode];\n"],"names":[],"mappings":"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"}

package/dist/foundation/geolocation/models/GeolocationReading.d.ts ADDED Viewed

@@ -0,0 +1,37 @@
+import { Position } from './Coordinates';
+import { PositionReadResult, PositionStatus } from '../PositionMapping';
+/**
+ * Where a geolocation consumer sits in its lifecycle: the platform's outcomes, plus the two states that exist
+ * only in the UI — `idle` (nothing requested yet) and `locating` (a request is in flight).
+ */
+export declare const GeolocationState: {
+    /** Nothing has been requested yet — the state before the first read and the one a reset returns to. */
+    readonly Idle: "idle";
+    /** A request is in flight; the permission prompt may be open. */
+    readonly Locating: "locating";
+};
+/** Where a geolocation consumer sits in its lifecycle — the UI-only states plus the platform's outcomes. */
+export type GeolocationState = (typeof GeolocationState)[keyof typeof GeolocationState] | PositionStatus;
+/** The state both {@link useGeolocation} and {@link useWatchPosition} expose. */
+export interface GeolocationReading {
+    /** The lifecycle state — drive the whole UI off this one switch. */
+    readonly status: GeolocationState;
+    /**
+     * The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later
+     * failure — check `status === 'ok'` when only a currently-valid reading will do.
+     */
+    readonly position: Position | null;
+    /** The error behind a `failed` status, or `null` for every other status. Never stale. */
+    readonly error: Error | null;
+}
+/** The starting state: nothing requested, nothing known. */
+export declare const IdleGeolocationReading: GeolocationReading;
+/**
+ * Folds one {@link PositionReadResult} into the current reading. Pure; exported for the two composables and for tests,
+ * absent from the barrel.
+ *
+ * @param previous The reading being updated — its `position` is what carries a past fix forward.
+ * @param result The outcome to apply.
+ * @returns The next reading.
+ */
+export declare function applyPositionResult(previous: GeolocationReading, result: PositionReadResult): GeolocationReading;

package/dist/foundation/geolocation/models/PositionFailure.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import { PositionFailureCode } from '../PositionFailureCode';
+/** Expected reasons the operation could not produce its requested value. */
+export type PositionFailure = {
+    readonly status: typeof PositionFailureCode.Denied;
+} | {
+    readonly status: typeof PositionFailureCode.Unavailable;
+} | {
+    readonly status: typeof PositionFailureCode.Timeout;
+} | {
+    readonly status: typeof PositionFailureCode.Unsupported;
+} | {
+    readonly status: typeof PositionFailureCode.Failed;
+    readonly error: Error;
+};

package/dist/foundation/geolocation/models/PositionReadResult.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import { Result } from '../../results';
+import { Position } from './Coordinates';
+import { PositionFailure } from './PositionFailure';
+/** The completed operation, carrying either its value or its typed failure. */
+export type PositionReadResult = Result<Position, PositionFailure>;

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

@@ -1,5 +1,5 @@
-import { GestureAxis } from './GestureAxis';
-import { SwipeDirection } from './SwipeDirection';
+import { GestureAxis } from './enums/GestureAxis';
+import { SwipeDirection } from './enums/SwipeDirection';
 /** A point in screen coordinates — `clientX` / `clientY` as reported by a pointer event. */
 export interface GesturePoint {
     /** Horizontal position in CSS pixels, growing rightward. */
@@ -44,7 +44,7 @@ export declare function gestureVelocity(delta: number, elapsedMs: number): numbe
  * @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): {
+export declare function windowedVelocity(samples: ReadonlyArray<GestureSample>, windowMs: number): {
     readonly velocityX: number;
     readonly velocityY: number;
 };
@@ -168,7 +168,7 @@ export declare function withinTolerance(dx: number, dy: number, tolerance: numbe
  * @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;
+export declare function acceptsPointerType(pointerType: string, allowed: ReadonlyArray<string> | undefined): boolean;
 /**
  * Clamps a long-press delay into the shared `PressExtensions.longPressDelay` bounds.
  *

package/dist/foundation/gestures/hooks/UseDrag.d.ts ADDED Viewed

@@ -0,0 +1,75 @@
+import { MaybeRefOrGetter } from 'vue';
+import { GestureAxis } from '../enums/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?: ReadonlyArray<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/hooks/UseLongPress.d.ts ADDED Viewed

@@ -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?: ReadonlyArray<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/hooks/UsePinch.d.ts ADDED Viewed

@@ -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?: ReadonlyArray<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/hooks/UseSwipe.d.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import { MaybeRefOrGetter } from 'vue';
+import { GestureAxis } from '../enums/GestureAxis';
+import { SwipeDirection } from '../enums/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 pointerup event that completed the gesture; cancelled pointers never produce a swipe. */
+    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?: ReadonlyArray<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 CHANGED Viewed

@@ -1,7 +1,7 @@
-export { SwipeDirection } from './SwipeDirection';
-export { GestureAxis } from './GestureAxis';
+export { SwipeDirection } from './enums/SwipeDirection';
+export { GestureAxis } from './enums/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';
+export { useDrag, type DragPayload, type DragHandlers, type DragOptions } from './hooks/UseDrag';
+export { useSwipe, type SwipePayload, type SwipeHandlers, type SwipeOptions } from './hooks/UseSwipe';
+export { useLongPress, type LongPressPayload, type LongPressOptions } from './hooks/UseLongPress';
+export { usePinch, type PinchPayload, type PinchHandlers, type PinchOptions } from './hooks/UsePinch';

package/dist/foundation/gestures/index.js CHANGED Viewed

@@ -18,7 +18,7 @@ const GestureAxis = {
   /** Unconstrained — recognition uses straight-line distance and both deltas are reported. */
   Both: "both"
 };
-const DEGREES_PER_RADIAN = 180 / Math.PI;
+const DegreesPerRadian = 180 / Math.PI;
 function finiteOrZero(value) {
   return Number.isFinite(value) ? value : 0;
 }
@@ -73,7 +73,7 @@ function pointerDistance(a, b) {
 function pointerAngle(a, b) {
   const dx = finiteOrZero(b.x) - finiteOrZero(a.x);
   const dy = finiteOrZero(b.y) - finiteOrZero(a.y);
-  return Math.atan2(dy, dx) * DEGREES_PER_RADIAN;
+  return Math.atan2(dy, dx) * DegreesPerRadian;
 }
 function pointerCenter(a, b) {
   return {
@@ -120,8 +120,8 @@ function clampLongPressDelay(delayMs) {
   if (delayMs === void 0 || !Number.isFinite(delayMs)) return bounds.default;
   return Math.min(bounds.max, Math.max(bounds.min, delayMs));
 }
-const MAX_SAMPLES = 16;
-const VELOCITY_WINDOW_MS = 80;
+const MaxSamples = 16;
+const VelocityWindowMs = 80;
 function useDrag(target, handlers, options) {
   watchPostEffect((onCleanup) => {
     const current = toValue(target);
@@ -132,7 +132,7 @@ function useDrag(target, handlers, options) {
     function toPayload(active, event) {
       const axis = toValue(options)?.axis ?? GestureAxis.Both;
       const { dx, dy } = constrainToAxis(event.clientX - active.originX, event.clientY - active.originY, axis);
-      const velocity = windowedVelocity(active.samples, VELOCITY_WINDOW_MS);
+      const velocity = windowedVelocity(active.samples, VelocityWindowMs);
       const constrainedVelocity = constrainToAxis(velocity.velocityX, velocity.velocityY, axis);
       return {
         dx,
@@ -147,7 +147,7 @@ function useDrag(target, handlers, options) {
     }
     function sample(active, event) {
       active.samples.push({ x: event.clientX, y: event.clientY, t: event.timeStamp });
-      if (active.samples.length > MAX_SAMPLES) active.samples.shift();
+      if (active.samples.length > MaxSamples) active.samples.shift();
     }
     function releaseCapture(pointerId) {
       try {
@@ -224,21 +224,22 @@ function useDrag(target, handlers, options) {
     });
   });
 }
-const DEFAULT_SWIPE_THRESHOLD = 50;
-const DEFAULT_VELOCITY_THRESHOLD = 0.3;
+const DefaultSwipeThreshold = 50;
+const DefaultVelocityThreshold = 0.3;
 function useSwipe(target, handlers, options) {
   useDrag(
     target,
     {
       onDragEnd: (payload) => {
+        if (payload.event.type === "pointercancel") return;
         const opts = toValue(options);
         const direction = swipeDirection(payload.dx, payload.dy);
         if (direction === null) return;
         const horizontal = direction === SwipeDirection.Left || direction === SwipeDirection.Right;
         const distance = Math.abs(horizontal ? payload.dx : payload.dy);
         const velocity = Math.abs(horizontal ? payload.velocityX : payload.velocityY);
-        const threshold = opts?.threshold ?? DEFAULT_SWIPE_THRESHOLD;
-        const velocityThreshold = opts?.velocityThreshold ?? DEFAULT_VELOCITY_THRESHOLD;
+        const threshold = opts?.threshold ?? DefaultSwipeThreshold;
+        const velocityThreshold = opts?.velocityThreshold ?? DefaultVelocityThreshold;
         if (distance < threshold || velocity < velocityThreshold) return;
         handlers.onSwipe?.({ direction, distance, velocity, event: payload.event });
       }
@@ -255,7 +256,7 @@ function useSwipe(target, handlers, options) {
     })
   );
 }
-const DEFAULT_MOVE_TOLERANCE = 10;
+const DefaultMoveTolerance = 10;
 function useLongPress(target, handler, options) {
   watchPostEffect((onCleanup) => {
     const current = toValue(target);
@@ -275,12 +276,12 @@ function useLongPress(target, handler, options) {
     }
     function onPointerMove(event) {
       if (state === null || event.pointerId !== state.pointerId) return;
-      const tolerance = toValue(options)?.moveTolerance ?? DEFAULT_MOVE_TOLERANCE;
+      const tolerance = toValue(options)?.moveTolerance ?? DefaultMoveTolerance;
       if (withinTolerance(event.clientX - state.originX, event.clientY - state.originY, tolerance)) return;
       cancel();
     }
-    function onPointerEnd() {
-      cancel();
+    function onPointerEnd(event) {
+      if (state?.pointerId === event.pointerId) cancel();
     }
     function onPointerDown(event) {
       const opts = toValue(options);