@octane-xplat/ui 0.6.0 → 0.7.1

package/src/references.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="@nativescript/types" />
+/// <reference types="vite/client" />

package/src/refresh-metrics.ts

@@ -0,0 +1,11 @@
+/** Pull-to-refresh geometry — one strip height drives the indicator
+ *  reveal, the default trigger threshold, and the docked gap on every
+ *  target (px on web, dip on native — equal by the dip≈px contract). */
+export const REFRESH_HEADER_HEIGHT = 64
+
+/** Finger-travel → content displacement. iOS rubber-band applies ~0.5
+ *  resistance at small pulls; web/Android drive the same ratio so the
+ *  affordance reads identically across targets. */
+export function dampenPull(dy: number): number {
+	return dy * 0.5
+}

package/src/refresh.ts

@@ -0,0 +1,271 @@
+import { isIOS } from '@nativescript/core'
+import { REFRESH_HEADER_HEIGHT, dampenPull } from './refresh-metrics'
+
+export interface RefreshConfig {
+	onRefresh?: () => void
+	refreshing?: boolean
+	threshold?: number
+}
+
+export interface RefreshHost {
+	/** The scrolling view — NS ScrollView or ListView. */
+	scroller: any
+	/** The overlay strip (owns the self-drawn spinner), translated in/out. */
+	indicator: any
+	/** True when the scroller is resting at its top edge (Android only —
+	 *  iOS reads the overscroll directly from contentOffset). */
+	isAtTop: () => boolean
+	/** Latest props — a ref so callback identity churn can't re-attach. */
+	cfg: { current: RefreshConfig }
+}
+
+export interface RefreshController {
+	/** Call when `refreshing` changes — docks/undocks the indicator. */
+	sync: () => void
+	detach: () => void
+}
+
+const PAN_ENDED = new Set([0, 3]) // GestureStateTypes cancelled / ended
+const DOCK_ANIM_MS = 180
+
+/* UIEdgeInsetsMake is a UIKit inline function — reach it through
+ * globalThis so nothing references NS globals at module scope. */
+function makeInsets(top: number, left: number, bottom: number, right: number) {
+	const make = (globalThis as any).UIEdgeInsetsMake
+	if (make) {
+		return make(top, left, bottom, right)
+	}
+
+	return { top, left, bottom, right }
+}
+
+/** Pan-driven pull-to-refresh over any NS scrollable (scrollview or
+ *  listview). Two mechanics, one visual:
+ *
+ *  iOS — UIScrollView's own bounce supplies the content displacement
+ *  (NS gesture delegates allow simultaneous recognition, so our pan on
+ *  the scroller observes alongside the scroll pan). The handler reads
+ *  `contentOffset` for the live gap and docks with
+ *  `contentInset.top += H` — the exact mechanics UIRefreshControl uses.
+ *
+ *  Android — there is no overscroll; the scroller box itself is
+ *  translated inside the clipping wrapper while the damped drag
+ *  accumulates. Docking holds the translate at H. Edge glow is disabled
+ *  (OVER_SCROLL_NEVER) so no OS chrome leaks into the pixels.
+ *
+ *  Releasing past `threshold` fires `onRefresh` once per pull and holds
+ *  the docked gap; the controlled `refreshing` prop keeps it docked.
+ *  A short grace window collapses the dock if `refreshing` never comes —
+ *  props land a render after `onRefresh` fires. */
+export function createPullToRefresh(host: RefreshHost): RefreshController {
+	const { scroller, indicator, isAtTop, cfg } = host
+	if (!scroller || !indicator) {
+		return { sync: () => {}, detach: () => {} }
+	}
+
+	let docked = false // gesture-driven dock at REFRESH_HEADER_HEIGHT
+	let pullAcc = 0 // android: damped accumulation beyond the held baseline
+	let prevDy = 0
+	let touching = false // a pan gesture is in flight
+	let grace: any = null
+	let baseInsetTop: number | null = null
+	let lastTy = Number.NaN
+
+	const threshold = () => cfg.current.threshold ?? REFRESH_HEADER_HEIGHT
+	/** Resting gap: the strip stays docked while the gesture docked it OR
+	 *  the controlled `refreshing` prop holds it open. */
+	const held = () => docked || !!cfg.current.refreshing
+
+	/* iOS: distance the content hangs below its resting top edge — 0 at
+	 * rest whether docked or not, so the held gap is added back by the
+	 * caller. */
+	const iosOverscroll = () => {
+		const sv = scroller.ios
+		if (!sv?.contentOffset) {
+			return 0
+		}
+
+		return Math.max(0, -(sv.contentOffset.y + sv.contentInset.top))
+	}
+
+	const applyReveal = (reveal: number) => {
+		const ty = reveal - REFRESH_HEADER_HEIGHT
+		if (ty !== lastTy) {
+			lastTy = ty
+			indicator.translateY = ty
+			if (!isIOS) {
+				scroller.translateY = reveal
+			}
+		}
+	}
+
+	const settle = (reveal: number) => {
+		lastTy = Number.NaN // animate() owns translateY now
+		if (isIOS) {
+			animateTo(indicator, reveal - REFRESH_HEADER_HEIGHT)
+		} else {
+			animateTo(scroller, reveal)
+			animateTo(indicator, reveal - REFRESH_HEADER_HEIGHT)
+		}
+	}
+
+	const setInset = (on: boolean) => {
+		const sv = scroller.ios
+		if (!sv?.contentInset) {
+			return
+		}
+
+		if (on && baseInsetTop == null) {
+			baseInsetTop = sv.contentInset.top
+		}
+
+		const next = (baseInsetTop ?? 0) + (on ? REFRESH_HEADER_HEIGHT : 0)
+		if (Math.abs(sv.contentInset.top - next) < 0.5) {
+			return
+		}
+
+		const apply = () => {
+			sv.contentInset = makeInsets(next, sv.contentInset.left, sv.contentInset.bottom, sv.contentInset.right)
+		}
+
+		const UIView = (globalThis as any).UIView
+		if (UIView?.animateWithDurationAnimations) {
+			UIView.animateWithDurationAnimations(DOCK_ANIM_MS / 1000, apply)
+		} else {
+			apply()
+		}
+	}
+
+	function animateTo(view: any, y: number) {
+		view?.animate?.({ translate: { x: 0, y }, duration: DOCK_ANIM_MS })
+	}
+
+	const dock = () => {
+		docked = true
+		pullAcc = 0
+		if (isIOS) {
+			setInset(true)
+		}
+
+		settle(REFRESH_HEADER_HEIGHT)
+	}
+
+	const collapse = () => {
+		docked = false
+		pullAcc = 0
+		if (isIOS) {
+			setInset(false)
+		}
+
+		settle(0)
+	}
+
+	/** `extra` is pull beyond the held baseline — a release only fires
+	 *  `onRefresh` when the user actually pulled (a resting release inside
+	 *  the dock re-fires nothing). */
+	const release = (extra: number) => {
+		const reveal = extra + (held() ? REFRESH_HEADER_HEIGHT : 0)
+		if (extra > 0 && reveal >= threshold()) {
+			cfg.current.onRefresh?.()
+			dock()
+			clearTimeout(grace)
+			grace = setTimeout(() => {
+				if (!cfg.current.refreshing) {
+					collapse()
+				}
+			}, 350)
+		} else if (held()) {
+			// A `refreshing`-driven dock deferred while the finger was down
+			// applies now; gesture-driven docks just settle back.
+			docked = true
+			pullAcc = 0
+			if (isIOS) {
+				setInset(true)
+			}
+
+			settle(REFRESH_HEADER_HEIGHT)
+		} else {
+			collapse()
+		}
+	}
+
+	const onPan = (e: any) => {
+		if (isIOS) {
+			// Clamped: once the user scrolls down past the held gap the
+			// indicator stays pinned — the dock is header-fixed, not a
+			// content row (uniform with the Android/web overlay).
+			const extra = iosOverscroll()
+			if (PAN_ENDED.has(e.state)) {
+				touching = false
+				release(extra)
+			} else {
+				touching = true
+				applyReveal(extra + (held() ? REFRESH_HEADER_HEIGHT : 0))
+			}
+
+			return
+		}
+
+		if (e.state === 1) {
+			touching = true
+			prevDy = e.deltaY
+			pullAcc = 0
+			return
+		}
+
+		if (PAN_ENDED.has(e.state)) {
+			touching = false
+			release(pullAcc)
+			pullAcc = 0
+			return
+		}
+
+		const inc = e.deltaY - prevDy
+		prevDy = e.deltaY
+		if (!isAtTop()) {
+			return
+		}
+
+		pullAcc = Math.max(0, pullAcc + dampenPull(inc))
+		applyReveal(pullAcc + (held() ? REFRESH_HEADER_HEIGHT : 0))
+	}
+
+	// `view.on('pan')` routes through NS's gesture observer; the recognizer
+	// attaches when the view loads. iOS marks NS recognizers as simultaneous
+	// with the scroll view's own pan, so it fires alongside scrolling.
+	scroller.on('pan', onPan)
+	// Kill Android's overscroll edge glow — OS chrome breaks the parity
+	// contract. 2 = android.view.View.OVER_SCROLL_NEVER.
+	if (!isIOS) {
+		scroller.android?.setOverScrollMode?.(2)
+	}
+
+	return {
+		sync: () => {
+			if (cfg.current.refreshing) {
+				clearTimeout(grace)
+				// Defer the dock while a gesture is in flight — release()
+				// applies it when the finger lifts.
+				if (!docked && !touching) {
+					dock()
+				}
+			} else if (docked && !touching) {
+				collapse()
+			}
+		},
+		detach: () => {
+			clearTimeout(grace)
+			scroller.off('pan', onPan)
+			if (docked) {
+				docked = false
+				if (isIOS) {
+					setInset(false)
+				} else {
+					scroller.translateY = 0
+				}
+
+				indicator.translateY = -REFRESH_HEADER_HEIGHT
+			}
+		},
+	}
+}

package/src/refresh.web.test.ts

@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPullToRefresh } from './refresh.web';
+import { REFRESH_HEADER_HEIGHT } from './refresh-metrics';
+
+// Unit-level check of the web pull-to-refresh state machine: synthetic
+// pointer events drive the controller, assertions read the composed
+// transform writes (setTranslate → translateX/translateY pair). jsdom has
+// no PointerEvent constructor — plain Events carry the fields the
+// handlers read.
+
+function host() {
+	const wrapper = document.createElement('div');
+	const scroller = document.createElement('div');
+	const indicator = document.createElement('div');
+	wrapper.appendChild(indicator);
+	wrapper.appendChild(scroller);
+	document.body.appendChild(wrapper);
+	return { wrapper, scroller, indicator };
+}
+
+function pointer(type: string, y: number) {
+	const e = new Event(type, { cancelable: true, bubbles: true });
+	Object.assign(e, { pointerType: 'mouse', clientY: y, button: 0 });
+	return e;
+}
+
+const ty = (el: HTMLElement) => el.style.transform;
+
+describe('createPullToRefresh (web)', () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		document.body.innerHTML = '';
+	});
+
+	it('tracks a sub-threshold drag and resets on release', () => {
+		const { scroller, indicator } = host();
+		const cfg = { current: { onRefresh: vi.fn() } };
+		const ctl = createPullToRefresh({ scroller, indicator, cfg });
+
+		scroller.dispatchEvent(pointer('pointerdown', 100));
+		scroller.dispatchEvent(pointer('pointermove', 180));
+		// damped: 80 * 0.5 = 40
+		expect(ty(scroller)).toContain('translateY(40px)');
+		expect(ty(indicator)).toContain(`translateY(${40 - REFRESH_HEADER_HEIGHT}px)`);
+
+		scroller.dispatchEvent(pointer('pointerup', 180));
+		expect(cfg.current.onRefresh).not.toHaveBeenCalled();
+		expect(ty(scroller)).toContain('translateY(0px)');
+		ctl.detach();
+	});
+
+	it('fires onRefresh and docks past the threshold; refreshless release collapses after grace', () => {
+		const { scroller, indicator } = host();
+		const cfg = { current: { onRefresh: vi.fn(), refreshing: false } };
+		const ctl = createPullToRefresh({ scroller, indicator, cfg });
+
+		scroller.dispatchEvent(pointer('pointerdown', 100));
+		scroller.dispatchEvent(pointer('pointermove', 320));
+		scroller.dispatchEvent(pointer('pointerup', 320));
+		// 220 * 0.5 = 110 >= 64 → docked
+		expect(cfg.current.onRefresh).toHaveBeenCalledTimes(1);
+		expect(ty(scroller)).toContain(`translateY(${REFRESH_HEADER_HEIGHT}px)`);
+		expect(ty(indicator)).toContain('translateY(0px)');
+
+		// refreshing never arrives → grace collapse
+		vi.advanceTimersByTime(400);
+		expect(ty(scroller)).toContain('translateY(0px)');
+		ctl.detach();
+	});
+
+	it('refreshing keeps the dock; sync(false) collapses', () => {
+		const { scroller, indicator } = host();
+		const cfg = { current: { onRefresh: vi.fn(), refreshing: false } };
+		const ctl = createPullToRefresh({ scroller, indicator, cfg });
+
+		scroller.dispatchEvent(pointer('pointerdown', 100));
+		scroller.dispatchEvent(pointer('pointermove', 320));
+		cfg.current.refreshing = true;
+		ctl.sync();
+		scroller.dispatchEvent(pointer('pointerup', 320));
+		expect(cfg.current.onRefresh).toHaveBeenCalledTimes(1);
+
+		vi.advanceTimersByTime(400);
+		expect(ty(scroller)).toContain(`translateY(${REFRESH_HEADER_HEIGHT}px)`);
+
+		cfg.current.refreshing = false;
+		ctl.sync();
+		expect(ty(scroller)).toContain('translateY(0px)');
+		expect(ty(indicator)).toContain(`translateY(${-REFRESH_HEADER_HEIGHT}px)`);
+		ctl.detach();
+	});
+
+	it('ignores drags that start below the top edge', () => {
+		const { scroller } = host();
+		Object.defineProperty(scroller, 'scrollTop', { value: 30, writable: true });
+		const cfg = { current: { onRefresh: vi.fn() } };
+		const ctl = createPullToRefresh({ scroller, indicator: document.createElement('div'), cfg });
+
+		scroller.dispatchEvent(pointer('pointerdown', 100));
+		scroller.dispatchEvent(pointer('pointermove', 320));
+		scroller.dispatchEvent(pointer('pointerup', 320));
+		expect(cfg.current.onRefresh).not.toHaveBeenCalled();
+		expect(ty(scroller)).toBe('');
+		ctl.detach();
+	});
+});

package/src/refresh.web.ts

@@ -0,0 +1,205 @@
+import { REFRESH_HEADER_HEIGHT, dampenPull } from './refresh-metrics'
+import { setTranslate } from './translate.web'
+
+export interface RefreshConfig {
+	onRefresh?: () => void
+	refreshing?: boolean
+	threshold?: number
+}
+
+export interface RefreshController {
+	/** Call when `refreshing` changes — docks/undocks the indicator. */
+	sync: () => void
+	detach: () => void
+}
+
+const DOCK_ANIM_MS = 180
+
+/** Pointer/touch-driven pull-to-refresh for the DOM leaf — the web has no
+ *  native overscroll, so drag distance translates the scroller inside the
+ *  clipped wrapper while the self-drawn indicator slides into the gap.
+ *  `touchmove` must be non-passive: `preventDefault` is what keeps the
+ *  browser from taking the gesture as a scroll (or Chrome's own
+ *  pull-to-refresh on Android). Mouse drags ride the pointer events. */
+export function createPullToRefresh(host: {
+	scroller: HTMLElement | null
+	indicator: HTMLElement | null
+	cfg: { current: RefreshConfig }
+}): RefreshController {
+	const { scroller, indicator, cfg } = host
+	if (!scroller || !indicator) {
+		return { sync: () => {}, detach: () => {} }
+	}
+
+	let pulling = false
+	let y0 = 0
+	let pull = 0 // displacement beyond the held baseline
+	let docked = false // gesture-driven dock at REFRESH_HEADER_HEIGHT
+	let grace: ReturnType<typeof setTimeout> | null = null
+
+	const threshold = () => cfg.current.threshold ?? REFRESH_HEADER_HEIGHT
+	/** Resting gap: the strip stays docked while the gesture docked it OR
+	 *  the controlled `refreshing` prop holds it open. */
+	const held = () => docked || !!cfg.current.refreshing
+
+	const applyReveal = (reveal: number) => {
+		setTranslate(indicator, 0, reveal - REFRESH_HEADER_HEIGHT)
+		setTranslate(scroller, 0, reveal)
+	}
+
+	const settle = (reveal: number) => {
+		for (const el of [scroller, indicator]) {
+			el.style.transition = `transform ${DOCK_ANIM_MS}ms ease-out`
+		}
+
+		applyReveal(reveal)
+		setTimeout(() => {
+			for (const el of [scroller, indicator]) {
+				el.style.transition = ''
+			}
+		}, DOCK_ANIM_MS)
+	}
+
+	const dock = () => {
+		docked = true
+		pull = 0
+		settle(REFRESH_HEADER_HEIGHT)
+	}
+
+	const collapse = () => {
+		docked = false
+		pull = 0
+		settle(0)
+	}
+
+	/** `pull` is drag distance beyond the held baseline — a release only
+	 *  fires `onRefresh` when the user actually pulled (a resting release
+	 *  inside the dock re-fires nothing). */
+	const release = () => {
+		pulling = false
+		const reveal = pull + (held() ? REFRESH_HEADER_HEIGHT : 0)
+		if (pull > 0 && reveal >= threshold()) {
+			cfg.current.onRefresh?.()
+			dock()
+			if (grace) {
+				clearTimeout(grace)
+			}
+
+			grace = setTimeout(() => {
+				if (!cfg.current.refreshing) {
+					collapse()
+				}
+			}, 350)
+		} else if (held()) {
+			// A `refreshing`-driven dock deferred while the pointer was down
+			// applies now; gesture-driven docks just settle back.
+			docked = true
+			pull = 0
+			settle(REFRESH_HEADER_HEIGHT)
+		} else {
+			collapse()
+		}
+	}
+
+	const begin = (y: number, prevent?: () => void) => {
+		if (scroller.scrollTop > 0) {
+			return
+		}
+
+		pulling = true
+		y0 = y
+		pull = 0
+		prevent?.()
+	}
+
+	const move = (y: number, prevent: () => void) => {
+		if (!pulling) {
+			return
+		}
+
+		const dy = y - y0
+		if (dy <= 0 || scroller.scrollTop > 0) {
+			pulling = false
+			pull = 0
+			applyReveal(held() ? REFRESH_HEADER_HEIGHT : 0)
+			return
+		}
+
+		prevent()
+		pull = dampenPull(dy)
+		applyReveal(pull + (held() ? REFRESH_HEADER_HEIGHT : 0))
+	}
+
+	const end = () => {
+		if (pulling) {
+			release()
+		}
+	}
+
+	const touchStart = (e: TouchEvent) => begin(e.touches[0].clientY)
+	const touchMove = (e: TouchEvent) => move(e.touches[0].clientY, () => e.preventDefault())
+	const touchEnd = () => end()
+	// pointer events cover mouse/pen drags — touch is handled by the touch
+	// listeners above since pointermove cannot preventDefault a native pan.
+	const pointerDown = (e: PointerEvent) => {
+		if (e.pointerType === 'mouse' && e.button === 0) {
+			begin(e.clientY, () => e.preventDefault())
+		}
+	}
+
+	const pointerMove = (e: PointerEvent) => {
+		if (e.pointerType === 'mouse') {
+			move(e.clientY, () => e.preventDefault())
+		}
+	}
+
+	const pointerUp = (e: PointerEvent) => {
+		if (e.pointerType === 'mouse') {
+			end()
+		}
+	}
+
+	scroller.addEventListener('touchstart', touchStart, { passive: true })
+	scroller.addEventListener('touchmove', touchMove, { passive: false })
+	scroller.addEventListener('touchend', touchEnd)
+	scroller.addEventListener('touchcancel', touchEnd)
+	scroller.addEventListener('pointerdown', pointerDown)
+	scroller.addEventListener('pointermove', pointerMove)
+	scroller.addEventListener('pointerup', pointerUp)
+	scroller.addEventListener('pointercancel', pointerUp)
+
+	return {
+		sync: () => {
+			if (cfg.current.refreshing) {
+				if (grace) {
+					clearTimeout(grace)
+				}
+
+				// Defer the dock while a gesture is in flight — release()
+				// applies it when the pointer lifts.
+				if (!docked && !pulling) {
+					dock()
+				}
+			} else if (docked && !pulling) {
+				collapse()
+			}
+		},
+		detach: () => {
+			if (grace) {
+				clearTimeout(grace)
+			}
+
+			scroller.removeEventListener('touchstart', touchStart)
+			scroller.removeEventListener('touchmove', touchMove)
+			scroller.removeEventListener('touchend', touchEnd)
+			scroller.removeEventListener('touchcancel', touchEnd)
+			scroller.removeEventListener('pointerdown', pointerDown)
+			scroller.removeEventListener('pointermove', pointerMove)
+			scroller.removeEventListener('pointerup', pointerUp)
+			scroller.removeEventListener('pointercancel', pointerUp)
+			scroller.style.transition = ''
+			indicator.style.transition = ''
+			applyReveal(0)
+		},
+	}
+}

package/src/root-layout.mobile.ts

@@ -0,0 +1,89 @@
+import { getRootLayout, RootLayout } from '@nativescript/core'
+
+// NS keeps an internal rootLayoutStack (mounted order) — but the module is
+// private and can duplicate when deep imports split bundles, so Screen
+// self-registers here on loaded/unloaded instead. registry order = mount
+// order; last = most recently mounted screen shell.
+const registry: RootLayout[] = []
+
+/** Called by the Screen leaf's <rootlayout> onLoaded/onUnloaded. */
+export function registerRootLayout(rl: RootLayout | undefined | null) {
+	if (rl && !registry.includes(rl)) {
+		registry.push(rl)
+	}
+}
+
+export function unregisterRootLayout(rl: RootLayout | undefined | null) {
+	const i = rl ? registry.indexOf(rl) : -1
+	if (i >= 0) {
+		registry.splice(i, 1)
+	}
+}
+
+/** The most recently mounted rootlayout — the top of the push stack. For
+ *  imperative services (toast, sheet) there is no invoking component to
+ *  walk from; last-mounted is the pushed page when one exists. Caveat: tabs
+ *  keep visited panes mounted — last is the newest, not the visible tab. */
+export function topRootLayout(): RootLayout | undefined {
+	return registry[registry.length - 1] ?? getRootLayout()
+}
+
+/** Resolve the RootLayout enclosing `view` by walking the native parent
+ *  chain — the screen shell is a RootLayout (Screen), so the first
+ *  RootLayout ancestor IS the current page's overlay host. Falls back to
+ *  the top registry entry when the component renders outside any Screen. */
+export function rootLayoutFor(view: any): RootLayout | undefined {
+	for (let v = view?.parent; v; v = v.parent) {
+		if (v instanceof RootLayout) {
+			return v
+		}
+	}
+
+	return topRootLayout()
+}
+
+/** Search every registered rootlayout for a view by id — overlays/sheets/
+ *  toasts land on different rootlayouts depending on which screen's shell
+ *  mounted last. Unloaded subtrees are skipped: a covered page unloads its
+ *  views (NativeScript detaches their native recognizers while the JS views
+ *  stay parented), so an unloaded match is a dead twin that can swallow
+ *  interaction probes — the live view either doesn't exist here yet or sits
+ *  under a loaded branch. */
+export function findInRootLayouts(id: string): any {
+	const walk = (view: any): any => {
+		if (!view) {
+			return null
+		}
+
+		if (view.id === id) {
+			return view
+		}
+
+		let hit: any = null
+		view.eachChildView?.((c: any) => {
+			if (c?.isLoaded === false) {
+				return true
+			}
+
+			const found = walk(c)
+			if (found) {
+				hit = found
+				return false
+			}
+
+			return true
+		})
+
+		return hit
+	}
+
+	for (let i = registry.length - 1; i >= 0; i--) {
+		const hit = walk(registry[i])
+		if (hit) {
+			return hit
+		}
+	}
+
+	const rl = getRootLayout() as any
+	return rl ? walk(rl) : null
+}

package/src/route-host.mobile.ts

@@ -0,0 +1 @@
+export { RouteHost, screenParamsFor } from './RouteHost.mobile.tsrx'