@octane-xplat/ui 0.5.0 → 0.7.0

package/src/sheet-detents.web.ts

@@ -0,0 +1,147 @@
+import { setTranslate } from './translate.web'
+import { detentOffset, normalizeDetents, snapDetentIndex } from './sheet-snap'
+
+const SNAP_MS = 200
+
+export interface SheetDetentsController {
+	detach: () => void
+}
+
+/** Drag-to-snap detents on a `.vx-sheet` panel: a self-drawn grabber strip
+ *  (the only drag target — it never fights inner scrolling) drives the
+ *  panel's translateY; the panel is sized to the largest detent and parked
+ *  at the offset for the current one. `closeNow` fires after the dismiss
+ *  slide-out — the caller decides what closing means (declarative
+ *  `onDismiss` or the `openSheet` resolution). In-window on every target —
+ *  the OS detent presentations (UISheetPresentationController /
+ *  BottomSheetDialog) host a modal VC/dialog window, not a RootLayout
+ *  child, so the snap mechanics stay self-drawn for pixel parity. */
+export function attachSheetDetents(
+	panel: HTMLElement,
+	detents: readonly number[],
+	closeNow: () => void,
+): SheetDetentsController {
+	const sorted = normalizeDetents(detents)
+	if (!sorted.length) {
+		return { detach: () => {} }
+	}
+
+	const vh = () => panel.parentElement?.clientHeight || window.innerHeight || 1
+	const max = sorted[sorted.length - 1]
+
+	panel.classList.add('vx-sheet-detents')
+	// Panel is sized to the largest detent; translateY parks it per detent.
+	panel.style.height = `${max * 100}%`
+
+	const grabber = document.createElement('div')
+	grabber.className = 'vx-sheet-grabber'
+	const grip = document.createElement('div')
+	grip.className = 'vx-sheet-grip'
+	grabber.appendChild(grip)
+	panel.appendChild(grabber)
+
+	let cur = 0
+	let ty = 0
+	let dragging = false
+	let y0 = 0
+	let ty0 = 0
+	let vy = 0
+	let lastY = 0
+	let lastT = 0
+
+	const applyTy = (value: number) => {
+		ty = value
+		setTranslate(panel, 0, value)
+	}
+
+	const animateTo = (value: number, then?: () => void) => {
+		panel.style.transition = `transform ${SNAP_MS}ms ease-out`
+		applyTy(value)
+		setTimeout(() => {
+			panel.style.transition = ''
+			then?.()
+		}, SNAP_MS)
+	}
+
+	const down = (e: PointerEvent) => {
+		if (e.pointerType === 'mouse' && e.button !== 0) {
+			return
+		}
+
+		dragging = true
+		grabber.setPointerCapture?.(e.pointerId)
+		y0 = e.clientY
+		lastY = e.clientY
+		lastT = Date.now()
+		ty0 = ty
+		vy = 0
+		panel.style.transition = ''
+		e.preventDefault()
+	}
+
+	const move = (e: PointerEvent) => {
+		if (!dragging) {
+			return
+		}
+
+		const now = Date.now()
+		const dt = (now - lastT) / 1000
+		if (dt > 0) {
+			// Smoothed velocity — a single noisy event shouldn't fling.
+			vy = vy * 0.7 + ((e.clientY - lastY) / dt) * 0.3
+		}
+
+		lastY = e.clientY
+		lastT = now
+		applyTy(Math.min(Math.max(ty0 + (e.clientY - y0), 0), vh()))
+		e.preventDefault()
+	}
+
+	const up = () => {
+		if (!dragging) {
+			return
+		}
+
+		dragging = false
+		const next = snapDetentIndex(ty, vy, sorted, vh())
+		if (next < 0) {
+			animateTo(vh(), closeNow)
+		} else {
+			cur = next
+			animateTo(detentOffset(sorted, cur, vh()))
+		}
+	}
+
+	// `.vx-sheet` scrolls its own overflow — the grabber is absolutely
+	// positioned against the content box, so pin it to the scrollport top
+	// while the panel scrolls (same floating-overlay shape as native).
+	const pinGrabber = () => {
+		grabber.style.top = `${panel.scrollTop}px`
+	}
+
+	panel.addEventListener('scroll', pinGrabber)
+	grabber.addEventListener('pointerdown', down)
+	grabber.addEventListener('pointermove', move)
+	grabber.addEventListener('pointerup', up)
+	grabber.addEventListener('pointercancel', up)
+
+	// Slide in from below the screen edge, matching the native leaf's
+	// translateY = vh → detent enter animation.
+	applyTy(vh())
+	const raf = requestAnimationFrame(() => animateTo(detentOffset(sorted, cur, vh())))
+
+	return {
+		detach: () => {
+			cancelAnimationFrame(raf)
+			panel.removeEventListener('scroll', pinGrabber)
+			grabber.removeEventListener('pointerdown', down)
+			grabber.removeEventListener('pointermove', move)
+			grabber.removeEventListener('pointerup', up)
+			grabber.removeEventListener('pointercancel', up)
+			grabber.remove()
+			panel.classList.remove('vx-sheet-detents')
+			panel.style.height = ''
+			panel.style.transition = ''
+		},
+	}
+}

package/src/sheet-service.macos.ts

@@ -0,0 +1,60 @@
+import type { ModalOpenResult, OpenSheet, SheetOpenOptions } from './props'
+
+interface SheetController {
+	close(): void
+	closed: Promise<void>
+}
+
+interface ActiveSheet {
+	controller: SheetController
+	finish: (result?: ModalOpenResult) => void
+}
+
+const active = new Set<ActiveSheet>()
+
+const mount = () => (globalThis as any).__xplatAppKitMountSheet
+
+/** Close the most recently opened sheet (resolve with `result`). */
+export function closeSheet(result?: ModalOpenResult): void {
+	;[...active].pop()?.finish(result)
+}
+
+/** Imperative sheet on the AppKit host — the component mounts on a dedicated
+ *  Octane root inside a dialog-kind window presented as a sheet on the key
+ *  window. Resolves when the sheet closes (either `close(result)` from the
+ *  component or the window itself closing). `sheetHost` stays null — the
+ *  sheet lives in a real NSWindow, not a rendered host element. */
+export const openSheet: OpenSheet = (Component, params, options: SheetOpenOptions = {}) => {
+	if (typeof mount() !== 'function') {
+		console.warn('[octane-xplat] Imperative sheets are unsupported by the current AppKit host.')
+		return Promise.reject(new Error('unsupported: AppKit host has no sheet presenter'))
+	}
+
+	return new Promise<ModalOpenResult>((resolve) => {
+		let finished = false
+		const finish = (result?: ModalOpenResult) => {
+			if (finished) return
+			finished = true
+			active.delete(entry)
+			try {
+				entry.controller?.close()
+			} catch (error) {
+				console.error('[octane-xplat] sheet close failed', error)
+			}
+			resolve(result)
+		}
+
+		const entry: ActiveSheet = {
+			controller: undefined as unknown as SheetController,
+			finish,
+		}
+
+		entry.controller = mount()(Component, { params, close: finish }, options)
+		active.add(entry)
+		void entry.controller.closed.then(() => finish('closed'))
+	})
+}
+
+export function sheetHost(): null {
+	return null
+}

package/src/sheet-service.ts

@@ -0,0 +1,124 @@
+import { GridLayout } from '@nativescript/core'
+import { createNativeScriptRoot } from '@nativescript-community/octane'
+import type { UniversalComponent } from 'octane/universal'
+import type { ModalOpenResult, OpenSheet } from './props'
+import { topRootLayout } from './root-layout.mobile'
+import { applyThemeClasses } from './theme/theme-scheme'
+import { attachSheetDetents } from './sheet-detents'
+import { bindBottomInsetToKeyboard } from './keyboard-inset.mobile'
+import { attachTapToBlur } from './tap-to-blur.mobile' 
+
+interface ActiveSheet {
+	host: GridLayout
+	root: any
+	unbindKeyboard?: () => void
+	finish: (result?: ModalOpenResult) => void
+}
+
+const active = new Set<ActiveSheet>()
+
+/** The most recently opened sheet's host view — for harness asserts (view
+ *  identity beats tree search; the owning rootlayout may unload/reload). */
+export function sheetHost(): GridLayout | null {
+	return [...active].pop()?.host ?? null
+}
+
+/** Close the most recently opened sheet (resolve with `result`). */
+export function closeSheet(result?: ModalOpenResult): void {
+	;[...active].pop()?.finish(result)
+}
+
+/** Imperative in-window sheet: a dedicated Octane root on a bottom-docked
+ *  GridLayout host opened on the CURRENT rootlayout (topRootLayout — the
+ *  service has no declaring view). Resolves when the sheet closes. */
+export const openSheet: OpenSheet = (Component, params, options = {}) =>
+	new Promise<ModalOpenResult>((resolve) => {
+		const rl = topRootLayout()
+		if (!rl) {
+			console.warn('[openSheet] no RootLayout mounted — sheet skipped')
+			resolve(undefined)
+			return
+		}
+
+		const host = new GridLayout()
+		const unbindTheme = applyThemeClasses(host, 'vx-sheet-host')
+		host.horizontalAlignment = 'stretch'
+		host.verticalAlignment = 'bottom'
+		const root = createNativeScriptRoot(host)
+		// Detents own enter/slide-out — the RootLayout animation always
+		// lands translateY at 0, so it's skipped while detents attach.
+		const detents = options.detents?.length
+			? attachSheetDetents(host, options.detents, () => finish())
+			: null
+
+		// Lift the host above the software keyboard — bottom-anchored sheets
+		// hosting inputs (e.g. the demo 'In sheet' todo add row) are covered
+		// otherwise.
+		const unbindKeyboard = bindBottomInsetToKeyboard(host)
+		attachTapToBlur(host)
+
+		let finished = false
+		// RootLayout notifies 'closed' from inside its own close(), before the
+		// removal lands — hasChild still answers true there. Re-entering
+		// close() from that notification schedules a second removeChild and
+		// throws 'View not added to this instance' once the first removal
+		// clears the parent. While a close is in flight the host is already
+		// spliced out of _popupViews, so getPopupIndex < 0 marks the two cases
+		// where we must not close() again: mid-close (RootLayout owns the
+		// detach) and raced-close leftovers (plain removeChild instead).
+		const finish = (result?: ModalOpenResult) => {
+			if (finished) {
+				return
+			}
+
+			finished = true
+			active.delete(entry)
+			unbindKeyboard()
+			unbindTheme()
+			detents?.detach()
+			root.unmount?.()
+			const owner = host.parent as any
+			if (owner?.hasChild?.(host) && !closing) {
+				if (owner.getPopupIndex?.(host) === -1) {
+					owner.removeChild?.(host)
+				} else {
+					;(owner.close?.(host) as Promise<unknown> | undefined)?.catch((error: unknown) => {
+						console.error('[openSheet] close failed', error)
+					})
+				}
+			}
+
+			resolve(result)
+		}
+
+		let closing = false
+
+		const entry: ActiveSheet = { host, root, unbindKeyboard, finish }
+		// 'closed' covers tap-to-dismiss — finish through the same path, but
+		// mark the close as already in flight so finish doesn't re-enter
+		// RootLayout.close (see above).
+		host.on('closed', () => {
+			closing = true
+			finish()
+		})
+
+		root.render(Component as UniversalComponent, { params, close: finish })
+		active.add(entry)
+
+		rl.open(host, {
+			...((options.shadeCover ?? true) ? { shadeCover: { opacity: 0.4, tapToClose: true } } : {}),
+			...(detents
+				? {}
+				: {
+						animation: {
+							enterFrom: { translateY: 400, duration: 250 },
+							exitTo: { translateY: 400, duration: 200 },
+						},
+					}),
+		})
+			.then(() => detents?.enter())
+			.catch((error: unknown) => {
+				console.error('[openSheet] open failed', error)
+				finish()
+			})
+	})

package/src/sheet-service.web.ts

@@ -0,0 +1,64 @@
+import { createRoot } from 'octane'
+import type { ModalOpenResult, OpenSheet } from './props'
+import { applyThemeClasses } from './theme/theme-scheme'
+import { attachSheetDetents } from './sheet-detents.web'
+
+interface ActiveSheet {
+	layer: HTMLElement
+	finish: (result?: ModalOpenResult) => void
+}
+
+const active = new Set<ActiveSheet>()
+
+/** Close the most recently opened sheet (resolve with `result`). */
+export function closeSheet(result?: ModalOpenResult): void {
+	;[...active].pop()?.finish(result)
+}
+
+/** Imperative in-window sheet: portal layer at document root, bottom-
+ *  anchored panel, dedicated Octane root. Resolves when the sheet closes. */
+export const openSheet: OpenSheet = (Component, params, options = {}) =>
+	new Promise<ModalOpenResult>((resolve) => {
+		const layer = document.createElement('div')
+		const unbindTheme = applyThemeClasses(layer, 'vx-sheet-layer')
+		const panel = document.createElement('div')
+		panel.className = 'vx-sheet'
+		if (options.detents?.length) {
+			panel.classList.add('vx-sheet-detents')
+		}
+
+		let finished = false
+		const finish = (result?: ModalOpenResult) => {
+			if (finished) {
+				return
+			}
+
+			finished = true
+			active.delete(entry)
+			unbindTheme()
+			detents?.detach()
+			root.unmount()
+			layer.remove()
+			resolve(result)
+		}
+
+		const entry: ActiveSheet = { layer, finish }
+		if (options.shadeCover ?? true) {
+			const backdrop = document.createElement('div')
+			backdrop.className = 'vx-sheet-backdrop'
+			backdrop.addEventListener('click', () => finish())
+			layer.appendChild(backdrop)
+		}
+
+		layer.appendChild(panel)
+		document.body.appendChild(layer)
+		// Attached after the layer is in the document — the panel sizes
+		// against the viewport and slides in to the smallest detent.
+		const detents = options.detents?.length
+			? attachSheetDetents(panel, options.detents, () => finish())
+			: null
+
+		const root = createRoot(panel)
+		root.render(Component, { params, close: finish })
+		active.add(entry)
+	})

package/src/sheet-snap.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { detentOffset, normalizeDetents, snapDetentIndex } from './sheet-snap';
+
+// Pure math behind the sheet detents: fractions → sorted snap points →
+// resting translateY offsets → release-time snap targets. The DOM/NS
+// attachments are thin adapters over this.
+
+const D = [0.25, 0.5, 0.9];
+const VH = 800;
+
+describe('normalizeDetents', () => {
+	it('sorts, filters, and dedupes', () => {
+		expect(normalizeDetents([0.9, 0.25, 0, 1.5, 0.25])).toEqual([0.25, 0.9]);
+		expect(normalizeDetents()).toEqual([]);
+		expect(normalizeDetents([0])).toEqual([]);
+	});
+});
+
+describe('detentOffset', () => {
+	it('parks the largest-detent-sized panel per detent', () => {
+		expect(detentOffset(D, 0, VH)).toBe((0.9 - 0.25) * VH);
+		expect(detentOffset(D, 2, VH)).toBe(0);
+	});
+});
+
+describe('snapDetentIndex', () => {
+	it('snaps to the nearest detent on a slow release', () => {
+		// frac 0.55 → detent 0.5 wins
+		expect(snapDetentIndex((0.9 - 0.55) * VH, 0, D, VH)).toBe(1);
+		expect(snapDetentIndex(0, 0, D, VH)).toBe(2); // fully open
+	});
+
+	it('dismisses below half of the smallest detent', () => {
+		// frac 0.1 < 0.25/2
+		expect(snapDetentIndex((0.9 - 0.1) * VH, 0, D, VH)).toBe(-1);
+	});
+
+	it('fling direction overrides proximity', () => {
+		// frac 0.6 (nearer 0.5) flung up → 0.9
+		expect(snapDetentIndex((0.9 - 0.6) * VH, -600, D, VH)).toBe(2);
+		// frac 0.4 (nearer 0.5) flung down → 0.25
+		expect(snapDetentIndex((0.9 - 0.4) * VH, 600, D, VH)).toBe(0);
+		// flung down at/below the smallest detent → dismiss
+		expect(snapDetentIndex((0.9 - 0.25) * VH, 600, D, VH)).toBe(-1);
+	});
+});

package/src/sheet-snap.ts

@@ -0,0 +1,66 @@
+/** Detent math shared by the web/native sheet-detents attachments.
+ *  Detents are viewport-height fractions; the panel is sized to the
+ *  largest detent and parked at the translateY offset for the current
+ *  one, so a snap is just a transform write — no layout thrash. */
+
+/** Downward/upward finger speed (px/s web, dip/s native) that overrides
+ *  nearest-detent snapping — a fling snaps one detent in its direction. */
+export const DETENT_FLICK_VELOCITY = 500
+
+/** Sorted, filtered, deduped detent fractions. Empty → the caller keeps
+ *  the content-sized sheet behavior (detents off). */
+export function normalizeDetents(input?: readonly number[]): number[] {
+	if (!input?.length) {
+		return []
+	}
+
+	return [...new Set(input.filter((d) => d > 0 && d <= 1))].sort((a, b) => a - b)
+}
+
+/** Resting translateY for a detent: the panel is `max * vh` tall, so the
+ *  portion below the screen edge is `(max - detent) * vh`. */
+export function detentOffset(detents: readonly number[], index: number, vh: number): number {
+	return (detents[detents.length - 1] - detents[index]) * vh
+}
+
+/** Snap target for a release at translateY `ty` with vertical velocity
+ *  `vy` (positive = dragging down). Returns the detent index, or -1 to
+ *  dismiss: released below half of the smallest detent, or a downward
+ *  fling while at/below it. */
+export function snapDetentIndex(ty: number, vy: number, detents: readonly number[], vh: number): number {
+	const max = detents[detents.length - 1]
+	const frac = Math.min(Math.max(max - ty / vh, 0), 1)
+
+	if (vy > DETENT_FLICK_VELOCITY) {
+		// Fling down — the nearest detent strictly below the finger.
+		let i = -1
+		while (i + 1 < detents.length && detents[i + 1] < frac - 1e-6) {
+			i++
+		}
+
+		return i
+	}
+
+	if (vy < -DETENT_FLICK_VELOCITY) {
+		// Fling up — the nearest detent strictly above the finger.
+		let i = detents.length - 1
+		while (i - 1 >= 0 && detents[i - 1] > frac + 1e-6) {
+			i--
+		}
+
+		return i
+	}
+
+	if (frac < detents[0] * 0.5) {
+		return -1
+	}
+
+	let best = 0
+	for (let i = 1; i < detents.length; i++) {
+		if (Math.abs(detents[i] - frac) < Math.abs(detents[best] - frac)) {
+			best = i
+		}
+	}
+
+	return best
+}

package/src/stacks.macos.ts

@@ -0,0 +1,13 @@
+const stacks = new Map<string, unknown>()
+
+export function registerStack(name: string, stack: unknown): void {
+	stacks.set(name, stack)
+}
+
+export function getStack(name: string): unknown {
+	return stacks.get(name)
+}
+
+export function stackEntries(): IterableIterator<[string, unknown]> {
+	return stacks.entries()
+}

package/src/stacks.ts

@@ -0,0 +1,44 @@
+import { Application, Frame } from '@nativescript/core'
+
+/** Named parallel stacks. A shell (Tabs with `stack` on a spec, the app
+ *  entry's root frame) registers its Frame here; `pushRoute` resolves the
+ *  target by name. Native-only concept — on web, parallel stacks map to
+ *  nested routes (one linear URL stack). 'root' needs no registration:
+ *  unregistered, it resolves to the app's root view when that's a
+ *  Frame — the standard `Application.run({ create: () => frame })` boot
+ *  shape. An explicit registerStack('root', frame) overrides it. */
+const stacks = new Map<string, Frame>()
+const regListeners = new Set<(name: string, frame: Frame) => void>()
+
+export function registerStack(name: string, frame: Frame): void {
+	stacks.set(name, frame)
+	regListeners.forEach((l) => l(name, frame))
+}
+
+export function getStack(name: string): Frame | undefined {
+	const registered = stacks.get(name)
+	if (registered) {
+		return registered
+	}
+
+	if (name === 'root') {
+		const rv = Application.getRootView?.()
+		if (rv instanceof Frame) {
+			return rv
+		}
+	}
+
+	return undefined
+}
+
+/** All registered stacks in registration order — for hardware-back
+ *  resolution (pop whichever stack is visibly on top). */
+export function stackEntries(): IterableIterator<[string, Frame]> {
+	return stacks.entries()
+}
+
+/** Internal: route.native attaches frame listeners as stacks appear —
+ *  named frames can register after a useRoute subscription ran. */
+export function onStackRegistered(cb: (name: string, frame: Frame) => void): void {
+	regListeners.add(cb)
+}

package/src/stacks.web.ts

@@ -0,0 +1,9 @@
+/** Web twin — one linear URL stack; named stacks don't apply. */
+export function registerStack(_name: string, _frame: unknown): void {}
+export function getStack(_name: string): undefined {
+	return undefined
+}
+
+export function stackEntries(): IterableIterator<[string, never]> {
+	return [].values()
+}